ua.in.hutorny.util
Class CommentRetriever

java.lang.Object
  ua.in.hutorny.util.CommentRetriever

public class CommentRetriever
extends java.lang.Object

CommentRetriever - this class implements reading the content of the comments embraced with /*-- and --*/.
All job is done in a single method retrieve. Other public methods facilitates setting/clearing options ( setOption, setOptions, clrOption, clrOptions), changing patterns ( setStopperPattern, setContentPattern, setDiscriminatorPattern), and changing values to return in different cases ( setBlankValue, setErrorValue, setMessagePrefix ).

Author:

Eugene@hutorny.in.ua

Nested Class Summary

static class	CommentRetriever.BlankContentException
static class	CommentRetriever.FileReadException
static class	CommentRetriever.HeaderIsNotBlankException
static class	CommentRetriever.NoMatchException
static class	CommentRetriever.NoStopperException
static class	CommentRetriever.Option A set of options to opt CommentRetriever behavior - ( THROWERRORS, RETURNERRORS, VOIDERRORS, BLANKISERROR, NODEFAULTS, TRIMRESULT )
static class	CommentRetriever.RetrieverException Descendants of this RetrieverException is thrown when and error occurs and option THROWERRORS is set It extends RuntimeException to avoid try ... catch blocks in the static initializers

Constructor Summary

CommentRetriever()
Constructs CommentRetriever with default options ( RETURNERRORS )

CommentRetriever(CommentRetriever.Option[] options)
Constructs CommentRetriever with provided options

Method Summary

void	clrOption(CommentRetriever.Option opt) Clears option opt.
void	clrOptions(CommentRetriever.Option[] options) Clears all options passed via array using setOption
java.lang.String	getBlankValue()
java.lang.String	getContentPattern()
java.lang.String	getDiscriminatorPattern()
java.lang.String	getErrorValue()
java.util.logging.Logger	getLogger()
java.lang.String	getMessagePrefix()
java.lang.String	getStopperPattern()
boolean	hasOption(CommentRetriever.Option opt) Returns true if queried option is set
java.lang.String	retrieve(java.lang.String discriminator, java.lang.String file, java.lang.String clazz, int line) This method reads the source file from the specified line until the line read contains the stopper pattern --*/.
void	setBlankValue(java.lang.String blankValue) Blank value is returned when there is no other content to return and BLANKISERROR is not set
void	setContentPattern(java.lang.String contentPattern) Sets the content pattern.
void	setDiscriminatorPattern(java.lang.String discriminatorPattern) Sets the discriminator pattern.
void	setErrorValue(java.lang.String errorValue) ErrorValue is returned when option VOIDERRORS is set and an error occured
void	setLogger(java.util.logging.Logger logger)
void	setMessagePrefix(java.lang.String messagePrefix) Message prefix is prepended to an error message if it is returned as the output value
void	setOption(CommentRetriever.Option opt) Sets option opt.
void	setOptions(CommentRetriever.Option[] options) Sets all options passed via array using setOption
void	setStopperPattern(java.lang.String stopperPattern) Sets the stopper pattern.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CommentRetriever

public CommentRetriever()

Constructs CommentRetriever with default options ( RETURNERRORS )

CommentRetriever

public CommentRetriever(CommentRetriever.Option[] options)

Constructs CommentRetriever with provided options

Parameters:

options - see Option

Method Detail

retrieve

public java.lang.String retrieve(java.lang.String discriminator,
                                 java.lang.String file,
                                 java.lang.String clazz,
                                 int line)

This method reads the source file from the specified line until the line read contains the stopper pattern --*/.
Then all read content (the block) is matched against the block pattern and content between /*-- and --*/ is retrieved.
This content is then split by discriminating designators --:<discriminator>. The content before the first designator is treated as the default value.
The content between the current designator and the next designator (or the end of the block) is associated with <discriminator>.
If the discriminator parameter is null or blank, it returns the default value. Otherwise it parses the block and, as it goes, it tests equity of the current discriminator and the discriminator parameter. When they are equal, associated content is returned.
N.B.: Any non-whitespace characters preceding /*-- are treated as an error and signaled according to the actual retriever options ( THROWERRORS, RETURNERRORS).

Parameters:

discriminator - -- a discriminator to look for, if equals("") default value returned, if is null, entire block is returned

file - - file name to read comments from

line - - line number to start from

clazz - - reference to the class that possess resources.

Returns:

comment text as described above

Throws:

CommentRetriever.RetrieverException

java.lang.RuntimeException

setOption

public void setOption(CommentRetriever.Option opt)

Sets option opt.
N.B. Setting VOIDERRORS clears THROWERRORS and RETURNERRORS.

Parameters:

opt -

clrOption

public void clrOption(CommentRetriever.Option opt)

Clears option opt. Clearing VOIDERRORS sets RETURNERRORS

Parameters:

opt -

See Also:

Option

hasOption

public boolean hasOption(CommentRetriever.Option opt)

Returns true if queried option is set

Parameters:

opt -

Returns:

true if option opt is set

setMessagePrefix

public void setMessagePrefix(java.lang.String messagePrefix)

Message prefix is prepended to an error message if it is returned as the output value

Parameters:

messagePrefix -

getMessagePrefix

public java.lang.String getMessagePrefix()

setBlankValue

public void setBlankValue(java.lang.String blankValue)

Blank value is returned when there is no other content to return and BLANKISERROR is not set

Parameters:

blankValue -

getBlankValue

public java.lang.String getBlankValue()

setErrorValue

public void setErrorValue(java.lang.String errorValue)

ErrorValue is returned when option VOIDERRORS is set and an error occured

Parameters:

errorValue -

getErrorValue

public java.lang.String getErrorValue()

setLogger

public void setLogger(java.util.logging.Logger logger)

getLogger

public java.util.logging.Logger getLogger()

setStopperPattern

public void setStopperPattern(java.lang.String stopperPattern)

Sets the stopper pattern. This pattern is searched in the lines read input stream to detect the comment block end

Parameters:

stopperPattern -

Throws:

PatternSyntaxException - see Pattern.compile

java.lang.IllegalArgumentException - see Pattern.compile

getStopperPattern

public java.lang.String getStopperPattern()

setContentPattern

public void setContentPattern(java.lang.String contentPattern)

Sets the content pattern. Comments block read from the input stream is matched against this pattern. The pattern shall have one matching group that matches the content.

Parameters:

contentPattern -

Throws:

PatternSyntaxException - see Pattern.compile

java.lang.IllegalArgumentException - see Pattern.compile

getContentPattern

public java.lang.String getContentPattern()

setDiscriminatorPattern

public void setDiscriminatorPattern(java.lang.String discriminatorPattern)

Sets the discriminator pattern. Comments content is spit by this pattern. The pattern shall have one matching group

Parameters:

discriminatorPattern -

Throws:

PatternSyntaxException - see Pattern.compile

java.lang.IllegalArgumentException - see Pattern.compile

getDiscriminatorPattern

public java.lang.String getDiscriminatorPattern()

setOptions

public final void setOptions(CommentRetriever.Option[] options)

Sets all options passed via array using setOption

Parameters:

options - - array of options to set

clrOptions

public final void clrOptions(CommentRetriever.Option[] options)

Clears all options passed via array using setOption

Parameters:

options - - array of options to set