org.apache.commons.digester.plugins

Class PluginRules

public class PluginRules extends Object implements Rules

A custom digester Rules manager which must be used as the Rules object when using the plugins module functionality.

During parsing, a linked list of PluginCreateRule instances develop, and this list also acts like a stack. The original instance that was set before the Digester started parsing is always at the tail of the list, and the Digester always holds a reference to the instance at the head of the list in the rules member. Initially, this list/stack holds just one instance, ie head and tail are the same object.

When the start of an xml element causes a PluginCreateRule to fire, a new PluginRules instance is created and inserted at the head of the list (ie pushed onto the stack of Rules objects). Digester.getRules() therefore returns this new Rules object, and any custom rules associated with that plugin are added to that instance.

When the end of the xml element is encountered (and therefore the PluginCreateRule end method fires), the stack of Rules objects is popped, so that Digester.getRules returns the previous Rules object.

Since: 1.6

Field Summary
RulesdecoratedRules
The rules implementation that we are "enhancing" with plugins functionality, as per the Decorator pattern.
protected Digesterdigester
The Digester instance with which this Rules instance is associated.
StringmountPoint
The path below which this rules object has responsibility.
PluginRulesparent
The Rules object that holds rules applying "above" the mountpoint, ie the next Rules object down in the stack.
PluginContextpluginContext
A reference to the object that holds all data which should only exist once per digester instance.
PluginManagerpluginManager
Object which contains information about all known plugins.
RulesFactoryrulesFactory
The (optional) object which generates new rules instances.
Constructor Summary
PluginRules()
Constructor for top-level Rules objects.
PluginRules(Rules decoratedRules)
Constructor for top-level Rules object which handles rule-matching using the specified implementation.
PluginRules(Digester digester, String mountPoint, PluginRules parent, Class pluginClass)
Constructs a Rules instance which has a parent Rules object (which is different from having a delegate rules object).
Method Summary
voidadd(String pattern, Rule rule)
Register a new Rule instance matching the specified pattern.
voidclear()
Clear all rules.
RulesgetDecoratedRules()
This package-scope method is used by the PluginCreateRule class to get direct access to the rules that were dynamically added by the plugin.
DigestergetDigester()
Return the Digester instance with which this instance is associated.
StringgetNamespaceURI()
Return the namespace URI that will be applied to all subsequently added Rule objects.
RulesgetParent()
Return the parent Rules object.
StringgetPluginClassAttr()
StringgetPluginClassAttrNs()
StringgetPluginIdAttr()
StringgetPluginIdAttrNs()
PluginManagergetPluginManager()
Return the object which "knows" about all declared plugins.
ListgetRuleFinders()
RulesFactorygetRulesFactory()
Return the rules factory object (or null if one has not been specified).
Listmatch(String path)
Return a List of all registered Rule instances that match the specified nesting pattern, or a zero-length List if there are no matches.
Listmatch(String namespaceURI, String path)
Return a List of all registered Rule instances that match the specified nodepath, or a zero-length List if there are no matches.
Listrules()
Return the list of rules registered with this object, in the order they were registered with this object.
voidsetDigester(Digester digester)
Set the Digester instance with which this Rules instance is associated.
voidsetNamespaceURI(String namespaceURI)
Set the namespace URI that will be applied to all subsequently added Rule objects.
voidsetPluginClassAttribute(String namespaceUri, String attrName)
voidsetPluginIdAttribute(String namespaceUri, String attrName)
voidsetRuleFinders(List ruleFinders)
voidsetRulesFactory(RulesFactory factory)
Set the object which is used to generate the new Rules instances created to hold and process the rules associated with each plugged-in class.

Field Detail

decoratedRules

private Rules decoratedRules
The rules implementation that we are "enhancing" with plugins functionality, as per the Decorator pattern.

digester

protected Digester digester
The Digester instance with which this Rules instance is associated.

mountPoint

private String mountPoint
The path below which this rules object has responsibility. For paths shorter than or equal the mountpoint, the parent's match is called.

parent

private PluginRules parent
The Rules object that holds rules applying "above" the mountpoint, ie the next Rules object down in the stack.

pluginContext

private PluginContext pluginContext
A reference to the object that holds all data which should only exist once per digester instance.

pluginManager

private PluginManager pluginManager
Object which contains information about all known plugins.

rulesFactory

private RulesFactory rulesFactory
The (optional) object which generates new rules instances.

Constructor Detail

PluginRules

public PluginRules()
Constructor for top-level Rules objects. Exactly one of these must be created and installed into the Digester instance as the Rules object before parsing starts.

PluginRules

public PluginRules(Rules decoratedRules)
Constructor for top-level Rules object which handles rule-matching using the specified implementation.

PluginRules

PluginRules(Digester digester, String mountPoint, PluginRules parent, Class pluginClass)
Constructs a Rules instance which has a parent Rules object (which is different from having a delegate rules object).

One of these is created each time a PluginCreateRule's begin method fires, in order to manage the custom rules associated with whatever concrete plugin class the user has specified.

Parameters: digester is the object this rules will be associated with. mountPoint is the digester match path for the element matching a PluginCreateRule which caused this "nested parsing scope" to begin. This is expected to be equal to digester.getMatch(). parent must be non-null. pluginClass is the plugin class whose custom rules will be loaded into this new PluginRules object.

Method Detail

add

public void add(String pattern, Rule rule)
Register a new Rule instance matching the specified pattern.

Parameters: pattern Nesting pattern to be matched for this Rule. This parameter treats equally patterns that begin with and without a leading slash ('/'). rule Rule instance to be registered

clear

public void clear()
Clear all rules.

getDecoratedRules

Rules getDecoratedRules()
This package-scope method is used by the PluginCreateRule class to get direct access to the rules that were dynamically added by the plugin. No other class should need access to this object.

getDigester

public Digester getDigester()
Return the Digester instance with which this instance is associated.

getNamespaceURI

public String getNamespaceURI()
Return the namespace URI that will be applied to all subsequently added Rule objects.

getParent

public Rules getParent()
Return the parent Rules object.

getPluginClassAttr

public String getPluginClassAttr()
See PluginContext.

getPluginClassAttrNs

public String getPluginClassAttrNs()
See PluginContext.

getPluginIdAttr

public String getPluginIdAttr()
See PluginContext.

getPluginIdAttrNs

public String getPluginIdAttrNs()
See PluginContext.

getPluginManager

public PluginManager getPluginManager()
Return the object which "knows" about all declared plugins.

Returns: The pluginManager value

getRuleFinders

public List getRuleFinders()
See PluginContext.

getRulesFactory

public RulesFactory getRulesFactory()
Return the rules factory object (or null if one has not been specified).

match

public List match(String path)

Deprecated: Call match(namespaceURI,pattern) instead.

Return a List of all registered Rule instances that match the specified nesting pattern, or a zero-length List if there are no matches. If more than one Rule instance matches, they must be returned in the order originally registered through the add() method.

Parameters: path the path to the xml nodes to be matched.

match

public List match(String namespaceURI, String path)
Return a List of all registered Rule instances that match the specified nodepath, or a zero-length List if there are no matches. If more than one Rule instance matches, they must be returned in the order originally registered through the add() method.

Parameters: namespaceURI Namespace URI for which to select matching rules, or null to match regardless of namespace URI path the path to the xml nodes to be matched.

rules

public List rules()
Return the list of rules registered with this object, in the order they were registered with this object.

Note that Rule objects stored in parent Rules objects are not returned by this method.

Returns: list of all Rule objects known to this Rules instance.

setDigester

public void setDigester(Digester digester)
Set the Digester instance with which this Rules instance is associated.

Parameters: digester The newly associated Digester instance

setNamespaceURI

public void setNamespaceURI(String namespaceURI)
Set the namespace URI that will be applied to all subsequently added Rule objects.

Parameters: namespaceURI Namespace URI that must match on all subsequently added rules, or null for matching regardless of the current namespace URI

setPluginClassAttribute

public void setPluginClassAttribute(String namespaceUri, String attrName)
See PluginContext.

setPluginIdAttribute

public void setPluginIdAttribute(String namespaceUri, String attrName)
See PluginContext.

setRuleFinders

public void setRuleFinders(List ruleFinders)
See PluginContext.

setRulesFactory

public void setRulesFactory(RulesFactory factory)
Set the object which is used to generate the new Rules instances created to hold and process the rules associated with each plugged-in class.
Copyright 2001-2005 The Apache Software Foundation.