com.thebuzzmedia.sjxp.rule
Class DefaultRule<T>

java.lang.Object
  extended by com.thebuzzmedia.sjxp.rule.DefaultRule<T>
Type Parameters:
T - The class type of any user-supplied object that the caller wishes to be passed through from one of the XMLParser's parse methods directly to the handler when a rule matches. This is typically a data storage mechanism like a DAO or cache used to store the parsed value in some valuable way, but it can ultimately be anything. If you do not need to make use of the user object, there is no need to parameterize the class.
All Implemented Interfaces:
IRule<T>

public class DefaultRule<T>
extends Object
implements IRule<T>

Class used to provide a default implementation of a rule in SJXP.

It is intended that you only ever need to use this class and not implement your own IRule classes yourself (you are certainly welcome to though).

Rules all consist of the same boiler plate:

All of that rudimentary behavior, along with some nice error-checking and an easy-to-debug and caching toString implementation are provided by this class so you can hit the ground running by simply creating an instance of this class, passing it a location path and provided an implementation for the handler you are interested in.

An example would look like this:

 new DefaultRule(Type.CHARACTER, "/library/book/title") {
        @Override
        public void handleParsedCharacters(XMLParser parser, String text, T userObject) {
                // Handle the title text
        }
 };
 

Instance Reuse

Instances of DefaultRule are immutable and maintain no internal state, so re-using the same DefaultRule among multiple instances of XMLParser is safe.

Author:
Riyad Kalla (software@thebuzzmedia.com)

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.thebuzzmedia.sjxp.rule.IRule
IRule.Type
 
Constructor Summary
DefaultRule(IRule.Type type, String locationPath, String... attributeNames)
          Create a new rule with the given values.
 
Method Summary
 String[] getAttributeNames()
          Used to get a list of attribute names that are to be parsed from the element located at IRule.getLocationPath().
 String getLocationPath()
          Used to get the location path of the element inside the XML document that this rule is interested in.
 IRule.Type getType()
          Used to get the type of the rule.
 void handleParsedAttribute(XMLParser<T> parser, int index, String value, T userObject)
          Default no-op implementation.
 void handleParsedCharacters(XMLParser<T> parser, String text, T userObject)
          Default no-op implementation.
 void handleTag(XMLParser<T> parser, boolean isStartTag, T userObject)
          Default no-op implementation.
 String toString()
          Overridden to provide a nicely formatted representation of the rule for easy debugging.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

DefaultRule

public DefaultRule(IRule.Type type,
                   String locationPath,
                   String... attributeNames)
            throws IllegalArgumentException
Create a new rule with the given values.

Parameters:
type - The type of the rule.
locationPath - The location path of the element to target in the XML.
attributeNames - An optional list of attribute names to parse values for if the type of this rule is IRule.Type.ATTRIBUTE.
Throws:
IllegalArgumentException - if type is null, if locationPath is null or empty, if type is IRule.Type.ATTRIBUTE and attributeNames is null or empty or if type is IRule.Type.CHARACTER and attributeNames is not null or empty.
Method Detail

toString

public String toString()
Overridden to provide a nicely formatted representation of the rule for easy debugging.

As an added bonus, since IRules are intended to be immutable, the result of toString is cached on the first call and the cache returned every time to avoid re-computing the completed String.

Overrides:
toString in class Object
Returns:
a nicely formatted representation of the rule for easy debugging.

getType

public IRule.Type getType()
Description copied from interface: IRule
Used to get the type of the rule.

The XMLParser uses this value to decide when to call this rule to see if it matches the current position inside the doc and how to parse out the values the rule wants.

Specified by:
getType in interface IRule<T>
Returns:
the type of the rule.

getLocationPath

public String getLocationPath()
Description copied from interface: IRule
Used to get the location path of the element inside the XML document that this rule is interested in.

This value is compared literally against the internal path state of the XMLParser to see if they match before processing the rule. If you have a rule that isn't executing, chances are your location path is incorrect or mistyped or it is possible that your location path is correct but you have implemented the wrong handleXXX method so the default no-op one in DefaultRule is getting called.

Namespaces

Please refer to the class notes on the correct format used to define a path element that is namespace-qualified by using brackets.

Namespace qualifiers can be specified for both element paths and attribute names.

Specified by:
getLocationPath in interface IRule<T>
Returns:
the location path of the element inside the XML document that this rule is interested in.

getAttributeNames

public String[] getAttributeNames()
Description copied from interface: IRule
Used to get a list of attribute names that are to be parsed from the element located at IRule.getLocationPath().

If the rule type is IRule.Type.CHARACTER, the attribute name list should be ignored.

Namespaces

Please refer to the class notes on the correct format used to define a path element that is namespace-qualified by using brackets.

Namespace qualifiers can be specified for both element paths and attribute names.

Specified by:
getAttributeNames in interface IRule<T>
Returns:
a list of attribute names that are to be parsed from the element located at IRule.getLocationPath().

handleTag

public void handleTag(XMLParser<T> parser,
                      boolean isStartTag,
                      T userObject)
Default no-op implementation. Please override with your own logic.

Specified by:
handleTag in interface IRule<T>
Parameters:
parser - The source XMLParser currently executing this rule. Providing access to the originating parser is handy if the rule wants to stop parsing by calling XMLParser.stop() .
isStartTag - Used to indicate if this notification is being made because the START_TAG (true) was encountered or the END_TAG (false) was encountered.
userObject - The user-supplied object passed through from the XMLParser's parse method directly to this handler. This is typically a data storage mechanism like a DAO or cache used to hold parsed data or null if you do not need to make use of this pass-through mechanism and passed nothing to the XMLParser when you initiated the parse.
See Also:
IRule.handleTag(XMLParser, boolean, Object)

handleParsedAttribute

public void handleParsedAttribute(XMLParser<T> parser,
                                  int index,
                                  String value,
                                  T userObject)
Default no-op implementation. Please override with your own logic.

Specified by:
handleParsedAttribute in interface IRule<T>
Parameters:
parser - The source XMLParser currently executing this rule. Providing access to the originating parser is handy if the rule wants to stop parsing by calling XMLParser.stop() .
index - The index of the attribute name (from IRule.getAttributeNames()) that this value belongs to.
value - The value for the given attribute.
userObject - The user-supplied object passed through from the XMLParser's parse method directly to this handler. This is typically a data storage mechanism like a DAO or cache used to hold parsed data or null if you do not need to make use of this pass-through mechanism and passed nothing to the XMLParser when you initiated the parse.
See Also:
IRule.handleParsedAttribute(XMLParser, int, String, Object)

handleParsedCharacters

public void handleParsedCharacters(XMLParser<T> parser,
                                   String text,
                                   T userObject)
Default no-op implementation. Please override with your own logic.

Specified by:
handleParsedCharacters in interface IRule<T>
Parameters:
parser - The source XMLParser currently executing this rule. Providing access to the originating parser is handy if the rule wants to stop parsing by calling XMLParser.stop() .
text - The character data contained between the open and close tags described by IRule.getLocationPath().
userObject - The user-supplied object passed through from the XMLParser's parse method directly to this handler. This is typically a data storage mechanism like a DAO or cache used to hold parsed data or null if you do not need to make use of this pass-through mechanism and passed nothing to the XMLParser when you initiated the parse.
See Also:
IRule.handleParsedCharacters(XMLParser, String, Object)

Copyright 2011 The Buzz Media, LLC