public abstract class Rule extends Object
Writing a custom Rule is considered perfectly normal when using Digester, and is encouraged whenever the default set of Rule classes don't meet your requirements; the digester framework can help process xml even when the built-in rules aren't quite what is needed. Creating a custom Rule is just as easy as subclassing javax.servlet.http.HttpServlet for webapps, or javax.swing.Action for GUI applications.
If a rule wishes to manipulate a digester stack (the default object stack, a named stack, or the parameter stack) then it should only ever push objects in the rule's begin method and always pop exactly the same number of objects off the stack during the rule's end method. Of course peeking at the objects on the stacks can be done from anywhere.
Rule objects should be stateless, ie they should not update any instance member during the parsing process. A rule instance that changes state will encounter problems if invoked in a "nested" manner; this can happen if the same instance is added to digester multiple times or if a wildcard pattern is used which can match both an element and a child of the same element. The digester object stack and named stacks should be used to store any state that a rule requires, making the rule class safe under all possible uses.
Modifier and Type | Field and Description |
---|---|
protected Digester |
digester
The Digester with which this Rule is associated.
|
protected String |
namespaceURI
The namespace URI for which this Rule is relevant, if any.
|
Constructor and Description |
---|
Rule()
Base constructor.
|
Rule(Digester digester)
Deprecated.
The digester instance is now set in the
Digester.addRule(java.lang.String, org.apache.commons.digester.Rule) method. Use Rule() instead. |
Modifier and Type | Method and Description |
---|---|
void |
begin(Attributes attributes)
Deprecated.
|
void |
begin(String namespace,
String name,
Attributes attributes)
This method is called when the beginning of a matching XML element
is encountered.
|
void |
body(String text)
Deprecated.
|
void |
body(String namespace,
String name,
String text)
This method is called when the body of a matching XML element is
encountered.
|
void |
end()
Deprecated.
|
void |
end(String namespace,
String name)
This method is called when the end of a matching XML element
is encountered.
|
void |
finish()
This method is called after all parsing methods have been
called, to allow Rules to remove temporary data.
|
Digester |
getDigester()
Return the Digester with which this Rule is associated.
|
String |
getNamespaceURI()
Return the namespace URI for which this Rule is relevant, if any.
|
void |
setDigester(Digester digester)
Set the
Digester with which this Rule is associated. |
void |
setNamespaceURI(String namespaceURI)
Set the namespace URI for which this Rule is relevant, if any.
|
protected Digester digester
protected String namespaceURI
public Rule(Digester digester)
Digester.addRule(java.lang.String, org.apache.commons.digester.Rule)
method. Use Rule()
instead.digester
- The digester with which this rule is associatedpublic Rule()
Base constructor. Now the digester will be set when the rule is added.
public Digester getDigester()
public void setDigester(Digester digester)
Digester
with which this Rule
is associated.public String getNamespaceURI()
public void setNamespaceURI(String namespaceURI)
namespaceURI
- Namespace URI for which this Rule is relevant,
or null
to match independent of namespace.public void begin(Attributes attributes) throws Exception
attributes
- The attribute list of this elementException
public void begin(String namespace, String name, Attributes attributes) throws Exception
begin
without the
namespace
and name
parameters, to retain
backwards compatibility.namespace
- the namespace URI of the matching element, or an
empty string if the parser is not namespace aware or the element has
no namespacename
- the local name if the parser is namespace aware, or just
the element name otherwiseattributes
- The attribute list of this elementException
public void body(String text) throws Exception
text
- The text of the body of this elementException
public void body(String namespace, String name, String text) throws Exception
The default implementation delegates to the deprecated method
body
without the namespace
and
name
parameters, to retain backwards compatibility.
namespace
- the namespace URI of the matching element, or an
empty string if the parser is not namespace aware or the element has
no namespacename
- the local name if the parser is namespace aware, or just
the element name otherwisetext
- The text of the body of this elementException
public void end() throws Exception
Exception
public void end(String namespace, String name) throws Exception
end
without the
namespace
and name
parameters, to retain
backwards compatibility.namespace
- the namespace URI of the matching element, or an
empty string if the parser is not namespace aware or the element has
no namespacename
- the local name if the parser is namespace aware, or just
the element name otherwiseException
Copyright © 2001-2014 The Apache Software Foundation. All Rights Reserved.