org.apache.commons.digester
public class Digester extends DefaultHandler
A Digester processes an XML input stream by matching a
series of element nesting patterns to execute Rules that have been added
prior to the start of parsing. This package was inspired by the
XmlMapper
class that was part of Tomcat 3.0 and 3.1,
but is organized somewhat differently.
See the Digester Developer Guide for more information.
IMPLEMENTATION NOTE - A single Digester instance may
only be used within the context of a single thread at a time, and a call
to parse()
must be completed before another can be initiated
even from the same thread.
A Digester instance should not be used for parsing more than one input document. The problem is that the Digester class has quite a few member variables whose values "evolve" as SAX events are received during a parse. When reusing the Digester instance, all these members must be reset back to their initial states before the second parse begins. The "clear()" method makes a stab at resetting these, but it is actually rather a difficult problem. If you are determined to reuse Digester instances, then at the least you should call the clear() method before each parse, and must call it if the Digester parse terminates due to an exception during a parse.
IMPLEMENTATION NOTE - A bug in Xerces 2.0.2 prevents the support of XML schema. You need Xerces 2.1/2.3 and up to make this class working with XML schema
Field Summary | |
---|---|
protected StringBuffer | bodyText
The body text of the current element. |
protected ArrayStack | bodyTexts
The stack of body text string buffers for surrounding elements. |
protected ClassLoader | classLoader
The class loader to use for instantiating application objects.
|
protected boolean | configured
Has this Digester been configured yet. |
protected EntityResolver | entityResolver
The EntityResolver used by the SAX parser. |
protected HashMap | entityValidator
The URLs of entityValidator that have been registered, keyed by the public
identifier that corresponds. |
protected ErrorHandler | errorHandler
The application-supplied error handler that is notified when parsing
warnings, errors, or fatal errors occur. |
protected SAXParserFactory | factory
The SAXParserFactory that is created the first time we need it. |
protected List | inputSources
|
protected String | JAXP_SCHEMA_LANGUAGE |
protected Locator | locator
The Locator associated with our parser. |
protected Log | log
The Log to which most logging calls will be made. |
protected String | match
The current match pattern for nested element processing. |
protected ArrayStack | matches
Stack whose elements are List objects, each containing a list of
Rule objects as returned from Rules.getMatch(). |
protected boolean | namespaceAware
Do we want a "namespace aware" parser. |
protected HashMap | namespaces
Registered namespaces we are currently processing. |
protected ArrayStack | params
The parameters stack being utilized by CallMethodRule and
CallParamRule rules. |
protected SAXParser | parser
The SAXParser we will use to parse the input stream. |
protected String | publicId
The public identifier of the DTD we are currently parsing under
(if any). |
protected XMLReader | reader
The XMLReader used to parse digester rules. |
protected Object | root
The "root" element of the stack (in other words, the last object
that was popped. |
protected Rules | rules
The Rules implementation containing our collection of
Rule instances and associated matching policy. |
protected Log | saxLog
The Log to which all SAX event related logging calls will be made. |
protected String | schemaLanguage
The XML schema language to use for validating an XML instance. |
protected String | schemaLocation
The XML schema to use for validating an XML instance. |
protected ArrayStack | stack
The object stack being constructed. |
protected Substitutor | substitutor
An optional class that substitutes values in attributes and body text.
|
protected boolean | useContextClassLoader
Do we want to use the Context ClassLoader when loading classes
for instantiating new objects. |
protected boolean | validating
Do we want to use a validating parser. |
protected static String | W3C_XML_SCHEMA
The schema language supported. |
Constructor Summary | |
---|---|
Digester()
Construct a new Digester with default properties. | |
Digester(SAXParser parser)
Construct a new Digester, allowing a SAXParser to be passed in. | |
Digester(XMLReader reader)
Construct a new Digester, allowing an XMLReader to be passed in. |
Method Summary | |
---|---|
void | addBeanPropertySetter(String pattern)
Add a "bean property setter" rule for the specified parameters.
|
void | addBeanPropertySetter(String pattern, String propertyName)
Add a "bean property setter" rule for the specified parameters.
|
void | addCallMethod(String pattern, String methodName)
Add an "call method" rule for a method which accepts no arguments.
|
void | addCallMethod(String pattern, String methodName, int paramCount)
Add an "call method" rule for the specified parameters.
|
void | addCallMethod(String pattern, String methodName, int paramCount, String[] paramTypes)
Add an "call method" rule for the specified parameters.
|
void | addCallMethod(String pattern, String methodName, int paramCount, Class[] paramTypes)
Add an "call method" rule for the specified parameters.
|
void | addCallParam(String pattern, int paramIndex)
Add a "call parameter" rule for the specified parameters.
|
void | addCallParam(String pattern, int paramIndex, String attributeName)
Add a "call parameter" rule for the specified parameters.
|
void | addCallParam(String pattern, int paramIndex, boolean fromStack)
Add a "call parameter" rule.
|
void | addCallParam(String pattern, int paramIndex, int stackIndex)
Add a "call parameter" rule that sets a parameter from the stack.
|
void | addCallParamPath(String pattern, int paramIndex)
Add a "call parameter" rule that sets a parameter from the current
Digester matching path.
|
void | addFactoryCreate(String pattern, String className)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, Class clazz)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, String className, String attributeName)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, Class clazz, String attributeName)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, ObjectCreationFactory creationFactory)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, String className, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, Class clazz, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, String className, String attributeName, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, Class clazz, String attributeName, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
|
void | addFactoryCreate(String pattern, ObjectCreationFactory creationFactory, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
|
void | addObjectCreate(String pattern, String className)
Add an "object create" rule for the specified parameters.
|
void | addObjectCreate(String pattern, Class clazz)
Add an "object create" rule for the specified parameters.
|
void | addObjectCreate(String pattern, String className, String attributeName)
Add an "object create" rule for the specified parameters.
|
void | addObjectCreate(String pattern, String attributeName, Class clazz)
Add an "object create" rule for the specified parameters.
|
void | addObjectParam(String pattern, int paramIndex, Object paramObj)
Add a "call parameter" rule that sets a parameter from a
caller-provided object. |
void | addRule(String pattern, Rule rule) Register a new Rule matching the specified pattern. |
void | addRuleSet(RuleSet ruleSet)
Register a set of Rule instances defined in a RuleSet.
|
void | addSetNestedProperties(String pattern)
Adds an SetNestedPropertiesRule.
|
void | addSetNestedProperties(String pattern, String elementName, String propertyName)
Adds an SetNestedPropertiesRule.
|
void | addSetNestedProperties(String pattern, String[] elementNames, String[] propertyNames)
Adds an SetNestedPropertiesRule.
|
void | addSetNext(String pattern, String methodName)
Add a "set next" rule for the specified parameters.
|
void | addSetNext(String pattern, String methodName, String paramType)
Add a "set next" rule for the specified parameters.
|
void | addSetProperties(String pattern)
Add a "set properties" rule for the specified parameters.
|
void | addSetProperties(String pattern, String attributeName, String propertyName)
Add a "set properties" rule with a single overridden parameter.
|
void | addSetProperties(String pattern, String[] attributeNames, String[] propertyNames)
Add a "set properties" rule with overridden parameters.
|
void | addSetProperty(String pattern, String name, String value)
Add a "set property" rule for the specified parameters.
|
void | addSetRoot(String pattern, String methodName)
Add SetRootRule with the specified parameters.
|
void | addSetRoot(String pattern, String methodName, String paramType)
Add SetRootRule with the specified parameters.
|
void | addSetTop(String pattern, String methodName)
Add a "set top" rule for the specified parameters.
|
void | addSetTop(String pattern, String methodName, String paramType)
Add a "set top" rule for the specified parameters.
|
void | characters(char[] buffer, int start, int length)
Process notification of character data received from the body of
an XML element.
|
protected void | cleanup() Clean up allocated resources after parsing is complete. |
void | clear()
Clear the current contents of the default object stack, the param stack,
all named stacks, and other internal variables.
|
protected void | configure()
Provide a hook for lazy configuration of this |
InputSource | createInputSourceFromURL(URL url)
Given a URL, return an InputSource that reads from that URL.
|
InputSource | createInputSourceFromURL(String url) Convenience method that creates an |
SAXException | createSAXException(String message, Exception e)
Create a SAX exception which also understands about the location in
the digester file where the exception occurs
|
SAXException | createSAXException(Exception e)
Create a SAX exception which also understands about the location in
the digester file where the exception occurs
|
SAXException | createSAXException(String message)
Create a SAX exception which also understands about the location in
the digester file where the exception occurs
|
void | endDocument()
Process notification of the end of the document being reached.
|
void | endElement(String namespaceURI, String localName, String qName)
Process notification of the end of an XML element being reached.
|
void | endPrefixMapping(String prefix)
Process notification that a namespace prefix is going out of scope.
|
void | error(SAXParseException exception)
Forward notification of a parsing error to the application supplied
error handler (if any).
|
void | fatalError(SAXParseException exception)
Forward notification of a fatal parsing error to the application
supplied error handler (if any).
|
String | findNamespaceURI(String prefix)
Return the currently mapped namespace URI for the specified prefix,
if any; otherwise return null . |
ClassLoader | getClassLoader()
Return the class loader to be used for instantiating application objects
when required. |
int | getCount()
Return the current depth of the element stack. |
String | getCurrentElementName()
Return the name of the XML element that is currently being processed. |
Map | getCurrentNamespaces()
Get the most current namespaces for all prefixes.
|
ContentHandler | getCustomContentHandler() |
int | getDebug()
Return the debugging detail level of our currently enabled logger.
|
Locator | getDocumentLocator()
Gets the document locator associated with our parser.
|
EntityResolver | getEntityResolver()
Return the Entity Resolver used by the SAX parser. |
ErrorHandler | getErrorHandler()
Return the error handler for this Digester. |
SAXParserFactory | getFactory()
Return the SAXParserFactory we will use, creating one if necessary. |
boolean | getFeature(String feature)
Returns a flag indicating whether the requested feature is supported
by the underlying implementation of org.xml.sax.XMLReader .
|
Log | getLogger()
Return the current Logger associated with this instance of the Digester |
String | getMatch()
Return the current rule match path |
boolean | getNamespaceAware()
Return the "namespace aware" flag for parsers we create. |
SAXParser | getParser()
Return the SAXParser we will use to parse the input stream. |
Object | getProperty(String property)
Return the current value of the specified property for the underlying
XMLReader implementation.
|
String | getPublicId()
Return the public identifier of the DTD we are currently
parsing under, if any. |
XMLReader | getReader()
By setting the reader in the constructor, you can bypass JAXP and
be able to use digester in Weblogic 6.0.
|
Object | getRoot()
Returns the root element of the tree of objects created as a result
of applying the rule objects to the input XML.
|
String | getRuleNamespaceURI()
Return the namespace URI that will be applied to all subsequently
added Rule objects. |
Rules | getRules()
Return the Rules implementation object containing our
rules collection and associated matching policy. |
Log | getSAXLogger()
Gets the logger used for logging SAX-related information.
|
String | getSchema()
Return the XML Schema URI used for validating an XML instance. |
String | getSchemaLanguage()
Return the XML Schema language used when parsing. |
StackAction | getStackAction()
See setStackAction.
|
Substitutor | getSubstitutor()
Gets the Substitutor used to convert attributes and body text. |
boolean | getUseContextClassLoader()
Return the boolean as to whether the context classloader should be used. |
boolean | getValidating()
Return the validating parser flag. |
XMLReader | getXMLReader()
Return the XMLReader to be used for parsing the input document.
|
void | ignorableWhitespace(char[] buffer, int start, int len)
Process notification of ignorable whitespace received from the body of
an XML element.
|
protected void | initialize()
Provides a hook for lazy initialization of this |
boolean | isEmpty(String stackName) Is the stack with the given name empty? |
void | log(String message)
Log a message to our associated logger.
|
void | log(String message, Throwable exception)
Log a message and exception to our associated logger.
|
void | notationDecl(String name, String publicId, String systemId)
Receive notification of a notation declaration event.
|
Object | parse(File file)
Parse the content of the specified file using this Digester. |
Object | parse(InputSource input)
Parse the content of the specified input source using this Digester.
|
Object | parse(InputStream input)
Parse the content of the specified input stream using this Digester.
|
Object | parse(Reader reader)
Parse the content of the specified reader using this Digester.
|
Object | parse(String uri)
Parse the content of the specified URI using this Digester.
|
Object | parse(URL url)
Parse the content of the specified URL using this Digester.
|
Object | peek()
Return the top object on the stack without removing it. |
Object | peek(int n)
Return the n'th object down the stack, where 0 is the top element
and [getCount()-1] is the bottom element. |
Object | peek(String stackName) Gets the top object from the stack with the given name. |
Object | peek(String stackName, int n) Gets the top object from the stack with the given name. |
Object | peekParams() Return the top object on the parameters stack without removing it. |
Object | peekParams(int n) Return the n'th object down the parameters stack, where 0 is the top element and [getCount()-1] is the bottom element. |
Object | pop()
Pop the top object off of the stack, and return it. |
Object | pop(String stackName) Pops (gets and removes) the top object from the stack with the given name. Note: a stack is considered empty if no objects have been pushed onto it yet. |
Object | popParams() Pop the top object off of the parameters stack, and return it. |
void | processingInstruction(String target, String data)
Process notification of a processing instruction that was encountered.
|
void | push(Object object)
Push a new object onto the top of the object stack.
|
void | push(String stackName, Object value)
Pushes the given object onto the stack with the given name.
|
void | pushParams(Object object) Push a new object onto the top of the parameters stack. The parameters stack is used to store |
void | register(String publicId, URL entityURL) Register the specified DTD URL for the specified public identifier. |
void | register(String publicId, String entityURL) Convenience method that registers the string version of an entity URL instead of a URL version. |
void | resetRoot()
This method allows the "root" variable to be reset to null.
|
InputSource | resolveEntity(String publicId, String systemId)
Resolve the requested external entity.
|
void | setClassLoader(ClassLoader classLoader)
Set the class loader to be used for instantiating application objects
when required.
|
void | setCustomContentHandler(ContentHandler handler)
Redirects (or cancels redirecting) of SAX ContentHandler events to an
external object.
|
void | setDebug(int debug)
Set the debugging detail level of our currently enabled logger.
|
void | setDocumentLocator(Locator locator)
Sets the document locator associated with our parser.
|
void | setEntityResolver(EntityResolver entityResolver)
Set the EntityResolver used by SAX when resolving
public id and system id.
|
void | setErrorHandler(ErrorHandler errorHandler)
Set the error handler for this Digester.
|
void | setFeature(String feature, boolean value)
Sets a flag indicating whether the requested feature is supported
by the underlying implementation of org.xml.sax.XMLReader .
|
void | setLogger(Log log)
Set the current logger for this Digester. |
void | setNamespaceAware(boolean namespaceAware)
Set the "namespace aware" flag for parsers we create.
|
void | setProperty(String property, Object value)
Set the current value of the specified property for the underlying
XMLReader implementation.
|
void | setPublicId(String publicId)
Set the publid id of the current file being parse. |
void | setRuleNamespaceURI(String ruleNamespaceURI)
Set the namespace URI that will be applied to all subsequently
added Rule objects.
|
void | setRules(Rules rules)
Set the Rules implementation object containing our
rules collection and associated matching policy.
|
void | setSAXLogger(Log saxLog)
Sets the logger used for logging SAX-related information.
|
void | setSchema(String schemaLocation)
Set the XML Schema URI used for validating the input XML.
|
void | setSchemaLanguage(String schemaLanguage)
Set the XML Schema language used when parsing. |
void | setStackAction(StackAction stackAction)
Define a callback object which is invoked whever an object is pushed onto
a digester object stack, or popped off one.
|
void | setSubstitutor(Substitutor substitutor)
Sets the Substitutor to be used to convert attributes and body text. |
void | setUseContextClassLoader(boolean use)
Determine whether to use the Context ClassLoader (the one found by
calling Thread.currentThread().getContextClassLoader() )
to resolve/load classes that are defined in various rules. |
void | setValidating(boolean validating)
Set the validating parser flag. |
void | skippedEntity(String name)
Process notification of a skipped entity.
|
void | startDocument()
Process notification of the beginning of the document being reached.
|
void | startElement(String namespaceURI, String localName, String qName, Attributes list)
Process notification of the start of an XML element being reached.
|
void | startPrefixMapping(String prefix, String namespaceURI)
Process notification that a namespace prefix is coming in to scope.
|
void | unparsedEntityDecl(String name, String publicId, String systemId, String notation)
Receive notification of an unparsed entity declaration event.
|
void | warning(SAXParseException exception)
Forward notification of a parse warning to the application supplied
error handler (if any).
|
useContextClassLoader
variable.List
of InputSource
instances
created by a createInputSourceFromURL()
method
call. These represent open input streams that need to be
closed to avoid resource leaks, as well as potentially locked
JAR files on Windows.
Deprecated: This is now managed by ParserFeatureSetterFactory
Since: 1.6
Rules
implementation containing our collection of
Rule
instances and associated matching policy. If not
established before the first rule is added, a default implementation
will be provided.W3C_XML_SCHEMA
false
.Parameters: pattern Element matching pattern
See Also: BeanPropertySetterRule
Parameters: pattern Element matching pattern propertyName Name of property to set
See Also: BeanPropertySetterRule
Parameters: pattern Element matching pattern methodName Method name to be called
See Also: CallMethodRule
Parameters: pattern Element matching pattern methodName Method name to be called paramCount Number of expected parameters (or zero for a single parameter from the body of this element)
See Also: CallMethodRule
paramCount
is set to zero the rule will use
the body of the matched element as the single argument of the
method, unless paramTypes
is null or empty, in this
case the rule will call the specified method with no arguments.
Parameters: pattern Element matching pattern methodName Method name to be called paramCount Number of expected parameters (or zero
for a single parameter from the body of this element) paramTypes Set of Java class names for the types
of the expected parameters
(if you wish to use a primitive type, specify the corresonding
Java wrapper class instead, such as java.lang.Boolean
for a boolean
parameter)
See Also: CallMethodRule
paramCount
is set to zero the rule will use
the body of the matched element as the single argument of the
method, unless paramTypes
is null or empty, in this
case the rule will call the specified method with no arguments.
Parameters: pattern Element matching pattern methodName Method name to be called paramCount Number of expected parameters (or zero
for a single parameter from the body of this element) paramTypes The Java class names of the arguments
(if you wish to use a primitive type, specify the corresonding
Java wrapper class instead, such as java.lang.Boolean
for a boolean
parameter)
See Also: CallMethodRule
Parameters: pattern Element matching pattern paramIndex Zero-relative parameter index to set (from the body of this element)
See Also: CallParamRule
Parameters: pattern Element matching pattern paramIndex Zero-relative parameter index to set (from the specified attribute) attributeName Attribute whose value is used as the parameter value
See Also: CallParamRule
Parameters: paramIndex The zero-relative parameter number fromStack Should the call parameter be taken from the top of the stack?
See Also: CallParamRule
Parameters: paramIndex The zero-relative parameter number stackIndex set the call parameter to the stackIndex'th object down the stack, where 0 is the top of the stack, 1 the next element down and so on
See Also: CallMethodRule
Digester
matching path.
This is sometimes useful when using rules that support wildcards.
Parameters: pattern the pattern that this rule should match paramIndex The zero-relative parameter number
See Also: CallMethodRule
Parameters: pattern Element matching pattern className Java class name of the object creation factory class
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern clazz Java class of the object creation factory class
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern className Java class name of the object creation factory class attributeName Attribute name which, if present, overrides the
value specified by className
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern clazz Java class of the object creation factory class attributeName Attribute name which, if present, overrides the
value specified by className
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern creationFactory Previously instantiated ObjectCreationFactory to be utilized
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern className Java class name of the object creation factory class ignoreCreateExceptions when true
any exceptions thrown during
object creation will be ignored.
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern clazz Java class of the object creation factory class ignoreCreateExceptions when true
any exceptions thrown during
object creation will be ignored.
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern className Java class name of the object creation factory class attributeName Attribute name which, if present, overrides the
value specified by className
ignoreCreateExceptions when true
any exceptions thrown during
object creation will be ignored.
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern clazz Java class of the object creation factory class attributeName Attribute name which, if present, overrides the
value specified by className
ignoreCreateExceptions when true
any exceptions thrown during
object creation will be ignored.
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern creationFactory Previously instantiated ObjectCreationFactory
to be utilized ignoreCreateExceptions when true
any exceptions thrown during
object creation will be ignored.
See Also: FactoryCreateRule
Parameters: pattern Element matching pattern className Java class name to be created
See Also: ObjectCreateRule
Parameters: pattern Element matching pattern clazz Java class to be created
See Also: ObjectCreateRule
Parameters: pattern Element matching pattern className Default Java class name to be created attributeName Attribute name that optionally overrides the default Java class name to be created
See Also: ObjectCreateRule
Parameters: pattern Element matching pattern attributeName Attribute name that optionally overrides clazz Default Java class to be created the default Java class name to be created
See Also: ObjectCreateRule
Note that when attempting to locate a matching method to invoke, the true type of the paramObj is used, so that despite the paramObj being passed in here as type Object, the target method can declare its parameters as being the true type of the object (or some ancestor type, according to the usual type-conversion rules).
Parameters: paramIndex The zero-relative parameter number paramObj Any arbitrary object to be passed to the target method.
Since: 1.6
Register a new Rule matching the specified pattern.
This method sets the Digester
property on the rule.
Parameters: pattern Element matching pattern rule Rule to be registered
Parameters: ruleSet The RuleSet instance to configure from
Parameters: pattern register the rule with this pattern elementName elment name that a property maps to propertyName property name of the element mapped from
Since: 1.6
Parameters: pattern register the rule with this pattern elementNames elment names that (in order) map to properties propertyNames property names that (in order) elements are mapped to
Since: 1.6
Parameters: pattern Element matching pattern methodName Method name to call on the parent element
See Also: SetNextRule
Parameters: pattern Element matching pattern methodName Method name to call on the parent element paramType Java class name of the expected parameter type
(if you wish to use a primitive type, specify the corresonding
Java wrapper class instead, such as java.lang.Boolean
for a boolean
parameter)
See Also: SetNextRule
Parameters: pattern Element matching pattern
See Also: SetPropertiesRule
Parameters: pattern Element matching pattern attributeName map this attribute propertyName to this property
See Also: SetPropertiesRule
(String [] attributeNames, String [] propertyNames)
Parameters: pattern Element matching pattern attributeNames names of attributes with custom mappings propertyNames property names these attributes map to
See Also: SetPropertiesRule
Parameters: pattern Element matching pattern name Attribute name containing the property name to be set value Attribute name containing the property value to set
See Also: SetPropertyRule
Parameters: pattern Element matching pattern methodName Method name to call on the root object
See Also: SetRootRule
Parameters: pattern Element matching pattern methodName Method name to call on the root object paramType Java class name of the expected parameter type
See Also: SetRootRule
Parameters: pattern Element matching pattern methodName Method name to call on the parent element
See Also: SetTopRule
Parameters: pattern Element matching pattern methodName Method name to call on the parent element paramType Java class name of the expected parameter type
(if you wish to use a primitive type, specify the corresonding
Java wrapper class instead, such as java.lang.Boolean
for a boolean
parameter)
See Also: SetTopRule
Parameters: buffer The characters from the XML document start Starting offset into the buffer length Number of characters from the buffer
Throws: SAXException if a parsing error is to be reported
Clean up allocated resources after parsing is complete. The
default method closes input streams that have been created by
Digester itself. If you override this method in a subclass, be
sure to call super.cleanup()
to invoke this logic.
Since: 1.8
Calling this method might allow another document of the same type to be correctly parsed. However this method was not intended for this purpose (just to tidy up memory usage). In general, a separate Digester object should be created for each document to be parsed.
Note that this method is called automatically after a document has been successfully parsed by a Digester instance. However it is not invoked automatically when a parse fails, so when reusing a Digester instance (which is not recommended) this method must be called manually after a parse failure.
Provide a hook for lazy configuration of this Digester
instance. The default implementation does nothing, but subclasses
can override as needed.
Note This method may be called more than once. Once only initialization code should be placed in Digester or the code should take responsibility by checking and setting the configured flag.
Ideally this function would not be needed and code could just use
new InputSource(entityURL)
. Unfortunately it appears
that when the entityURL points to a file within a jar archive a
caching mechanism inside the InputSource implementation causes a
file-handle to the jar file to remain open. On Windows systems
this then causes the jar archive file to be locked on disk
("in use") which makes it impossible to delete the jar file -
and that really stuffs up "undeploy" in webapps in particular.
In JDK1.4 and later, Apache XercesJ is used as the xml parser. The InputSource object provided is converted into an XMLInputSource, and eventually passed to an instance of XMLDocumentScannerImpl to specify the source data to be converted into tokens for the rest of the XMLReader code to handle. XMLDocumentScannerImpl calls fEntityManager.startDocumentEntity(source), where fEntityManager is declared in ancestor class XMLScanner to be an XMLEntityManager. In that class, if the input source stream is null, then:
URL location = new URL(expandedSystemId); URLConnection connect = location.openConnection(); if (connect instanceof HttpURLConnection) { setHttpProperties(connect,xmlInputSource); } stream = connect.getInputStream();This method pretty much duplicates the standard behaviour, except that it calls URLConnection.setUseCaches(false) before opening the connection.
Since: 1.8
Convenience method that creates an InputSource
from the string version of a URL.
Parameters: url URL for which to create an InputSource
Since: 1.8
Returns: the new exception
Returns: the new exception
Returns: the new exception
Throws: SAXException if a parsing error is to be reported
Parameters: namespaceURI - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed. localName - The local name (without prefix), or the empty string if Namespace processing is not being performed. qName - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.
Throws: SAXException if a parsing error is to be reported
Parameters: prefix Prefix that is going out of scope
Throws: SAXException if a parsing error is to be reported
Parameters: exception The error information
Throws: SAXException if a parsing exception occurs
Parameters: exception The fatal error information
Throws: SAXException if a parsing exception occurs
null
. These mappings come and
go dynamically as the document is parsed.
Parameters: prefix Prefix to look up
setClassLoader()
, if anyuseContextClassLoader
property is set to trueReturns: Map A map with namespace prefixes as keys and most current namespace URIs for the corresponding prefixes as values
Since: 1.8
Deprecated: This method now always returns 0. Digester uses the apache jakarta commons-logging library; see the documentation for that library for more information.
Return the debugging detail level of our currently enabled logger.Returns: the Locator supplied by the document parser
Returns: Return the Entity Resolver used by the SAX parser.
org.xml.sax.XMLReader
.
See the saxproject website
for information about the standard SAX2 feature flags.
Parameters: feature Name of the feature to inquire about
Throws: ParserConfigurationException if a parser configuration error occurs SAXNotRecognizedException if the property name is not recognized SAXNotSupportedException if the property name is recognized but not supported
null
.XMLReader
implementation.
See the saxproject website
for information about the standard SAX2 properties.
Parameters: property Property name to be retrieved
Throws: SAXNotRecognizedException if the property name is not recognized SAXNotSupportedException if the property name is recognized but not supported
Deprecated: Use getXMLReader() instead, which can throw a SAXException if the reader cannot be instantiated
By setting the reader in the constructor, you can bypass JAXP and be able to use digester in Weblogic 6.0.If the digester stack was "primed" by explicitly pushing a root object onto the stack before parsing started, then that root object is returned here.
Alternatively, if a Rule which creates an object (eg ObjectCreateRule) matched the root element of the xml, then the object created will be returned here.
In other cases, the object most recently pushed onto an empty digester stack is returned. This would be a most unusual use of digester, however; one of the previous configurations is much more likely.
Note that when using one of the Digester.parse methods, the return value from the parse method is exactly the same as the return value from this method. However when the Digester is being used as a SAXContentHandler, no such return value is available; in this case, this method allows you to access the root object that has been created after parsing has completed.
Returns: the root object that has been created after parsing or null if the digester has not parsed any XML yet.
Rule
objects.Rules
implementation object containing our
rules collection and associated matching policy. If none has been
established, a default implementation will be created and returned.Since: 1.6
Since: 1.8
Substitutor
used to convert attributes and body text.Returns: Substitutor, null if not substitutions are to be performed.
Throws: SAXException if no XMLReader can be instantiated
Parameters: buffer The characters from the XML document start Starting offset into the buffer len Number of characters from the buffer
Throws: SAXException if a parsing error is to be reported
Provides a hook for lazy initialization of this Digester
instance.
The default implementation does nothing, but subclasses
can override as needed.
Digester (by default) only calls this method once.
Note This method will be called by Digester
only when the configured flag is false.
Subclasses that override configure
or who set configured
may find that this method may be called more than once.
Since: 1.6
Is the stack with the given name empty?
Note: a stack is considered empty if no objects have been pushed onto it yet.
Parameters: stackName the name of the stack whose emptiness should be evaluated
Returns: true if the given stack if empty
Since: 1.6
Deprecated: Call getLogger() and use it's logging methods
Log a message to our associated logger.Parameters: message The message to be logged
Deprecated: Call getLogger() and use it's logging methods
Log a message and exception to our associated logger.Parameters: message The message to be logged
Parameters: name The notation name publicId The public identifier (if any) systemId The system identifier (if any)
Parameters: file File containing the XML data to be parsed
Throws: IOException if an input/output error occurs SAXException if a parsing exception occurs
Parameters: input Input source containing the XML data to be parsed
Throws: IOException if an input/output error occurs SAXException if a parsing exception occurs
Parameters: input Input stream containing the XML data to be parsed
Throws: IOException if an input/output error occurs SAXException if a parsing exception occurs
Parameters: reader Reader containing the XML data to be parsed
Throws: IOException if an input/output error occurs SAXException if a parsing exception occurs
Parameters: uri URI containing the XML data to be parsed
Throws: IOException if an input/output error occurs SAXException if a parsing exception occurs
Parameters: url URL containing the XML data to be parsed
Throws: IOException if an input/output error occurs SAXException if a parsing exception occurs
Since: 1.8
null
.null
.
Parameters: n Index of the desired element, where 0 is the top of the stack, 1 is the next element down, and so on.
Gets the top object from the stack with the given name. This method does not remove the object from the stack.
Note: a stack is considered empty if no objects have been pushed onto it yet.
Parameters: stackName the name of the stack to be peeked
Returns: the top Object
on the stack or null if the stack is either
empty or has not been created yet
Throws: EmptyStackException if the named stack is empty
Since: 1.6
Gets the top object from the stack with the given name. This method does not remove the object from the stack.
Note: a stack is considered empty if no objects have been pushed onto it yet.
Parameters: stackName the name of the stack to be peeked n Index of the desired element, where 0 is the top of the stack, 1 is the next element down, and so on.
Returns: the specified Object
on the stack.
Throws: EmptyStackException if the named stack is empty
Since: 1.6
Return the top object on the parameters stack without removing it. If there are
no objects on the stack, return null
.
The parameters stack is used to store CallMethodRule
parameters.
See params.
Return the n'th object down the parameters stack, where 0 is the top element
and [getCount()-1] is the bottom element. If the specified index
is out of range, return null
.
The parameters stack is used to store CallMethodRule
parameters.
See params.
Parameters: n Index of the desired element, where 0 is the top of the stack, 1 is the next element down, and so on.
null
.Pops (gets and removes) the top object from the stack with the given name.
Note: a stack is considered empty if no objects have been pushed onto it yet.
Parameters: stackName the name of the stack from which the top value is to be popped.
Returns: the top Object
on the stack or or null if the stack is either
empty or has not been created yet
Throws: EmptyStackException if the named stack is empty
Since: 1.6
Pop the top object off of the parameters stack, and return it. If there are
no objects on the stack, return null
.
The parameters stack is used to store CallMethodRule
parameters.
See params.
Parameters: target The processing instruction target data The processing instruction data (if any)
Throws: SAXException if a parsing error is to be reported
Parameters: object The new object
Parameters: stackName the name of the stack onto which the object should be pushed value the Object to be pushed onto the named stack.
Since: 1.6
Push a new object onto the top of the parameters stack.
The parameters stack is used to store CallMethodRule
parameters.
See params.
Parameters: object The new object
Register the specified DTD URL for the specified public identifier.
This must be called before the first call to parse()
.
Digester
contains an internal EntityResolver
implementation. This maps PUBLICID
's to URLs
(from which the resource will be loaded). A common use case for this
method is to register local URLs (possibly computed at runtime by a
classloader) for DTDs. This allows the performance advantage of using
a local version without having to ensure every SYSTEM
URI on every processed xml document is local. This implementation provides
only basic functionality. If more sophisticated features are required,
using Digester to set a custom resolver is recommended.
Note: This method will have no effect when a custom
EntityResolver
has been set. (Setting a custom
EntityResolver
overrides the internal implementation.)
Parameters: publicId Public identifier of the DTD to be resolved entityURL The URL to use for reading this DTD
Since: 1.8
Convenience method that registers the string version of an entity URL instead of a URL version.
Parameters: publicId Public identifier of the entity to be resolved entityURL The URL to use for reading this entity
It is not considered safe for a digester instance to be reused to parse multiple xml documents. However if you are determined to do so, then you should call both clear() and resetRoot() before each parse.
Since: 1.7
Parameters: publicId The public identifier of the entity being referenced systemId The system identifier of the entity being referenced
Throws: SAXException if a parsing exception occurs
Parameters: classLoader The new class loader to use, or null
to revert to the standard rules
When this object's customContentHandler is non-null, any SAX events received from the parser will simply be passed on to the specified object instead of this object handling them. This allows Rule classes to take control of the SAX event stream for a while in order to do custom processing. Such a rule should save the old value before setting a new one, and restore the old value in order to resume normal digester processing.
An example of a Rule which needs this feature is NodeCreateRule.
Note that saving the old value is probably not needed as it should always be null; a custom rule that wants to take control could only have been called when there was no custom content handler. But it seems cleaner to properly save/restore the value and maybe some day this will come in useful.
Note also that this is not quite equivalent to
digester.getXMLReader().setContentHandler(handler)for these reasons:
Since: 1.7
Deprecated: This method now has no effect at all. Digester uses the apache jakarta comons-logging library; see the documentation for that library for more information.
Set the debugging detail level of our currently enabled logger.Parameters: debug New debugging detail level (0=off, increasing integers for more detail)
Parameters: locator The new locator
EntityResolver
used by SAX when resolving
public id and system id.
This must be called before the first call to parse()
.Parameters: entityResolver a class that implement the EntityResolver
interface.
Parameters: errorHandler The new error handler
org.xml.sax.XMLReader
.
See the saxproject website
for information about the standard SAX2 feature flags. In order to be
effective, this method must be called before the
getParser()
method is called for the first time, either
directly or indirectly.
Parameters: feature Name of the feature to set the status for value The new value for this feature
Throws: ParserConfigurationException if a parser configuration error occurs SAXNotRecognizedException if the property name is not recognized SAXNotSupportedException if the property name is recognized but not supported
Parameters: namespaceAware The new "namespace aware" flag
XMLReader
implementation.
See the saxproject website
for information about the standard SAX2 properties.
Parameters: property Property name to be set value Property value to be set
Throws: SAXNotRecognizedException if the property name is not recognized SAXNotSupportedException if the property name is recognized but not supported
Parameters: publicId the DTD/Schema public's id.
Rule
objects.
Parameters: ruleNamespaceURI Namespace URI that must match on all
subsequently added rules, or null
for matching
regardless of the current namespace URI
Rules
implementation object containing our
rules collection and associated matching policy.
Parameters: rules New Rules implementation
Parameters: saxLog Log, not null
Since: 1.6
It is often desirable to force the input document to be validated against a particular schema regardless of what type the input document declares itself to be. This method allows that to be done.
Note, however, that there is no standard API for enabling this feature on the underlying SAX parser; this method therefore only works for those parsers explicitly supported by Digester's ParserFeatureSetterFactory class. If the underlying parser does not support the feature, or is not one of the supported parsers, then an exception will be thrown when getParser is called (explicitly, or implicitly via the parse method).
See also method setSchemaLanguage which allows the type of the schema specified here to be defined. By default, the schema is expected to be a W3C xml schema definition.
IMPORTANT NOTE: This functionality was never very reliable, and has been horribly broken since the 1.6 release of Digester. There are currently no plans to fix it, so you are strongly recommended to avoid using this method. Instead, create an XMLParser instance yourself, configure validation appropriately, and pass it as a parameter to the Digester constructor.
Parameters: schemaLocation a URI to the schema.
Parameters: schemaLanguage a URI to the schema language.
Since: 1.8
Substitutor
to be used to convert attributes and body text.Parameters: substitutor the Substitutor to be used to convert attributes and body text or null if not substitution of these values is to be performed.
Thread.currentThread().getContextClassLoader()
)
to resolve/load classes that are defined in various rules. If not
using Context ClassLoader, then the class-loading defaults to
using the calling-class' ClassLoader.
Parameters: use determines whether to use Context ClassLoader.
parse()
is called the first time.
Parameters: validating The new validating parser flag.
Parameters: name Name of the skipped entity
Throws: SAXException if a parsing error is to be reported
Throws: SAXException if a parsing error is to be reported
Parameters: namespaceURI The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed. localName The local name (without prefix), or the empty string if Namespace processing is not being performed. qName The qualified name (with prefix), or the empty string if qualified names are not available.\ list The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
Throws: SAXException if a parsing error is to be reported
Parameters: prefix Prefix that is being declared namespaceURI Corresponding namespace URI being mapped to
Throws: SAXException if a parsing error is to be reported
Parameters: name The unparsed entity name publicId The public identifier (if any) systemId The system identifier (if any) notation The name of the associated notation
Parameters: exception The warning information
Throws: SAXException if a parsing exception occurs