Class Digester
- java.lang.Object
-
- org.xml.sax.helpers.DefaultHandler
-
- org.apache.commons.digester3.Digester
-
- All Implemented Interfaces:
org.xml.sax.ContentHandler
,org.xml.sax.DTDHandler
,org.xml.sax.EntityResolver
,org.xml.sax.ErrorHandler
public class Digester extends org.xml.sax.helpers.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.
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.
LEGACY IMPLEMENTATION NOTE - When using the legacy XML schema support (instead of using the
Schema
class), 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 work with the legacy XML schema support.This package was inspired by the
XmlMapper
class that was part of Tomcat 3.0 and 3.1, but is organized somewhat differently.
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.StringBuilder
bodyText
The body text of the current element.private java.util.Stack<java.lang.StringBuilder>
bodyTexts
The stack of body text string buffers for surrounding elements.private java.lang.ClassLoader
classLoader
The class loader to use for instantiating application objects.private boolean
configured
Has this Digester been configured yet.private org.xml.sax.ContentHandler
customContentHandler
If not null, then calls by the parser to this object's characters, startElement, endElement and processingInstruction methods are forwarded to the specified object.private org.xml.sax.EntityResolver
entityResolver
The EntityResolver used by the SAX parser.private java.util.HashMap<java.lang.String,java.net.URL>
entityValidator
The URLs of entityValidator that have been registered, keyed by the public identifier that corresponds.private org.xml.sax.ErrorHandler
errorHandler
The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.private java.util.concurrent.ExecutorService
executorService
The executor service to run asynchronous parse method.private javax.xml.parsers.SAXParserFactory
factory
The SAXParserFactory that is created the first time we need it.protected java.util.List<org.xml.sax.InputSource>
inputSources
List
ofInputSource
instances created by acreateInputSourceFromURL()
method call.private org.xml.sax.Locator
locator
The Locator associated with our parser.private org.apache.commons.logging.Log
log
The Log to which most logging calls will be made.private java.lang.String
match
The current match pattern for nested element processing.private java.util.Stack<java.util.List<Rule>>
matches
Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().private boolean
namespaceAware
Do we want a "namespace aware" parser.private java.util.HashMap<java.lang.String,java.util.Stack<java.lang.String>>
namespaces
Registered namespaces we are currently processing.private java.util.Stack<java.lang.Object[]>
params
The parameters stack being utilized by CallMethodRule and CallParamRule rules.private javax.xml.parsers.SAXParser
parser
The SAXParser we will use to parse the input stream.private java.lang.String
publicId
The public identifier of the DTD we are currently parsing under (if any).private org.xml.sax.XMLReader
reader
The XMLReader used to parse digester rules.private java.lang.Object
root
The "root" element of the stack (in other words, the last object that was popped.private Rules
rules
TheRules
implementation containing our collection ofRule
instances and associated matching policy.private org.apache.commons.logging.Log
saxLog
The Log to which all SAX event related logging calls will be made.private javax.xml.validation.Schema
schema
The XML schema to use for validating an XML instance.private java.util.Stack<java.lang.Object>
stack
The object stack being constructed.private StackAction
stackAction
Object which will receive callbacks for every pop/push action on the default stack or named stacks.private java.util.HashMap<java.lang.String,java.util.Stack<java.lang.Object>>
stacksByName
Stacks used for interrule communication, indexed by name Stringprivate Substitutor
substitutor
An optional class that substitutes values in attributes and body text.private boolean
useContextClassLoader
Do we want to use the Context ClassLoader when loading classes for instantiating new objects.private boolean
validating
Do we want to use a validating parser.protected static java.lang.String
W3C_XML_SCHEMA
The schema language supported.private boolean
xincludeAware
Do we want a "XInclude aware" parser.
-
Constructor Summary
Constructors Constructor Description Digester()
Construct a new Digester with default properties.Digester(javax.xml.parsers.SAXParser parser)
Construct a new Digester, allowing a SAXParser to be passed in.Digester(org.xml.sax.XMLReader reader)
Construct a new Digester, allowing an XMLReader to be passed in.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addBeanPropertySetter(java.lang.String pattern)
Add a "bean property setter" rule for the specified parameters.void
addBeanPropertySetter(java.lang.String pattern, java.lang.String propertyName)
Add a "bean property setter" rule for the specified parameters.void
addCallMethod(java.lang.String pattern, java.lang.String methodName)
Add an "call method" rule for a method which accepts no arguments.void
addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount)
Add an "call method" rule for the specified parameters.void
addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.Class<?>[] paramTypes)
Add an "call method" rule for the specified parameters.void
addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Add an "call method" rule for the specified parameters.void
addCallParam(java.lang.String pattern, int paramIndex)
Add a "call parameter" rule for the specified parameters.void
addCallParam(java.lang.String pattern, int paramIndex, boolean fromStack)
Add a "call parameter" rule.void
addCallParam(java.lang.String pattern, int paramIndex, int stackIndex)
Add a "call parameter" rule that sets a parameter from the stack.void
addCallParam(java.lang.String pattern, int paramIndex, java.lang.String attributeName)
Add a "call parameter" rule for the specified parameters.void
addCallParamPath(java.lang.String pattern, int paramIndex)
Add a "call parameter" rule that sets a parameter from the currentDigester
matching path.void
addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, java.lang.String attributeName)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, java.lang.String attributeName, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, java.lang.String className)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, java.lang.String className, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, java.lang.String className, java.lang.String attributeName)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, java.lang.String className, java.lang.String attributeName, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, ObjectCreationFactory<?> creationFactory)
Add a "factory create" rule for the specified parameters.void
addFactoryCreate(java.lang.String pattern, ObjectCreationFactory<?> creationFactory, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.void
addObjectCreate(java.lang.String pattern, java.lang.Class<?> clazz)
Add an "object create" rule for the specified parameters.void
addObjectCreate(java.lang.String pattern, java.lang.String className)
Add an "object create" rule for the specified parameters.void
addObjectCreate(java.lang.String pattern, java.lang.String attributeName, java.lang.Class<?> clazz)
Add an "object create" rule for the specified parameters.void
addObjectCreate(java.lang.String pattern, java.lang.String className, java.lang.String attributeName)
Add an "object create" rule for the specified parameters.void
addObjectParam(java.lang.String pattern, int paramIndex, java.lang.Object paramObj)
Add a "call parameter" rule that sets a parameter from a caller-provided object.void
addRule(java.lang.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(java.lang.String pattern)
Adds anSetNestedPropertiesRule
.void
addSetNestedProperties(java.lang.String pattern, java.lang.String[] elementNames, java.lang.String[] propertyNames)
Adds anSetNestedPropertiesRule
.void
addSetNestedProperties(java.lang.String pattern, java.lang.String elementName, java.lang.String propertyName)
Adds anSetNestedPropertiesRule
.void
addSetNext(java.lang.String pattern, java.lang.String methodName)
Add a "set next" rule for the specified parameters.void
addSetNext(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
Add a "set next" rule for the specified parameters.void
addSetProperties(java.lang.String pattern)
Add a "set properties" rule for the specified parameters.void
addSetProperties(java.lang.String pattern, java.lang.String[] attributeNames, java.lang.String[] propertyNames)
Add a "set properties" rule with overridden parameters.void
addSetProperties(java.lang.String pattern, java.lang.String attributeName, java.lang.String propertyName)
Add a "set properties" rule with a single overridden parameter.void
addSetProperty(java.lang.String pattern, java.lang.String name, java.lang.String value)
Add a "set property" rule for the specified parameters.void
addSetRoot(java.lang.String pattern, java.lang.String methodName)
AddSetRootRule
with the specified parameters.void
addSetRoot(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
AddSetRootRule
with the specified parameters.void
addSetTop(java.lang.String pattern, java.lang.String methodName)
Add a "set top" rule for the specified parameters.void
addSetTop(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
Add a "set top" rule for the specified parameters.<T> java.util.concurrent.Future<T>
asyncParse(java.io.File file)
Creates a Callable instance that parse the content of the specified reader using this Digester.<T> java.util.concurrent.Future<T>
asyncParse(java.io.InputStream input)
Creates a Callable instance that parse the content of the specified reader using this Digester.<T> java.util.concurrent.Future<T>
asyncParse(java.io.Reader reader)
Creates a Callable instance that parse the content of the specified reader using this Digester.<T> java.util.concurrent.Future<T>
asyncParse(java.lang.String uri)
Creates a Callable instance that parse the content of the specified reader using this Digester.<T> java.util.concurrent.Future<T>
asyncParse(java.net.URL url)
Creates a Callable instance that parse the content of the specified reader using this Digester.private <T> java.util.concurrent.Future<T>
asyncParse(java.util.concurrent.Callable<T> callable)
Execute the parse in async mode.<T> java.util.concurrent.Future<T>
asyncParse(org.xml.sax.InputSource input)
Creates a Callable instance that parse the content of the specified reader using this Digester.void
characters(char[] buffer, int start, int length)
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 thisDigester
instance.org.xml.sax.InputSource
createInputSourceFromURL(java.lang.String url)
Convenience method that creates anInputSource
from the string version of a URL.org.xml.sax.InputSource
createInputSourceFromURL(java.net.URL url)
Given a URL, return an InputSource that reads from that URL.org.xml.sax.SAXException
createSAXException(java.lang.Exception e)
Create a SAX exception which also understands about the location in the digester file where the exception occursorg.xml.sax.SAXException
createSAXException(java.lang.String message)
Create a SAX exception which also understands about the location in the digester file where the exception occursorg.xml.sax.SAXException
createSAXException(java.lang.String message, java.lang.Exception e)
Create a SAX exception which also understands about the location in the digester file where the exception occursvoid
endDocument()
void
endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)
void
endPrefixMapping(java.lang.String prefix)
void
error(org.xml.sax.SAXParseException exception)
void
fatalError(org.xml.sax.SAXParseException exception)
java.lang.String
findNamespaceURI(java.lang.String prefix)
Return the currently mapped namespace URI for the specified prefix, if any; otherwise returnnull
.java.lang.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.java.lang.String
getCurrentElementName()
Return the name of the XML element that is currently being processed.java.util.Map<java.lang.String,java.lang.String>
getCurrentNamespaces()
Get the most current namespaces for all prefixes.org.xml.sax.ContentHandler
getCustomContentHandler()
returns the custom SAX ContentHandler where events are redirected.org.xml.sax.Locator
getDocumentLocator()
Gets the document locator associated with our parser.org.xml.sax.EntityResolver
getEntityResolver()
Return the Entity Resolver used by the SAX parser.org.xml.sax.ErrorHandler
getErrorHandler()
Return the error handler for this Digester.java.util.concurrent.ExecutorService
getExecutorService()
Returns the executor service used to run asynchronous parse method.javax.xml.parsers.SAXParserFactory
getFactory()
Return the SAXParserFactory we will use, creating one if necessary.boolean
getFeature(java.lang.String feature)
Returns a flag indicating whether the requested feature is supported by the underlying implementation oforg.xml.sax.XMLReader
.org.apache.commons.logging.Log
getLogger()
Return the current Logger associated with this instance of the Digesterjava.lang.String
getMatch()
Return the current rule match pathjava.util.Stack<java.util.List<Rule>>
getMatches()
Return a Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().boolean
getNamespaceAware()
Return the "namespace aware" flag for parsers we create.javax.xml.parsers.SAXParser
getParser()
Return the SAXParser we will use to parse the input stream.java.lang.Object
getProperty(java.lang.String property)
Return the current value of the specified property for the underlyingXMLReader
implementation.java.lang.String
getPublicId()
Return the public identifier of the DTD we are currently parsing under, if any.(package private) java.util.Map<java.lang.String,java.net.URL>
getRegistrations()
Return the set of DTD URL registrations, keyed by public identifier.<T> T
getRoot()
Returns the root element of the tree of objects created as a result of applying the rule objects to the input XML.java.lang.String
getRuleNamespaceURI()
Return the namespace URI that will be applied to all subsequently addedRule
objects.Rules
getRules()
Return theRules
implementation object containing our rules collection and associated matching policy.org.apache.commons.logging.Log
getSAXLogger()
Gets the logger used for logging SAX-related information.StackAction
getStackAction()
Return the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.Substitutor
getSubstitutor()
Gets theSubstitutor
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.boolean
getXIncludeAware()
Return the XInclude-aware flag for parsers we create.org.xml.sax.XMLReader
getXMLReader()
Return the XMLReader to be used for parsing the input document.javax.xml.validation.Schema
getXMLSchema()
Return the XML Schema used when parsing.void
ignorableWhitespace(char[] buffer, int start, int len)
protected void
initialize()
Provides a hook for lazy initialization of thisDigester
instance.boolean
isConfigured()
Checks the Digester instance has been configured.boolean
isEmpty(java.lang.String stackName)
Is the stack with the given name empty?void
notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
private <T> T
npeSafeCast(java.lang.Object obj)
Helps casting the input object to given type, avoiding NPEs.<T> T
parse(java.io.File file)
Parse the content of the specified file using this Digester.<T> T
parse(java.io.InputStream input)
Parse the content of the specified input stream using this Digester.<T> T
parse(java.io.Reader reader)
Parse the content of the specified reader using this Digester.<T> T
parse(java.lang.String uri)
Parse the content of the specified URI using this Digester.<T> T
parse(java.net.URL url)
Parse the content of the specified URL using this Digester.<T> T
parse(org.xml.sax.InputSource input)
Parse the content of the specified input source using this Digester.<T> T
peek()
Return the top object on the stack without removing it.<T> T
peek(int n)
Return the n'th object down the stack, where 0 is the top element and [getCount()-1] is the bottom element.<T> T
peek(java.lang.String stackName)
Gets the top object from the stack with the given name.<T> T
peek(java.lang.String stackName, int n)
Gets the top object from the stack with the given name.java.lang.Object[]
peekParams()
Return the top object on the parameters stack without removing it.java.lang.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.<T> T
pop()
Pop the top object off of the stack, and return it.<T> T
pop(java.lang.String stackName)
Pops (gets and removes) the top object from the stack with the given name.java.lang.Object[]
popParams()
Pop the top object off of the parameters stack, and return it.void
processingInstruction(java.lang.String target, java.lang.String data)
<T> void
push(java.lang.String stackName, T value)
Pushes the given object onto the stack with the given name.<T> void
push(T object)
Push a new object onto the top of the object stack.void
pushParams(java.lang.Object... object)
Push a new object onto the top of the parameters stack.void
register(java.lang.String publicId, java.lang.String entityURL)
Convenience method that registers the string version of an entity URL instead of a URL version.void
register(java.lang.String publicId, java.net.URL entityURL)
Register the specified DTD URL for the specified public identifier.void
registerAll(java.util.Map<java.lang.String,java.net.URL> entityValidator)
Convenience method that registers DTD URLs for the specified public identifiers.void
resetRoot()
This method allows the "root" variable to be reset to null.org.xml.sax.InputSource
resolveEntity(java.lang.String publicId, java.lang.String systemId)
void
setClassLoader(java.lang.ClassLoader classLoader)
Set the class loader to be used for instantiating application objects when required.void
setCustomContentHandler(org.xml.sax.ContentHandler handler)
Redirects (or cancels redirecting) of SAX ContentHandler events to an external object.void
setDocumentLocator(org.xml.sax.Locator locator)
void
setEntityResolver(org.xml.sax.EntityResolver entityResolver)
Set theEntityResolver
used by SAX when resolving public id and system id.void
setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
Set the error handler for this Digester.void
setExecutorService(java.util.concurrent.ExecutorService executorService)
Sets the executor service to run asynchronous parse method.void
setFeature(java.lang.String feature, boolean value)
Sets a flag indicating whether the requested feature is supported by the underlying implementation oforg.xml.sax.XMLReader
.void
setLogger(org.apache.commons.logging.Log log)
Set the current logger for this Digester.void
setNamespaceAware(boolean namespaceAware)
Set the "namespace aware" flag for parsers we create.void
setProperty(java.lang.String property, java.lang.Object value)
Set the current value of the specified property for the underlyingXMLReader
implementation.void
setPublicId(java.lang.String publicId)
Set the public id of the current file being parse.void
setRuleNamespaceURI(java.lang.String ruleNamespaceURI)
Set the namespace URI that will be applied to all subsequently addedRule
objects.void
setRules(Rules rules)
Set theRules
implementation object containing our rules collection and associated matching policy.void
setSAXLogger(org.apache.commons.logging.Log saxLog)
Sets the logger used for logging SAX-related information.void
setStackAction(StackAction stackAction)
Define a callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.void
setSubstitutor(Substitutor substitutor)
Sets theSubstitutor
to be used to convert attributes and body text.void
setUseContextClassLoader(boolean use)
Determine whether to use the Context ClassLoader (the one found by callingThread.currentThread().getContextClassLoader()
) to resolve/load classes that are defined in various rules.void
setValidating(boolean validating)
Set the validating parser flag.void
setXIncludeAware(boolean xincludeAware)
Set the XInclude-aware flag for parsers we create.void
setXMLSchema(javax.xml.validation.Schema schema)
Set the XML Schema to be used when parsing.void
skippedEntity(java.lang.String name)
void
startDocument()
void
startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes list)
void
startPrefixMapping(java.lang.String prefix, java.lang.String namespaceURI)
void
unparsedEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notation)
void
warning(org.xml.sax.SAXParseException exception)
-
-
-
Field Detail
-
bodyText
private java.lang.StringBuilder bodyText
The body text of the current element.
-
bodyTexts
private final java.util.Stack<java.lang.StringBuilder> bodyTexts
The stack of body text string buffers for surrounding elements.
-
matches
private final java.util.Stack<java.util.List<Rule>> matches
Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch(). As each xml element in the input is entered, the matching rules are pushed onto this stack. After the end tag is reached, the matches are popped again. The depth of is stack is therefore exactly the same as the current "nesting" level of the input xml.- Since:
- 1.6
-
classLoader
private java.lang.ClassLoader classLoader
The class loader to use for instantiating application objects. If not specified, the context class loader, or the class loader used to load Digester itself, is used, based on the value of theuseContextClassLoader
variable.
-
configured
private boolean configured
Has this Digester been configured yet.
-
entityResolver
private org.xml.sax.EntityResolver entityResolver
The EntityResolver used by the SAX parser. By default it use this class
-
entityValidator
private final java.util.HashMap<java.lang.String,java.net.URL> entityValidator
The URLs of entityValidator that have been registered, keyed by the public identifier that corresponds.
-
errorHandler
private org.xml.sax.ErrorHandler errorHandler
The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.
-
factory
private javax.xml.parsers.SAXParserFactory factory
The SAXParserFactory that is created the first time we need it.
-
locator
private org.xml.sax.Locator locator
The Locator associated with our parser.
-
match
private java.lang.String match
The current match pattern for nested element processing.
-
namespaceAware
private boolean namespaceAware
Do we want a "namespace aware" parser.
-
executorService
private java.util.concurrent.ExecutorService executorService
The executor service to run asynchronous parse method.- Since:
- 3.1
-
namespaces
private final java.util.HashMap<java.lang.String,java.util.Stack<java.lang.String>> namespaces
Registered namespaces we are currently processing. The key is the namespace prefix that was declared in the document. The value is an Stack of the namespace URIs this prefix has been mapped to -- the top Stack element is the most current one. (This architecture is required because documents can declare nested uses of the same prefix for different Namespace URIs).
-
xincludeAware
private boolean xincludeAware
Do we want a "XInclude aware" parser.
-
params
private final java.util.Stack<java.lang.Object[]> params
The parameters stack being utilized by CallMethodRule and CallParamRule rules.- Since:
- 2.0
-
parser
private javax.xml.parsers.SAXParser parser
The SAXParser we will use to parse the input stream.
-
publicId
private java.lang.String publicId
The public identifier of the DTD we are currently parsing under (if any).
-
reader
private org.xml.sax.XMLReader reader
The XMLReader used to parse digester rules.
-
root
private java.lang.Object root
The "root" element of the stack (in other words, the last object that was popped.
-
rules
private Rules rules
TheRules
implementation containing our collection ofRule
instances and associated matching policy. If not established before the first rule is added, a default implementation will be provided.
-
schema
private javax.xml.validation.Schema schema
The XML schema to use for validating an XML instance.- Since:
- 2.0
-
stack
private final java.util.Stack<java.lang.Object> stack
The object stack being constructed.
-
useContextClassLoader
private boolean useContextClassLoader
Do we want to use the Context ClassLoader when loading classes for instantiating new objects. Default istrue
.
-
validating
private boolean validating
Do we want to use a validating parser.
-
log
private org.apache.commons.logging.Log log
The Log to which most logging calls will be made.
-
saxLog
private org.apache.commons.logging.Log saxLog
The Log to which all SAX event related logging calls will be made.
-
W3C_XML_SCHEMA
protected static final java.lang.String W3C_XML_SCHEMA
The schema language supported. By default, we use this one.- See Also:
- Constant Field Values
-
substitutor
private Substitutor substitutor
An optional class that substitutes values in attributes and body text. This may be null and so a null check is always required before use.
-
stacksByName
private final java.util.HashMap<java.lang.String,java.util.Stack<java.lang.Object>> stacksByName
Stacks used for interrule communication, indexed by name String
-
customContentHandler
private org.xml.sax.ContentHandler customContentHandler
If not null, then calls by the parser to this object's characters, startElement, endElement and processingInstruction methods are forwarded to the specified object. This is intended to allow rules to temporarily "take control" of the sax events. In particular, this is used by NodeCreateRule.See setCustomContentHandler.
-
stackAction
private StackAction stackAction
Object which will receive callbacks for every pop/push action on the default stack or named stacks.
-
inputSources
protected java.util.List<org.xml.sax.InputSource> inputSources
List
ofInputSource
instances created by acreateInputSourceFromURL()
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.
-
-
Constructor Detail
-
Digester
public Digester()
Construct a new Digester with default properties.
-
Digester
public Digester(javax.xml.parsers.SAXParser parser)
Construct a new Digester, allowing a SAXParser to be passed in. This allows Digester to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). This may help in places where you are able to load JAXP 1.1 classes yourself.- Parameters:
parser
- The SAXParser used to parse XML streams
-
Digester
public Digester(org.xml.sax.XMLReader reader)
Construct a new Digester, allowing an XMLReader to be passed in. This allows Digester to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). Note that if you use this option you have to configure namespace and validation support yourself, as these properties only affect the SAXParser and emtpy constructor.- Parameters:
reader
- The XMLReader used to parse XML streams
-
-
Method Detail
-
findNamespaceURI
public java.lang.String findNamespaceURI(java.lang.String prefix)
Return the currently mapped namespace URI for the specified prefix, if any; otherwise returnnull
. These mappings come and go dynamically as the document is parsed.- Parameters:
prefix
- Prefix to look up- Returns:
- the currently mapped namespace URI for the specified prefix
-
getClassLoader
public java.lang.ClassLoader getClassLoader()
Return the class loader to be used for instantiating application objects when required. This is determined based upon the following rules:- The class loader set by
setClassLoader()
, if any - The thread context class loader, if it exists and the
useContextClassLoader
property is set to true - The class loader used to load the Digester class itself.
- Returns:
- the class loader to be used for instantiating application objects.
- The class loader set by
-
setClassLoader
public void setClassLoader(java.lang.ClassLoader classLoader)
Set the class loader to be used for instantiating application objects when required.- Parameters:
classLoader
- The new class loader to use, ornull
to revert to the standard rules
-
getCount
public int getCount()
Return the current depth of the element stack.- Returns:
- the current depth of the element stack.
-
getCurrentElementName
public java.lang.String getCurrentElementName()
Return the name of the XML element that is currently being processed.- Returns:
- the name of the XML element that is currently being processed.
-
getErrorHandler
public org.xml.sax.ErrorHandler getErrorHandler()
Return the error handler for this Digester.- Returns:
- the error handler for this Digester.
-
setErrorHandler
public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)
Set the error handler for this Digester.- Parameters:
errorHandler
- The new error handler
-
getFactory
public javax.xml.parsers.SAXParserFactory getFactory()
Return the SAXParserFactory we will use, creating one if necessary.- Returns:
- the SAXParserFactory we will use, creating one if necessary.
-
getFeature
public boolean getFeature(java.lang.String feature) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
Returns a flag indicating whether the requested feature is supported by the underlying implementation oforg.xml.sax.XMLReader
. See the saxproject website for information about the standard SAX2 feature flags.- Parameters:
feature
- Name of the feature to inquire about- Returns:
- true, if the requested feature is supported by the underlying implementation of
org.xml.sax.XMLReader
, false otherwise - Throws:
javax.xml.parsers.ParserConfigurationException
- if a parser configuration error occursorg.xml.sax.SAXNotRecognizedException
- if the property name is not recognizedorg.xml.sax.SAXNotSupportedException
- if the property name is recognized but not supported
-
setFeature
public void setFeature(java.lang.String feature, boolean value) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
Sets a flag indicating whether the requested feature is supported by the underlying implementation oforg.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 thegetParser()
method is called for the first time, either directly or indirectly.- Parameters:
feature
- Name of the feature to set the status forvalue
- The new value for this feature- Throws:
javax.xml.parsers.ParserConfigurationException
- if a parser configuration error occursorg.xml.sax.SAXNotRecognizedException
- if the property name is not recognizedorg.xml.sax.SAXNotSupportedException
- if the property name is recognized but not supported
-
getLogger
public org.apache.commons.logging.Log getLogger()
Return the current Logger associated with this instance of the Digester- Returns:
- the current Logger associated with this instance of the Digester
-
setLogger
public void setLogger(org.apache.commons.logging.Log log)
Set the current logger for this Digester.- Parameters:
log
- the current logger for this Digester.
-
getSAXLogger
public org.apache.commons.logging.Log getSAXLogger()
Gets the logger used for logging SAX-related information. Note the output is finely grained.- Returns:
- the logger used for logging SAX-related information
- Since:
- 1.6
-
setSAXLogger
public void setSAXLogger(org.apache.commons.logging.Log saxLog)
Sets the logger used for logging SAX-related information. Note the output is finely grained.- Parameters:
saxLog
- the logger used for logging SAX-related information, not null- Since:
- 1.6
-
getMatch
public java.lang.String getMatch()
Return the current rule match path- Returns:
- the current rule match path
-
getMatches
public java.util.Stack<java.util.List<Rule>> getMatches()
Return a Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().- Returns:
- a Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().
- Since:
- 3.0
-
getNamespaceAware
public boolean getNamespaceAware()
Return the "namespace aware" flag for parsers we create.- Returns:
- the "namespace aware" flag for parsers we create.
-
setNamespaceAware
public void setNamespaceAware(boolean namespaceAware)
Set the "namespace aware" flag for parsers we create.- Parameters:
namespaceAware
- The new "namespace aware" flag
-
getXIncludeAware
public boolean getXIncludeAware()
Return the XInclude-aware flag for parsers we create. XInclude functionality additionally requires namespace-awareness.- Returns:
- The XInclude-aware flag
- Since:
- 2.0
- See Also:
getNamespaceAware()
-
setXIncludeAware
public void setXIncludeAware(boolean xincludeAware)
Set the XInclude-aware flag for parsers we create. This additionally requires namespace-awareness.- Parameters:
xincludeAware
- The new XInclude-aware flag- Since:
- 2.0
- See Also:
setNamespaceAware(boolean)
-
setPublicId
public void setPublicId(java.lang.String publicId)
Set the public id of the current file being parse.- Parameters:
publicId
- the DTD/Schema public's id.
-
getPublicId
public java.lang.String getPublicId()
Return the public identifier of the DTD we are currently parsing under, if any.- Returns:
- the public identifier of the DTD we are currently parsing under, if any.
-
getRuleNamespaceURI
public java.lang.String getRuleNamespaceURI()
Return the namespace URI that will be applied to all subsequently addedRule
objects.- Returns:
- the namespace URI that will be applied to all subsequently added
Rule
objects.
-
setRuleNamespaceURI
public void setRuleNamespaceURI(java.lang.String ruleNamespaceURI)
Set the namespace URI that will be applied to all subsequently addedRule
objects.- Parameters:
ruleNamespaceURI
- Namespace URI that must match on all subsequently added rules, ornull
for matching regardless of the current namespace URI
-
getParser
public javax.xml.parsers.SAXParser getParser()
Return the SAXParser we will use to parse the input stream. If there is a problem creating the parser, returnnull
.- Returns:
- the SAXParser we will use to parse the input stream
-
getProperty
public java.lang.Object getProperty(java.lang.String property) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
Return the current value of the specified property for the underlyingXMLReader
implementation. See the saxproject website for information about the standard SAX2 properties.- Parameters:
property
- Property name to be retrieved- Returns:
- the current value of the specified property for the underlying
XMLReader
implementation. - Throws:
org.xml.sax.SAXNotRecognizedException
- if the property name is not recognizedorg.xml.sax.SAXNotSupportedException
- if the property name is recognized but not supported
-
setProperty
public void setProperty(java.lang.String property, java.lang.Object value) throws org.xml.sax.SAXNotRecognizedException, org.xml.sax.SAXNotSupportedException
Set the current value of the specified property for the underlyingXMLReader
implementation. See the saxproject website for information about the standard SAX2 properties.- Parameters:
property
- Property name to be setvalue
- Property value to be set- Throws:
org.xml.sax.SAXNotRecognizedException
- if the property name is not recognizedorg.xml.sax.SAXNotSupportedException
- if the property name is recognized but not supported
-
getRules
public Rules getRules()
Return theRules
implementation object containing our rules collection and associated matching policy. If none has been established, a default implementation will be created and returned.- Returns:
- the
Rules
implementation object.
-
setRules
public void setRules(Rules rules)
Set theRules
implementation object containing our rules collection and associated matching policy.- Parameters:
rules
- New Rules implementation
-
getXMLSchema
public javax.xml.validation.Schema getXMLSchema()
Return the XML Schema used when parsing.- Returns:
- The
Schema
instance in use. - Since:
- 2.0
-
setXMLSchema
public void setXMLSchema(javax.xml.validation.Schema schema)
Set the XML Schema to be used when parsing.- Parameters:
schema
- TheSchema
instance to use.- Since:
- 2.0
-
getUseContextClassLoader
public boolean getUseContextClassLoader()
Return the boolean as to whether the context ClassLoader should be used.- Returns:
- true, if the context ClassLoader should be used, false otherwise.
-
setUseContextClassLoader
public void setUseContextClassLoader(boolean use)
Determine whether to use the Context ClassLoader (the one found by callingThread.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.
-
getValidating
public boolean getValidating()
Return the validating parser flag.- Returns:
- the validating parser flag.
-
setValidating
public void setValidating(boolean validating)
Set the validating parser flag. This must be called beforeparse()
is called the first time.- Parameters:
validating
- The new validating parser flag.
-
getXMLReader
public org.xml.sax.XMLReader getXMLReader() throws org.xml.sax.SAXException
Return the XMLReader to be used for parsing the input document. FIXME: there is a bug in JAXP/XERCES that prevent the use of a parser that contains a schema with a DTD.- Returns:
- the XMLReader to be used for parsing the input document.
- Throws:
org.xml.sax.SAXException
- if no XMLReader can be instantiated
-
getSubstitutor
public Substitutor getSubstitutor()
Gets theSubstitutor
used to convert attributes and body text.- Returns:
- the
Substitutor
used to convert attributes and body text, null if not substitutions are to be performed.
-
setSubstitutor
public void setSubstitutor(Substitutor substitutor)
Sets theSubstitutor
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.
-
getCustomContentHandler
public org.xml.sax.ContentHandler getCustomContentHandler()
returns the custom SAX ContentHandler where events are redirected.- Returns:
- the custom SAX ContentHandler where events are redirected.
- Since:
- 1.7
- See Also:
setCustomContentHandler(ContentHandler)
-
setCustomContentHandler
public void setCustomContentHandler(org.xml.sax.ContentHandler handler)
Redirects (or cancels redirecting) of SAX ContentHandler events to an external object.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:- Some xml parsers don't like having setContentHandler called after parsing has started. The Aelfred parser is one example.
- Directing the events via the Digester object potentially allows us to log information about those SAX events at the digester level.
- Parameters:
handler
- the custom SAX ContentHandler where events are redirected.- Since:
- 1.7
-
setStackAction
public void setStackAction(StackAction stackAction)
Define a callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.- Parameters:
stackAction
- the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.- Since:
- 1.8
-
getStackAction
public StackAction getStackAction()
Return the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.- Returns:
- the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.
- Since:
- 1.8
- See Also:
setStackAction(StackAction)
-
getCurrentNamespaces
public java.util.Map<java.lang.String,java.lang.String> getCurrentNamespaces()
Get the most current namespaces for all prefixes.- Returns:
- Map A map with namespace prefixes as keys and most current namespace URIs for the corresponding prefixes as values
- Since:
- 1.8
-
getExecutorService
public java.util.concurrent.ExecutorService getExecutorService()
Returns the executor service used to run asynchronous parse method.- Returns:
- the executor service used to run asynchronous parse method
- Since:
- 3.1
-
setExecutorService
public void setExecutorService(java.util.concurrent.ExecutorService executorService)
Sets the executor service to run asynchronous parse method.- Parameters:
executorService
- the executor service to run asynchronous parse method- Since:
- 3.1
-
characters
public void characters(char[] buffer, int start, int length) throws org.xml.sax.SAXException
- Specified by:
characters
in interfaceorg.xml.sax.ContentHandler
- Overrides:
characters
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
endDocument
public void endDocument() throws org.xml.sax.SAXException
- Specified by:
endDocument
in interfaceorg.xml.sax.ContentHandler
- Overrides:
endDocument
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
endElement
public void endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName) throws org.xml.sax.SAXException
- Specified by:
endElement
in interfaceorg.xml.sax.ContentHandler
- Overrides:
endElement
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
endPrefixMapping
public void endPrefixMapping(java.lang.String prefix) throws org.xml.sax.SAXException
- Specified by:
endPrefixMapping
in interfaceorg.xml.sax.ContentHandler
- Overrides:
endPrefixMapping
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
ignorableWhitespace
public void ignorableWhitespace(char[] buffer, int start, int len) throws org.xml.sax.SAXException
- Specified by:
ignorableWhitespace
in interfaceorg.xml.sax.ContentHandler
- Overrides:
ignorableWhitespace
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
processingInstruction
public void processingInstruction(java.lang.String target, java.lang.String data) throws org.xml.sax.SAXException
- Specified by:
processingInstruction
in interfaceorg.xml.sax.ContentHandler
- Overrides:
processingInstruction
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
getDocumentLocator
public org.xml.sax.Locator getDocumentLocator()
Gets the document locator associated with our parser.- Returns:
- the Locator supplied by the document parser
-
setDocumentLocator
public void setDocumentLocator(org.xml.sax.Locator locator)
- Specified by:
setDocumentLocator
in interfaceorg.xml.sax.ContentHandler
- Overrides:
setDocumentLocator
in classorg.xml.sax.helpers.DefaultHandler
-
skippedEntity
public void skippedEntity(java.lang.String name) throws org.xml.sax.SAXException
- Specified by:
skippedEntity
in interfaceorg.xml.sax.ContentHandler
- Overrides:
skippedEntity
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
startDocument
public void startDocument() throws org.xml.sax.SAXException
- Specified by:
startDocument
in interfaceorg.xml.sax.ContentHandler
- Overrides:
startDocument
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
startElement
public void startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes list) throws org.xml.sax.SAXException
- Specified by:
startElement
in interfaceorg.xml.sax.ContentHandler
- Overrides:
startElement
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
startPrefixMapping
public void startPrefixMapping(java.lang.String prefix, java.lang.String namespaceURI) throws org.xml.sax.SAXException
- Specified by:
startPrefixMapping
in interfaceorg.xml.sax.ContentHandler
- Overrides:
startPrefixMapping
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
notationDecl
public void notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
- Specified by:
notationDecl
in interfaceorg.xml.sax.DTDHandler
- Overrides:
notationDecl
in classorg.xml.sax.helpers.DefaultHandler
-
unparsedEntityDecl
public void unparsedEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notation)
- Specified by:
unparsedEntityDecl
in interfaceorg.xml.sax.DTDHandler
- Overrides:
unparsedEntityDecl
in classorg.xml.sax.helpers.DefaultHandler
-
setEntityResolver
public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
Set theEntityResolver
used by SAX when resolving public id and system id. This must be called before the first call toparse()
.- Parameters:
entityResolver
- a class that implement theEntityResolver
interface.
-
getEntityResolver
public org.xml.sax.EntityResolver getEntityResolver()
Return the Entity Resolver used by the SAX parser.- Returns:
- the Entity Resolver used by the SAX parser.
-
resolveEntity
public org.xml.sax.InputSource resolveEntity(java.lang.String publicId, java.lang.String systemId) throws org.xml.sax.SAXException
- Specified by:
resolveEntity
in interfaceorg.xml.sax.EntityResolver
- Overrides:
resolveEntity
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
error
public void error(org.xml.sax.SAXParseException exception) throws org.xml.sax.SAXException
- Specified by:
error
in interfaceorg.xml.sax.ErrorHandler
- Overrides:
error
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
fatalError
public void fatalError(org.xml.sax.SAXParseException exception) throws org.xml.sax.SAXException
- Specified by:
fatalError
in interfaceorg.xml.sax.ErrorHandler
- Overrides:
fatalError
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
warning
public void warning(org.xml.sax.SAXParseException exception) throws org.xml.sax.SAXException
- Specified by:
warning
in interfaceorg.xml.sax.ErrorHandler
- Overrides:
warning
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
parse
public <T> T parse(java.io.File file) throws java.io.IOException, org.xml.sax.SAXException
Parse the content of the specified file using this Digester. Returns the root element from the object stack (if any).- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
file
- File containing the XML data to be parsed- Returns:
- the root element from the object stack (if any)
- Throws:
java.io.IOException
- if an input/output error occursorg.xml.sax.SAXException
- if a parsing exception occurs
-
asyncParse
public <T> java.util.concurrent.Future<T> asyncParse(java.io.File file)
Creates a Callable instance that parse the content of the specified reader using this Digester.- Type Parameters:
T
- The result type returned by the returned Future'sget
method- Parameters:
file
- File containing the XML data to be parsed- Returns:
- a Future that can be used to track when the parse has been fully processed.
- Since:
- 3.1
- See Also:
parse(File)
-
parse
public <T> T parse(org.xml.sax.InputSource input) throws java.io.IOException, org.xml.sax.SAXException
Parse the content of the specified input source using this Digester. Returns the root element from the object stack (if any).- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
input
- Input source containing the XML data to be parsed- Returns:
- the root element from the object stack (if any)
- Throws:
java.io.IOException
- if an input/output error occursorg.xml.sax.SAXException
- if a parsing exception occurs
-
asyncParse
public <T> java.util.concurrent.Future<T> asyncParse(org.xml.sax.InputSource input)
Creates a Callable instance that parse the content of the specified reader using this Digester.- Type Parameters:
T
- The result type returned by the returned Future'sget
method- Parameters:
input
- Input source containing the XML data to be parsed- Returns:
- a Future that can be used to track when the parse has been fully processed.
- Since:
- 3.1
- See Also:
parse(InputSource)
-
parse
public <T> T parse(java.io.InputStream input) throws java.io.IOException, org.xml.sax.SAXException
Parse the content of the specified input stream using this Digester. Returns the root element from the object stack (if any).- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
input
- Input stream containing the XML data to be parsed- Returns:
- the root element from the object stack (if any)
- Throws:
java.io.IOException
- if an input/output error occursorg.xml.sax.SAXException
- if a parsing exception occurs
-
asyncParse
public <T> java.util.concurrent.Future<T> asyncParse(java.io.InputStream input)
Creates a Callable instance that parse the content of the specified reader using this Digester.- Type Parameters:
T
- The result type returned by the returned Future'sget
method- Parameters:
input
- Input stream containing the XML data to be parsed- Returns:
- a Future that can be used to track when the parse has been fully processed.
- Since:
- 3.1
- See Also:
parse(InputStream)
-
parse
public <T> T parse(java.io.Reader reader) throws java.io.IOException, org.xml.sax.SAXException
Parse the content of the specified reader using this Digester. Returns the root element from the object stack (if any).- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
reader
- Reader containing the XML data to be parsed- Returns:
- the root element from the object stack (if any)
- Throws:
java.io.IOException
- if an input/output error occursorg.xml.sax.SAXException
- if a parsing exception occurs
-
asyncParse
public <T> java.util.concurrent.Future<T> asyncParse(java.io.Reader reader)
Creates a Callable instance that parse the content of the specified reader using this Digester.- Type Parameters:
T
- The result type returned by the returned Future'sget
method- Parameters:
reader
- Reader containing the XML data to be parsed- Returns:
- a Future that can be used to track when the parse has been fully processed.
- Since:
- 3.1
- See Also:
parse(Reader)
-
parse
public <T> T parse(java.lang.String uri) throws java.io.IOException, org.xml.sax.SAXException
Parse the content of the specified URI using this Digester. Returns the root element from the object stack (if any).- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
uri
- URI containing the XML data to be parsed- Returns:
- the root element from the object stack (if any)
- Throws:
java.io.IOException
- if an input/output error occursorg.xml.sax.SAXException
- if a parsing exception occurs
-
asyncParse
public <T> java.util.concurrent.Future<T> asyncParse(java.lang.String uri)
Creates a Callable instance that parse the content of the specified reader using this Digester.- Type Parameters:
T
- The result type returned by the returned Future'sget
method- Parameters:
uri
- URI containing the XML data to be parsed- Returns:
- a Future that can be used to track when the parse has been fully processed.
- Since:
- 3.1
- See Also:
parse(String)
-
parse
public <T> T parse(java.net.URL url) throws java.io.IOException, org.xml.sax.SAXException
Parse the content of the specified URL using this Digester. Returns the root element from the object stack (if any).- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
url
- URL containing the XML data to be parsed- Returns:
- the root element from the object stack (if any)
- Throws:
java.io.IOException
- if an input/output error occursorg.xml.sax.SAXException
- if a parsing exception occurs- Since:
- 1.8
-
asyncParse
public <T> java.util.concurrent.Future<T> asyncParse(java.net.URL url)
Creates a Callable instance that parse the content of the specified reader using this Digester.- Type Parameters:
T
- The result type returned by the returned Future'sget
method- Parameters:
url
- URL containing the XML data to be parsed- Returns:
- a Future that can be used to track when the parse has been fully processed.
- Since:
- 3.1
- See Also:
parse(URL)
-
asyncParse
private <T> java.util.concurrent.Future<T> asyncParse(java.util.concurrent.Callable<T> callable)
Execute the parse in async mode.- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
callable
-- Returns:
- a Future that can be used to track when the parse has been fully processed.
- Since:
- 3.1
-
register
public void register(java.lang.String publicId, java.net.URL entityURL)
Register the specified DTD URL for the specified public identifier. This must be called before the first call to
parse()
.Digester
contains an internalEntityResolver
implementation. This mapsPUBLICID
'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 everySYSTEM
URI on every processed xml document is local. This implementation provides only basic functionality. If more sophisticated features are required, usingsetEntityResolver(org.xml.sax.EntityResolver)
to set a custom resolver is recommended.Note: This method will have no effect when a custom
EntityResolver
has been set. (Setting a customEntityResolver
overrides the internal implementation.)- Parameters:
publicId
- Public identifier of the DTD to be resolvedentityURL
- The URL to use for reading this DTD- Since:
- 1.8
-
register
public void register(java.lang.String publicId, java.lang.String entityURL)
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 resolvedentityURL
- The URL to use for reading this entity
-
registerAll
public void registerAll(java.util.Map<java.lang.String,java.net.URL> entityValidator)
Convenience method that registers DTD URLs for the specified public identifiers.- Parameters:
entityValidator
- The URLs of entityValidator that have been registered, keyed by the public identifier that corresponds.- Since:
- 3.0
-
createInputSourceFromURL
public org.xml.sax.InputSource createInputSourceFromURL(java.net.URL url) throws java.io.IOException
Given a URL, return an InputSource that reads from that URL.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.- Parameters:
url
- The URL has to be read- Returns:
- The InputSource that reads from the input URL
- Throws:
java.io.IOException
- if any error occurs while reading the input URL- Since:
- 1.8
-
createInputSourceFromURL
public org.xml.sax.InputSource createInputSourceFromURL(java.lang.String url) throws java.io.IOException
Convenience method that creates an
InputSource
from the string version of a URL.- Parameters:
url
- URL for which to create anInputSource
- Returns:
- The InputSource that reads from the input URL
- Throws:
java.io.IOException
- if any error occurs while reading the input URL- Since:
- 1.8
-
addRule
public void addRule(java.lang.String pattern, Rule rule)
Register a new Rule matching the specified pattern. This method sets the
Digester
property on the rule.- Parameters:
pattern
- Element matching patternrule
- Rule to be registered
-
addRuleSet
public void addRuleSet(RuleSet ruleSet)
Register a set of Rule instances defined in a RuleSet.- Parameters:
ruleSet
- The RuleSet instance to configure from
-
addBeanPropertySetter
public void addBeanPropertySetter(java.lang.String pattern)
Add a "bean property setter" rule for the specified parameters.- Parameters:
pattern
- Element matching pattern- See Also:
BeanPropertySetterRule
-
addBeanPropertySetter
public void addBeanPropertySetter(java.lang.String pattern, java.lang.String propertyName)
Add a "bean property setter" rule for the specified parameters.- Parameters:
pattern
- Element matching patternpropertyName
- Name of property to set- See Also:
BeanPropertySetterRule
-
addCallMethod
public void addCallMethod(java.lang.String pattern, java.lang.String methodName)
Add an "call method" rule for a method which accepts no arguments.- Parameters:
pattern
- Element matching patternmethodName
- Method name to be called- See Also:
CallMethodRule
-
addCallMethod
public void addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount)
Add an "call method" rule for the specified parameters.- Parameters:
pattern
- Element matching patternmethodName
- Method name to be calledparamCount
- Number of expected parameters (or zero for a single parameter from the body of this element)- See Also:
CallMethodRule
-
addCallMethod
public void addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Add an "call method" rule for the specified parameters. IfparamCount
is set to zero the rule will use the body of the matched element as the single argument of the method, unlessparamTypes
is null or empty, in this case the rule will call the specified method with no arguments.- Parameters:
pattern
- Element matching patternmethodName
- Method name to be calledparamCount
- 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 asjava.lang.Boolean
for aboolean
parameter)- See Also:
CallMethodRule
-
addCallMethod
public void addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.Class<?>[] paramTypes)
Add an "call method" rule for the specified parameters. IfparamCount
is set to zero the rule will use the body of the matched element as the single argument of the method, unlessparamTypes
is null or empty, in this case the rule will call the specified method with no arguments.- Parameters:
pattern
- Element matching patternmethodName
- Method name to be calledparamCount
- 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 asjava.lang.Boolean
for aboolean
parameter)- See Also:
CallMethodRule
-
addCallParam
public void addCallParam(java.lang.String pattern, int paramIndex)
Add a "call parameter" rule for the specified parameters.- Parameters:
pattern
- Element matching patternparamIndex
- Zero-relative parameter index to set (from the body of this element)- See Also:
CallParamRule
-
addCallParam
public void addCallParam(java.lang.String pattern, int paramIndex, java.lang.String attributeName)
Add a "call parameter" rule for the specified parameters.- Parameters:
pattern
- Element matching patternparamIndex
- Zero-relative parameter index to set (from the specified attribute)attributeName
- Attribute whose value is used as the parameter value- See Also:
CallParamRule
-
addCallParam
public void addCallParam(java.lang.String pattern, int paramIndex, boolean fromStack)
Add a "call parameter" rule. This will either take a parameter from the stack or from the current element body text.- Parameters:
pattern
- Element matching patternparamIndex
- The zero-relative parameter numberfromStack
- Should the call parameter be taken from the top of the stack?- See Also:
CallParamRule
-
addCallParam
public void addCallParam(java.lang.String pattern, int paramIndex, int stackIndex)
Add a "call parameter" rule that sets a parameter from the stack. This takes a parameter from the given position on the stack.- Parameters:
pattern
- Element matching patternparamIndex
- The zero-relative parameter numberstackIndex
- 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
-
addCallParamPath
public void addCallParamPath(java.lang.String pattern, int paramIndex)
Add a "call parameter" rule that sets a parameter from the currentDigester
matching path. This is sometimes useful when using rules that support wildcards.- Parameters:
pattern
- the pattern that this rule should matchparamIndex
- The zero-relative parameter number- See Also:
CallMethodRule
-
addObjectParam
public void addObjectParam(java.lang.String pattern, int paramIndex, java.lang.Object paramObj)
Add a "call parameter" rule that sets a parameter from a caller-provided object. This can be used to pass constants such as strings to methods; it can also be used to pass mutable objects, providing ways for objects to do things like "register" themselves with some shared object.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:
pattern
- Element matching patternparamIndex
- The zero-relative parameter numberparamObj
- Any arbitrary object to be passed to the target method.- Since:
- 1.6
- See Also:
CallMethodRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.String className)
Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.- Parameters:
pattern
- Element matching patternclassName
- Java class name of the object creation factory class- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz)
Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.- Parameters:
pattern
- Element matching patternclazz
- Java class of the object creation factory class- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.String className, java.lang.String attributeName)
Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.- Parameters:
pattern
- Element matching patternclassName
- Java class name of the object creation factory classattributeName
- Attribute name which, if present, overrides the value specified byclassName
- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, java.lang.String attributeName)
Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.- Parameters:
pattern
- Element matching patternclazz
- Java class of the object creation factory classattributeName
- Attribute name which, if present, overrides the value specified byclassName
- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, ObjectCreationFactory<?> creationFactory)
Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.- Parameters:
pattern
- Element matching patterncreationFactory
- Previously instantiated ObjectCreationFactory to be utilized- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.String className, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternclassName
- Java class name of the object creation factory classignoreCreateExceptions
- whentrue
any exceptions thrown during object creation will be ignored.- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternclazz
- Java class of the object creation factory classignoreCreateExceptions
- whentrue
any exceptions thrown during object creation will be ignored.- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.String className, java.lang.String attributeName, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternclassName
- Java class name of the object creation factory classattributeName
- Attribute name which, if present, overrides the value specified byclassName
ignoreCreateExceptions
- whentrue
any exceptions thrown during object creation will be ignored.- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, java.lang.String attributeName, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternclazz
- Java class of the object creation factory classattributeName
- Attribute name which, if present, overrides the value specified byclassName
ignoreCreateExceptions
- whentrue
any exceptions thrown during object creation will be ignored.- See Also:
FactoryCreateRule
-
addFactoryCreate
public void addFactoryCreate(java.lang.String pattern, ObjectCreationFactory<?> creationFactory, boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.- Parameters:
pattern
- Element matching patterncreationFactory
- Previously instantiated ObjectCreationFactory to be utilizedignoreCreateExceptions
- whentrue
any exceptions thrown during object creation will be ignored.- See Also:
FactoryCreateRule
-
addObjectCreate
public void addObjectCreate(java.lang.String pattern, java.lang.String className)
Add an "object create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternclassName
- Java class name to be created- See Also:
ObjectCreateRule
-
addObjectCreate
public void addObjectCreate(java.lang.String pattern, java.lang.Class<?> clazz)
Add an "object create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternclazz
- Java class to be created- See Also:
ObjectCreateRule
-
addObjectCreate
public void addObjectCreate(java.lang.String pattern, java.lang.String className, java.lang.String attributeName)
Add an "object create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternclassName
- Default Java class name to be createdattributeName
- Attribute name that optionally overrides the default Java class name to be created- See Also:
ObjectCreateRule
-
addObjectCreate
public void addObjectCreate(java.lang.String pattern, java.lang.String attributeName, java.lang.Class<?> clazz)
Add an "object create" rule for the specified parameters.- Parameters:
pattern
- Element matching patternattributeName
- Attribute name that optionally overridesclazz
- Default Java class to be created the default Java class name to be created- See Also:
ObjectCreateRule
-
addSetNestedProperties
public void addSetNestedProperties(java.lang.String pattern)
Adds anSetNestedPropertiesRule
.- Parameters:
pattern
- register the rule with this pattern- Since:
- 1.6
-
addSetNestedProperties
public void addSetNestedProperties(java.lang.String pattern, java.lang.String elementName, java.lang.String propertyName)
Adds anSetNestedPropertiesRule
.- Parameters:
pattern
- register the rule with this patternelementName
- elment name that a property maps topropertyName
- property name of the element mapped from- Since:
- 1.6
-
addSetNestedProperties
public void addSetNestedProperties(java.lang.String pattern, java.lang.String[] elementNames, java.lang.String[] propertyNames)
Adds anSetNestedPropertiesRule
.- Parameters:
pattern
- register the rule with this patternelementNames
- elment names that (in order) map to propertiespropertyNames
- property names that (in order) elements are mapped to- Since:
- 1.6
-
addSetNext
public void addSetNext(java.lang.String pattern, java.lang.String methodName)
Add a "set next" rule for the specified parameters.- Parameters:
pattern
- Element matching patternmethodName
- Method name to call on the parent element- See Also:
SetNextRule
-
addSetNext
public void addSetNext(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
Add a "set next" rule for the specified parameters.- Parameters:
pattern
- Element matching patternmethodName
- Method name to call on the parent elementparamType
- Java class name of the expected parameter type (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean
for aboolean
parameter)- See Also:
SetNextRule
-
addSetRoot
public void addSetRoot(java.lang.String pattern, java.lang.String methodName)
AddSetRootRule
with the specified parameters.- Parameters:
pattern
- Element matching patternmethodName
- Method name to call on the root object- See Also:
SetRootRule
-
addSetRoot
public void addSetRoot(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
AddSetRootRule
with the specified parameters.- Parameters:
pattern
- Element matching patternmethodName
- Method name to call on the root objectparamType
- Java class name of the expected parameter type- See Also:
SetRootRule
-
addSetProperties
public void addSetProperties(java.lang.String pattern)
Add a "set properties" rule for the specified parameters.- Parameters:
pattern
- Element matching pattern- See Also:
SetPropertiesRule
-
addSetProperties
public void addSetProperties(java.lang.String pattern, java.lang.String attributeName, java.lang.String propertyName)
Add a "set properties" rule with a single overridden parameter. SeeSetPropertiesRule(String attributeName, String propertyName)
- Parameters:
pattern
- Element matching patternattributeName
- map this attributepropertyName
- to this property- See Also:
SetPropertiesRule
-
addSetProperties
public void addSetProperties(java.lang.String pattern, java.lang.String[] attributeNames, java.lang.String[] propertyNames)
Add a "set properties" rule with overridden parameters. SeeSetPropertiesRule(String [] attributeNames, String [] propertyNames)
- Parameters:
pattern
- Element matching patternattributeNames
- names of attributes with custom mappingspropertyNames
- property names these attributes map to- See Also:
SetPropertiesRule
-
addSetProperty
public void addSetProperty(java.lang.String pattern, java.lang.String name, java.lang.String value)
Add a "set property" rule for the specified parameters.- Parameters:
pattern
- Element matching patternname
- Attribute name containing the property name to be setvalue
- Attribute name containing the property value to set- See Also:
SetPropertyRule
-
addSetTop
public void addSetTop(java.lang.String pattern, java.lang.String methodName)
Add a "set top" rule for the specified parameters.- Parameters:
pattern
- Element matching patternmethodName
- Method name to call on the parent element- See Also:
SetTopRule
-
addSetTop
public void addSetTop(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
Add a "set top" rule for the specified parameters.- Parameters:
pattern
- Element matching patternmethodName
- Method name to call on the parent elementparamType
- Java class name of the expected parameter type (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean
for aboolean
parameter)- See Also:
SetTopRule
-
clear
public void clear()
Clear the current contents of the default object stack, the param stack, all named stacks, and other internal variables.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.
-
peek
public <T> T peek()
Return the top object on the stack without removing it. If there are no objects on the stack, returnnull
.- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Returns:
- the top object on the stack without removing it.
-
peek
public <T> T peek(int n)
Return the n'th object down the stack, where 0 is the top element and [getCount()-1] is the bottom element. If the specified index is out of range, returnnull
.- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
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 n'th object down the stack
-
pop
public <T> T pop()
Pop the top object off of the stack, and return it. If there are no objects on the stack, returnnull
.- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Returns:
- the top object popped off of the stack
-
push
public <T> void push(T object)
Push a new object onto the top of the object stack.- Type Parameters:
T
- any type of the pushed object- Parameters:
object
- The new object
-
push
public <T> void push(java.lang.String stackName, T value)
Pushes the given object onto the stack with the given name. If no stack already exists with the given name then one will be created.- Type Parameters:
T
- any type of the pushed object- Parameters:
stackName
- the name of the stack onto which the object should be pushedvalue
- the Object to be pushed onto the named stack.- Since:
- 1.6
-
pop
public <T> T pop(java.lang.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.
- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- 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 - Since:
- 1.6
-
peek
public <T> T peek(java.lang.String stackName)
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.
- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- 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 - Since:
- 1.6
-
peek
public <T> T peek(java.lang.String stackName, int n)
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.
- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Parameters:
stackName
- the name of the stack to be peekedn
- 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. - Since:
- 1.6
-
isEmpty
public boolean isEmpty(java.lang.String stackName)
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
-
getRoot
public <T> T getRoot()
Returns the root element of the tree of objects created as a result of applying the rule objects to the input XML.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.
- Type Parameters:
T
- the type used to auto-cast the returned object to the assigned variable type- Returns:
- the root object that has been created after parsing or null if the digester has not parsed any XML yet.
-
resetRoot
public void resetRoot()
This method allows the "root" variable to be reset to null.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
-
cleanup
protected void cleanup()
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
-
configure
protected void configure()
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
initialize()
or the code should take responsibility by checking and setting theconfigured
flag.
-
isConfigured
public boolean isConfigured()
Checks the Digester instance has been configured.- Returns:
- true, if the Digester instance has been configured, false otherwise
- Since:
- 3.0
-
initialize
protected void initialize()
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
configure()
only when theconfigured
flag is false. Subclasses that overrideconfigure
or who setconfigured
may find that this method may be called more than once.- Since:
- 1.6
-
getRegistrations
java.util.Map<java.lang.String,java.net.URL> getRegistrations()
Return the set of DTD URL registrations, keyed by public identifier. NOTE: the returned map is in read-only mode.- Returns:
- the read-only Map of DTD URL registrations.
-
peekParams
public java.lang.Object[] peekParams()
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. Seeparams
.- Returns:
- the top object on the parameters stack without removing it.
-
peekParams
public java.lang.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. If the specified index is out of range, return
null
.The parameters stack is used to store
CallMethodRule
parameters. Seeparams
.- Parameters:
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 n'th object down the parameters stack
-
popParams
public java.lang.Object[] popParams()
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. Seeparams
.- Returns:
- the top object popped off of the parameters stack
-
pushParams
public void pushParams(java.lang.Object... object)
Push a new object onto the top of the parameters stack.
The parameters stack is used to store
CallMethodRule
parameters. Seeparams
.- Parameters:
object
- The new object
-
createSAXException
public org.xml.sax.SAXException createSAXException(java.lang.String message, java.lang.Exception e)
Create a SAX exception which also understands about the location in the digester file where the exception occurs- Parameters:
message
- the custom SAX exception messagee
- the exception cause- Returns:
- the new SAX exception
-
createSAXException
public org.xml.sax.SAXException createSAXException(java.lang.Exception e)
Create a SAX exception which also understands about the location in the digester file where the exception occurs- Parameters:
e
- the exception cause- Returns:
- the new SAX exception
-
createSAXException
public org.xml.sax.SAXException createSAXException(java.lang.String message)
Create a SAX exception which also understands about the location in the digester file where the exception occurs- Parameters:
message
- the custom SAX exception message- Returns:
- the new SAX exception
-
npeSafeCast
private <T> T npeSafeCast(java.lang.Object obj)
Helps casting the input object to given type, avoiding NPEs.- Type Parameters:
T
- the type the input object has to be cast.- Parameters:
obj
- the object has to be cast.- Returns:
- the casted object, if input object is not null, null otherwise.
- Since:
- 3.0
-
-