org.apache.commons.digester.plugins
Class PluginCreateRule

java.lang.Object
  |
  +--org.apache.commons.digester.Rule
        |
        +--org.apache.commons.digester.plugins.PluginCreateRule

All Implemented Interfaces:

InitializableRule

public class PluginCreateRule

extends Rule

implements InitializableRule

Allows the original rules for parsing the configuration file to define points at which plugins are allowed, by configuring a PluginCreateRule with the appropriate pattern.

Since:

1.6

Field Summary

private java.lang.Class	baseClass A base class that any plugin must derive from.
private Declaration	defaultPlugin Info about optional default plugin to be used if no plugin-id is specified in the input data.
private PluginConfigurationException	initException Currently, none of the Rules methods allow exceptions to be thrown.
private java.lang.String	pattern In order to invoke the addRules method on the plugin class correctly, we need to know the pattern which this rule is matched by.
private java.lang.String	pluginClassAttr
private java.lang.String	pluginClassAttrNs
private java.lang.String	pluginIdAttr
private java.lang.String	pluginIdAttrNs

Fields inherited from class org.apache.commons.digester.Rule

digester, namespaceURI

Constructor Summary

PluginCreateRule(java.lang.Class baseClass)
Create a plugin rule where the user must specify a plugin-class or plugin-id.

PluginCreateRule(java.lang.Class baseClass, java.lang.Class dfltPluginClass)
Create a plugin rule where the user may specify a plugin.

PluginCreateRule(java.lang.Class baseClass, java.lang.Class dfltPluginClass, RuleLoader dfltPluginRuleLoader)
Create a plugin rule where the user may specify a plugin.

Method Summary

void	begin(java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes attributes) Invoked when the Digester matches this rule against an xml element.
void	body(java.lang.String namespace, java.lang.String name, java.lang.String text) Process the body text of this element.
void	end(java.lang.String namespace, java.lang.String name) Invoked by the digester when the closing tag matching this Rule's pattern is encountered.
void	fireBeginMethods(java.util.List rules, java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes list) Duplicate the processing that the Digester does when firing the begin methods of rules.
private void	fireBodyMethods(java.util.List rules, java.lang.String namespaceURI, java.lang.String name, java.lang.String text) Duplicate the processing that the Digester does when firing the body methods of rules.
void	fireEndMethods(java.util.List rules, java.lang.String namespaceURI, java.lang.String name) Duplicate the processing that the Digester does when firing the end methods of rules.
java.lang.String	getPattern() Return the pattern that this Rule is associated with.
void	postRegisterInit(java.lang.String matchPattern) Invoked after this rule has been added to the set of digester rules, associated with the specified pattern.
void	setPluginClassAttribute(java.lang.String namespaceUri, java.lang.String attrName) Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which class should be instantiated.
void	setPluginIdAttribute(java.lang.String namespaceUri, java.lang.String attrName) Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which plugin declaration is being referenced.

Methods inherited from class org.apache.commons.digester.Rule

begin, body, end, finish, getDigester, getNamespaceURI, setDigester, setNamespaceURI

Methods inherited from class java.lang.Object

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

Field Detail

pluginClassAttrNs

private java.lang.String pluginClassAttrNs

pluginClassAttr

private java.lang.String pluginClassAttr

pluginIdAttrNs

private java.lang.String pluginIdAttrNs

pluginIdAttr

private java.lang.String pluginIdAttr

pattern

private java.lang.String pattern

In order to invoke the addRules method on the plugin class correctly, we need to know the pattern which this rule is matched by.

baseClass

private java.lang.Class baseClass

A base class that any plugin must derive from.

defaultPlugin

private Declaration defaultPlugin

Info about optional default plugin to be used if no plugin-id is specified in the input data. This can simplify the syntax where one particular plugin is usually used.

initException

private PluginConfigurationException initException

Currently, none of the Rules methods allow exceptions to be thrown. Therefore if this class cannot initialise itself properly, it cannot cause the digester to stop. Instead, we cache the exception and throw it the first time the begin() method is called.

Constructor Detail

PluginCreateRule

public PluginCreateRule(java.lang.Class baseClass)

Create a plugin rule where the user must specify a plugin-class or plugin-id.

Parameters:

baseClass - is the class which any specified plugin must be descended from.

PluginCreateRule

public PluginCreateRule(java.lang.Class baseClass,
                        java.lang.Class dfltPluginClass)

Create a plugin rule where the user may specify a plugin. If the user doesn't specify a plugin, then the default class specified in this constructor is used.

Parameters:

baseClass - is the class which any specified plugin must be descended from.

dfltPluginClass - is the class which will be used if the user doesn't specify any plugin-class or plugin-id. This class will have custom rules installed for it just like a declared plugin.

PluginCreateRule

public PluginCreateRule(java.lang.Class baseClass,
                        java.lang.Class dfltPluginClass,
                        RuleLoader dfltPluginRuleLoader)

Create a plugin rule where the user may specify a plugin. If the user doesn't specify a plugin, then the default class specified in this constructor is used.

Parameters:

baseClass - is the class which any specified plugin must be descended from.

dfltPluginClass - is the class which will be used if the user doesn't specify any plugin-class or plugin-id. This class will have custom rules installed for it just like a declared plugin.

dfltPluginRuleLoader - is a RuleLoader instance which knows how to load the custom rules associated with this default plugin.

Method Detail

setPluginClassAttribute

public void setPluginClassAttribute(java.lang.String namespaceUri,
                                    java.lang.String attrName)

Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which class should be instantiated.

See PluginRules.setPluginClassAttribute(java.lang.String, java.lang.String) for more info.

setPluginIdAttribute

public void setPluginIdAttribute(java.lang.String namespaceUri,
                                 java.lang.String attrName)

Sets the xml attribute which the input xml uses to indicate to a PluginCreateRule which plugin declaration is being referenced.

See PluginRules.setPluginIdAttribute(java.lang.String, java.lang.String) for more info.

postRegisterInit

public void postRegisterInit(java.lang.String matchPattern)
                      throws PluginConfigurationException

Invoked after this rule has been added to the set of digester rules, associated with the specified pattern. Check all configuration data is valid and remember the pattern for later.

Specified by:

postRegisterInit in interface InitializableRule

Parameters:

matchPattern - is the digester match pattern that is associated with this rule instance, eg "root/widget".

Throws:

PluginConfigurationException

begin

public void begin(java.lang.String namespace,
                  java.lang.String name,
                  org.xml.sax.Attributes attributes)
           throws java.lang.Exception

Invoked when the Digester matches this rule against an xml element.

A new instance of the target class is created, and pushed onto the stack. A new "private" PluginRules object is then created and set as the digester's default Rules object. Any custom rules associated with the plugin class are then loaded into that new Rules object. Finally, any custom rules that are associated with the current pattern (such as SetPropertiesRules) have their begin methods executed.

Overrides:

begin in class Rule

Parameters:

namespace -

name -

attributes -

Throws:

java.lang.ClassNotFoundException

PluginInvalidInputException

PluginConfigurationException

java.lang.Exception

body

public void body(java.lang.String namespace,
                 java.lang.String name,
                 java.lang.String text)
          throws java.lang.Exception

Process the body text of this element.

Overrides:

body in class Rule

Parameters:

text - The body text of this element

namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace

name - the local name if the parser is namespace aware, or just the element name otherwise

java.lang.Exception

end

public void end(java.lang.String namespace,
                java.lang.String name)
         throws java.lang.Exception

Invoked by the digester when the closing tag matching this Rule's pattern is encountered.

Overrides:

end in class Rule

Parameters:

namespace - Description of the Parameter

name - Description of the Parameter

Throws:

java.lang.Exception - Description of the Exception

See Also:

begin(java.lang.String, java.lang.String, org.xml.sax.Attributes)

getPattern

public java.lang.String getPattern()

Return the pattern that this Rule is associated with.

In general, Rule instances can be associated with multiple patterns. A PluginCreateRule, however, will only function correctly when associated with a single pattern. It is possible to fix this, but I can't be bothered just now because this feature is unlikely to be used.

Returns:

The pattern value

fireBeginMethods

public void fireBeginMethods(java.util.List rules,
                             java.lang.String namespace,
                             java.lang.String name,
                             org.xml.sax.Attributes list)
                      throws java.lang.Exception

Duplicate the processing that the Digester does when firing the begin methods of rules. It would be really nice if the Digester class provided a way for this functionality to just be invoked directly.

java.lang.Exception

fireBodyMethods

private void fireBodyMethods(java.util.List rules,
                             java.lang.String namespaceURI,
                             java.lang.String name,
                             java.lang.String text)
                      throws java.lang.Exception

Duplicate the processing that the Digester does when firing the body methods of rules. It would be really nice if the Digester class provided a way for this functionality to just be invoked directly.

java.lang.Exception

fireEndMethods

public void fireEndMethods(java.util.List rules,
                           java.lang.String namespaceURI,
                           java.lang.String name)
                    throws java.lang.Exception

Duplicate the processing that the Digester does when firing the end methods of rules. It would be really nice if the Digester class provided a way for this functionality to just be invoked directly.

java.lang.Exception