org.apache.commons.digester

Class 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.

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 String
JAXP_SCHEMA_LANGUAGE
Deprecated. This is now managed by ParserFeatureSetterFactory
private static String
JAXP_SCHEMA_SOURCE
The JAXP 1.2 property required to set up the schema location.
protected static String
W3C_XML_SCHEMA
The schema language supported.
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.
private 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.
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
List of InputSource instances created by a createInputSourceFromURL() method call.
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.
private StackAction
stackAction
Object which will receive callbacks for every pop/push action on the default stack or named stacks.
private HashMap
stacksByName
Stacks used for interrule communication, indexed by name String
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.

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, paramTypes[] )
Add an "call method" rule for the specified parameters.
void
addCallMethod(String pattern, String methodName, int paramCount, 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, Class clazz)
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, Class clazz, String attributeName, 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)
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, String className, String attributeName, boolean ignoreCreateExceptions)
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, ObjectCreationFactory creationFactory)
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, Class clazz)
Add an "object 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, String attributeName, 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
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(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 Digester instance.
InputSource
createInputSourceFromURL(String url)
Convenience method that creates an InputSource from the string version of a URL.
InputSource
createInputSourceFromURL(URL url)
Given a URL, return an InputSource that reads from that URL.
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
SAXException
createSAXException(String message, Exception e)
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()
Deprecated. This method now always returns 0.
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()
Deprecated. Use getXMLReader() instead, which can throw a SAXException if the reader cannot be instantiated
(package private) Map
getRegistrations()
Return the set of DTD URL registrations, keyed by public identifier.
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.
(package private) List
getRules(String match)
Deprecated. Call match() on the Rules implementation returned by getRules()
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(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 Digester instance.
boolean
isEmpty(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.

void
log(String message)
Deprecated. Call getLogger() and use it's logging methods
void
log(String message, Throwable exception)
Deprecated. Call getLogger() and use it's logging methods
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(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
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
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.
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.
void
register(String publicId, String entityURL)
Convenience method that registers the string version of an entity URL instead of a URL version.
void
register(String publicId, URL entityURL)
Register the specified DTD URL for the specified public identifier.
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)
Deprecated. This method now has no effect at all.
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).

Field Details

JAXP_SCHEMA_LANGUAGE

protected String JAXP_SCHEMA_LANGUAGE

Deprecated. This is now managed by ParserFeatureSetterFactory


JAXP_SCHEMA_SOURCE

private static final String JAXP_SCHEMA_SOURCE
The JAXP 1.2 property required to set up the schema location. Removed in digester 1.6 - introduced for tomcat4 backport

W3C_XML_SCHEMA

protected static final String W3C_XML_SCHEMA
The schema language supported. By default, we use this one.

bodyText

protected StringBuffer bodyText
The body text of the current element.

bodyTexts

protected ArrayStack bodyTexts
The stack of body text string buffers for surrounding elements.

classLoader

protected 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 the useContextClassLoader variable.

configured

protected boolean configured
Has this Digester been configured yet.

customContentHandler

private 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.


entityResolver

protected EntityResolver entityResolver
The EntityResolver used by the SAX parser. By default it use this class

entityValidator

protected HashMap entityValidator
The URLs of entityValidator that have been registered, keyed by the public identifier that corresponds.

errorHandler

protected ErrorHandler errorHandler
The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.

factory

protected SAXParserFactory factory
The SAXParserFactory that is created the first time we need it.

inputSources

protected List inputSources
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.

locator

protected Locator locator
The Locator associated with our parser.

log

protected Log log
The Log to which most logging calls will be made.

match

protected String match
The current match pattern for nested element processing.

matches

protected ArrayStack 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

namespaceAware

protected boolean namespaceAware
Do we want a "namespace aware" parser.

namespaces

protected HashMap namespaces
Registered namespaces we are currently processing. The key is the namespace prefix that was declared in the document. The value is an ArrayStack 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).

params

protected ArrayStack params
The parameters stack being utilized by CallMethodRule and CallParamRule rules.

parser

protected SAXParser parser
The SAXParser we will use to parse the input stream.

publicId

protected String publicId
The public identifier of the DTD we are currently parsing under (if any).

reader

protected XMLReader reader
The XMLReader used to parse digester rules.

root

protected Object root
The "root" element of the stack (in other words, the last object that was popped.

rules

protected Rules rules
The 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.

saxLog

protected Log saxLog
The Log to which all SAX event related logging calls will be made.

schemaLanguage

protected String schemaLanguage
The XML schema language to use for validating an XML instance. By default this value is set to W3C_XML_SCHEMA

schemaLocation

protected String schemaLocation
The XML schema to use for validating an XML instance.

stack

protected ArrayStack stack
The object stack being constructed.

stackAction

private StackAction stackAction
Object which will receive callbacks for every pop/push action on the default stack or named stacks.

stacksByName

private HashMap stacksByName
Stacks used for interrule communication, indexed by name String

substitutor

protected 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.

useContextClassLoader

protected boolean useContextClassLoader
Do we want to use the Context ClassLoader when loading classes for instantiating new objects. Default is false.

validating

protected boolean validating
Do we want to use a validating parser.

Constructor Details

Digester

public Digester()
Construct a new Digester with default properties.

Digester

public Digester(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.

Digester

public Digester(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.

Method Details

addBeanPropertySetter

public void addBeanPropertySetter(String pattern)
Add a "bean property setter" rule for the specified parameters.
Parameters:
pattern - Element matching pattern

addBeanPropertySetter

public void addBeanPropertySetter(String pattern,
                                  String propertyName)
Add a "bean property setter" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
propertyName - Name of property to set

addCallMethod

public void addCallMethod(String pattern,
                          String methodName)
Add an "call method" rule for a method which accepts no arguments.
Parameters:
pattern - Element matching pattern
methodName - Method name to be called

addCallMethod

public void addCallMethod(String pattern,
                          String methodName,
                          int paramCount)
Add an "call method" rule for the specified parameters.
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)

addCallMethod

public void addCallMethod(String pattern,
                          String methodName,
                          int paramCount,
                          paramTypes[] )
Add an "call method" rule for the specified parameters. If 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)

addCallMethod

public void addCallMethod(String pattern,
                          String methodName,
                          int paramCount,
                          paramTypes[] )
Add an "call method" rule for the specified parameters. If 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)

addCallParam

public void addCallParam(String pattern,
                         int paramIndex)
Add a "call parameter" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
paramIndex - Zero-relative parameter index to set (from the body of this element)

addCallParam

public void addCallParam(String pattern,
                         int paramIndex,
                         String attributeName)
Add a "call parameter" rule for the specified parameters.
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

addCallParam

public void addCallParam(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:
paramIndex - The zero-relative parameter number
fromStack - Should the call parameter be taken from the top of the stack?

addCallParam

public void addCallParam(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:
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

addCallParamPath

public void addCallParamPath(String pattern,
                             int paramIndex)
Add a "call parameter" rule that sets a parameter from the current 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

addFactoryCreate

public void addFactoryCreate(String pattern,
                             Class clazz)
Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.
Parameters:
pattern - Element matching pattern
clazz - Java class of the object creation factory class

addFactoryCreate

public void addFactoryCreate(String pattern,
                             Class clazz,
                             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 pattern
clazz - Java class of the object creation factory class
attributeName - Attribute name which, if present, overrides the value specified by className

addFactoryCreate

public void addFactoryCreate(String pattern,
                             Class clazz,
                             String attributeName,
                             boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
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.

addFactoryCreate

public void addFactoryCreate(String pattern,
                             Class clazz,
                             boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
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.

addFactoryCreate

public void addFactoryCreate(String pattern,
                             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 pattern
className - Java class name of the object creation factory class

addFactoryCreate

public void addFactoryCreate(String pattern,
                             String className,
                             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 pattern
className - Java class name of the object creation factory class
attributeName - Attribute name which, if present, overrides the value specified by className

addFactoryCreate

public void addFactoryCreate(String pattern,
                             String className,
                             String attributeName,
                             boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
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.

addFactoryCreate

public void addFactoryCreate(String pattern,
                             String className,
                             boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
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.

addFactoryCreate

public void addFactoryCreate(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 pattern
creationFactory - Previously instantiated ObjectCreationFactory to be utilized

addFactoryCreate

public void addFactoryCreate(String pattern,
                             ObjectCreationFactory creationFactory,
                             boolean ignoreCreateExceptions)
Add a "factory create" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
creationFactory - Previously instantiated ObjectCreationFactory to be utilized
ignoreCreateExceptions - when true any exceptions thrown during object creation will be ignored.

addObjectCreate

public void addObjectCreate(String pattern,
                            Class clazz)
Add an "object create" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
clazz - Java class to be created

addObjectCreate

public void addObjectCreate(String pattern,
                            String className)
Add an "object create" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
className - Java class name to be created

addObjectCreate

public void addObjectCreate(String pattern,
                            String attributeName,
                            Class clazz)
Add an "object create" rule for the specified parameters.
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

addObjectCreate

public void addObjectCreate(String pattern,
                            String className,
                            String attributeName)
Add an "object create" rule for the specified parameters.
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

addObjectParam

public void addObjectParam(String pattern,
                           int paramIndex,
                           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:
paramIndex - The zero-relative parameter number
paramObj - Any arbitrary object to be passed to the target method.
Since:
1.6

addRule

public void addRule(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 pattern
rule - 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

addSetNestedProperties

public void addSetNestedProperties(String pattern)
Parameters:
pattern - register the rule with this pattern
Since:
1.6

addSetNestedProperties

public void addSetNestedProperties(String pattern,
                                   String elementName,
                                   String propertyName)
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

addSetNestedProperties

public void addSetNestedProperties(String pattern,
                                   String[] elementNames,
                                   String[] propertyNames)
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

addSetNext

public void addSetNext(String pattern,
                       String methodName)
Add a "set next" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
methodName - Method name to call on the parent element

addSetNext

public void addSetNext(String pattern,
                       String methodName,
                       String paramType)
Add a "set next" rule for the specified parameters.
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)

addSetProperties

public void addSetProperties(String pattern)
Add a "set properties" rule for the specified parameters.
Parameters:
pattern - Element matching pattern

addSetProperties

public void addSetProperties(String pattern,
                             String attributeName,
                             String propertyName)
Add a "set properties" rule with a single overridden parameter. See SetPropertiesRule.SetPropertiesRule(String attributeName, String propertyName)
Parameters:
pattern - Element matching pattern
attributeName - map this attribute
propertyName - to this property

addSetProperties

public void addSetProperties(String pattern,
                             String[] attributeNames,
                             String[] propertyNames)
Add a "set properties" rule with overridden parameters. See SetPropertiesRule.SetPropertiesRule(String [] attributeNames, String [] propertyNames)
Parameters:
pattern - Element matching pattern
attributeNames - names of attributes with custom mappings
propertyNames - property names these attributes map to

addSetProperty

public void addSetProperty(String pattern,
                           String name,
                           String value)
Add a "set property" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
name - Attribute name containing the property name to be set
value - Attribute name containing the property value to set

addSetRoot

public void addSetRoot(String pattern,
                       String methodName)
Add SetRootRule with the specified parameters.
Parameters:
pattern - Element matching pattern
methodName - Method name to call on the root object
See Also:
SetRootRule

addSetRoot

public void addSetRoot(String pattern,
                       String methodName,
                       String paramType)
Add SetRootRule with the specified parameters.
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

addSetTop

public void addSetTop(String pattern,
                      String methodName)
Add a "set top" rule for the specified parameters.
Parameters:
pattern - Element matching pattern
methodName - Method name to call on the parent element

addSetTop

public void addSetTop(String pattern,
                      String methodName,
                      String paramType)
Add a "set top" rule for the specified parameters.
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)

characters

public void characters(buffer[] ,
                       int start,
                       int length)
            throws SAXException
Process notification of character data received from the body of an XML element.
Parameters:
start - Starting offset into the buffer
length - Number of characters from the buffer

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

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. In general, a separate Digester object should be created for each document to be parsed.


configure

protected void configure()

createInputSourceFromURL

public InputSource createInputSourceFromURL(String url)
            throws MalformedURLException,
                   IOException
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

createInputSourceFromURL

public InputSource createInputSourceFromURL(URL url)
            throws MalformedURLException,
                   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.
Since:
1.8

createSAXException

public SAXException createSAXException(Exception e)
Create a SAX exception which also understands about the location in the digester file where the exception occurs
Returns:
the new exception

createSAXException

public SAXException createSAXException(String message)
Create a SAX exception which also understands about the location in the digester file where the exception occurs
Returns:
the new exception

createSAXException

public SAXException createSAXException(String message,
                                       Exception e)
Create a SAX exception which also understands about the location in the digester file where the exception occurs
Returns:
the new exception

endDocument

public void endDocument()
            throws SAXException
Process notification of the end of the document being reached.

endElement

public void endElement(String namespaceURI,
                       String localName,
                       String qName)
            throws SAXException
Process notification of the end of an XML element being reached.
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.

endPrefixMapping

public void endPrefixMapping(String prefix)
            throws SAXException
Process notification that a namespace prefix is going out of scope.
Parameters:
prefix - Prefix that is going out of scope

error

public void error(SAXParseException exception)
            throws SAXException
Forward notification of a parsing error to the application supplied error handler (if any).
Parameters:
exception - The error information

fatalError

public void fatalError(SAXParseException exception)
            throws SAXException
Forward notification of a fatal parsing error to the application supplied error handler (if any).
Parameters:
exception - The fatal error information

findNamespaceURI

public String findNamespaceURI(String prefix)
Return the currently mapped namespace URI for the specified prefix, if any; otherwise return null. These mappings come and go dynamically as the document is parsed.
Parameters:
prefix - Prefix to look up

getClassLoader

public 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.

getCount

public int getCount()
Return the current depth of the element stack.

getCurrentElementName

public String getCurrentElementName()
Return the name of the XML element that is currently being processed.

getCurrentNamespaces

public Map 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

getCustomContentHandler

public ContentHandler getCustomContentHandler()

getDebug

public int getDebug()

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.

getDocumentLocator

public Locator getDocumentLocator()
Gets the document locator associated with our parser.
Returns:
the Locator supplied by the document parser

getEntityResolver

public EntityResolver getEntityResolver()
Return the Entity Resolver used by the SAX parser.
Returns:
Return the Entity Resolver used by the SAX parser.

getErrorHandler

public ErrorHandler getErrorHandler()
Return the error handler for this Digester.

getFactory

public SAXParserFactory getFactory()
Return the SAXParserFactory we will use, creating one if necessary.

getFeature

public boolean getFeature(String feature)
            throws ParserConfigurationException,
                   SAXNotRecognizedException,
                   SAXNotSupportedException
Parameters:
feature - Name of the feature to inquire about

getLogger

public Log getLogger()
Return the current Logger associated with this instance of the Digester

getMatch

public String getMatch()
Return the current rule match path

getNamespaceAware

public boolean getNamespaceAware()
Return the "namespace aware" flag for parsers we create.

getParser

public SAXParser getParser()
Return the SAXParser we will use to parse the input stream. If there is a problem creating the parser, return null.

getProperty

public Object getProperty(String property)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException
Parameters:
property - Property name to be retrieved

getPublicId

public String getPublicId()
Return the public identifier of the DTD we are currently parsing under, if any.

getReader

public XMLReader getReader()

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.

getRegistrations

(package private)  Map getRegistrations()
Return the set of DTD URL registrations, keyed by public identifier.

getRoot

public Object 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.

Returns:
the root object that has been created after parsing or null if the digester has not parsed any XML yet.

getRuleNamespaceURI

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

getRules

public Rules getRules()
Return the Rules implementation object containing our rules collection and associated matching policy. If none has been established, a default implementation will be created and returned.

getRules

(package private)  List getRules(String match)

Deprecated. Call match() on the Rules implementation returned by getRules()

Return the set of rules that apply to the specified match position. The selected rules are those that match exactly, or those rules that specify a suffix match and the tail of the rule matches the current match position. Exact matches have precedence over suffix matches, then (among suffix matches) the longest match is preferred.
Parameters:
match - The current match position

getSAXLogger

public Log getSAXLogger()
Gets the logger used for logging SAX-related information. Note the output is finely grained.
Since:
1.6

getSchema

public String getSchema()
Return the XML Schema URI used for validating an XML instance.

getSchemaLanguage

public String getSchemaLanguage()
Return the XML Schema language used when parsing.

getStackAction

public StackAction getStackAction()
See setStackAction.
Since:
1.8

getSubstitutor

public Substitutor getSubstitutor()
Gets the Substitutor used to convert attributes and body text.
Returns:
Substitutor, null if not substitutions are to be performed.

getUseContextClassLoader

public boolean getUseContextClassLoader()
Return the boolean as to whether the context classloader should be used.

getValidating

public boolean getValidating()
Return the validating parser flag.

getXMLReader

public XMLReader getXMLReader()
            throws SAXException
Return the XMLReader to be used for parsing the input document. FIX ME: there is a bug in JAXP/XERCES that prevent the use of a parser that contains a schema with a DTD.

ignorableWhitespace

public void ignorableWhitespace(buffer[] ,
                                int start,
                                int len)
            throws SAXException
Process notification of ignorable whitespace received from the body of an XML element.
Parameters:
start - Starting offset into the buffer
len - Number of characters from the buffer

initialize

protected void initialize()
Since:
1.6

isEmpty

public boolean isEmpty(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

log

public void log(String message)

Deprecated. Call getLogger() and use it's logging methods

Log a message to our associated logger.
Parameters:
message - The message to be logged

log

public void log(String message,
                Throwable exception)

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

notationDecl

public void notationDecl(String name,
                         String publicId,
                         String systemId)
Receive notification of a notation declaration event.
Parameters:
name - The notation name
publicId - The public identifier (if any)
systemId - The system identifier (if any)

parse

public Object parse(File file)
            throws IOException,
                   SAXException
Parse the content of the specified file using this Digester. Returns the root element from the object stack (if any).
Parameters:
file - File containing the XML data to be parsed

parse

public Object parse(InputSource input)
            throws IOException,
                   SAXException
Parse the content of the specified input source using this Digester. Returns the root element from the object stack (if any).
Parameters:
input - Input source containing the XML data to be parsed

parse

public Object parse(InputStream input)
            throws IOException,
                   SAXException
Parse the content of the specified input stream using this Digester. Returns the root element from the object stack (if any).
Parameters:
input - Input stream containing the XML data to be parsed

parse

public Object parse(Reader reader)
            throws IOException,
                   SAXException
Parse the content of the specified reader using this Digester. Returns the root element from the object stack (if any).
Parameters:
reader - Reader containing the XML data to be parsed

parse

public Object parse(String uri)
            throws IOException,
                   SAXException
Parse the content of the specified URI using this Digester. Returns the root element from the object stack (if any).
Parameters:
uri - URI containing the XML data to be parsed

parse

public Object parse(URL url)
            throws IOException,
                   SAXException
Parse the content of the specified URL using this Digester. Returns the root element from the object stack (if any).
Parameters:
Since:
1.8

peek

public Object peek()
Return the top object on the stack without removing it. If there are no objects on the stack, return null.

peek

public Object peek(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.

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 Object peek(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.

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.
Since:
1.6

peek

public 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. If the specified index is out of range, return 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.

peekParams

public Object peekParams()

peekParams

public Object peekParams(int n)
Parameters:
n - Index of the desired element, where 0 is the top of the stack, 1 is the next element down, and so on.

pop

public Object pop()
Pop the top object off of the stack, and return it. If there are no objects on the stack, return null.

pop

public 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.

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

popParams

public Object popParams()

processingInstruction

public void processingInstruction(String target,
                                  String data)
            throws SAXException
Process notification of a processing instruction that was encountered.
Parameters:
target - The processing instruction target
data - The processing instruction data (if any)

push

public void push(Object object)
Push a new object onto the top of the object stack.
Parameters:
object - The new object

push

public void push(String stackName,
                 Object 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.
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

pushParams

public void pushParams(Object object)
Parameters:
object - The new object

register

public void register(String publicId,
                     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 resolved
entityURL - The URL to use for reading this entity

register

public void register(String publicId,
                     URL entityURL)
Parameters:
publicId - Public identifier of the DTD to be resolved
entityURL - The URL to use for reading this DTD
Since:
1.8

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

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
            throws SAXException
Resolve the requested external entity.
Parameters:
publicId - The public identifier of the entity being referenced
systemId - The system identifier of the entity being referenced

setClassLoader

public void setClassLoader(ClassLoader classLoader)
Set the class loader to be used for instantiating application objects when required.
Parameters:
classLoader - The new class loader to use, or null to revert to the standard rules

setCustomContentHandler

public void setCustomContentHandler(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.
Since:
1.7

setDebug

public void setDebug(int debug)

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)

setDocumentLocator

public void setDocumentLocator(Locator locator)
Sets the document locator associated with our parser.
Parameters:
locator - The new locator

setEntityResolver

public void setEntityResolver(EntityResolver entityResolver)
Set the 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.

setErrorHandler

public void setErrorHandler(ErrorHandler errorHandler)
Set the error handler for this Digester.
Parameters:
errorHandler - The new error handler

setFeature

public void setFeature(String feature,
                       boolean value)
            throws ParserConfigurationException,
                   SAXNotRecognizedException,
                   SAXNotSupportedException
Sets a flag indicating whether the requested feature is supported by the underlying implementation of 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

setLogger

public void setLogger(Log log)
Set the current logger for this Digester.

setNamespaceAware

public void setNamespaceAware(boolean namespaceAware)
Set the "namespace aware" flag for parsers we create.
Parameters:
namespaceAware - The new "namespace aware" flag

setProperty

public void setProperty(String property,
                        Object value)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException
Parameters:
property - Property name to be set
value - Property value to be set

setPublicId

public void setPublicId(String publicId)
Set the publid id of the current file being parse.
Parameters:
publicId - the DTD/Schema public's id.

setRuleNamespaceURI

public void setRuleNamespaceURI(String ruleNamespaceURI)
Set the namespace URI that will be applied to all subsequently added Rule objects.
Parameters:
ruleNamespaceURI - Namespace URI that must match on all subsequently added rules, or null for matching regardless of the current namespace URI

setRules

public void setRules(Rules rules)
Set the Rules implementation object containing our rules collection and associated matching policy.
Parameters:
rules - New Rules implementation

setSAXLogger

public void setSAXLogger(Log saxLog)
Sets the logger used for logging SAX-related information. Note the output is finely grained.
Parameters:
saxLog - Log, not null
Since:
1.6

setSchema

public void setSchema(String schemaLocation)
Set the XML Schema URI used for validating the input XML.

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.

setSchemaLanguage

public void setSchemaLanguage(String schemaLanguage)
Set the XML Schema language used when parsing. By default, we use W3C.
Parameters:
schemaLanguage - a URI to the schema language.

setStackAction

public 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.
Since:
1.8

setSubstitutor

public void setSubstitutor(Substitutor substitutor)
Sets the 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.

setUseContextClassLoader

public 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. If not using Context ClassLoader, then the class-loading defaults to using the calling-class' ClassLoader.
Parameters:
use - determines whether to use Context ClassLoader.

setValidating

public void setValidating(boolean validating)
Set the validating parser flag. This must be called before parse() is called the first time.
Parameters:
validating - The new validating parser flag.

skippedEntity

public void skippedEntity(String name)
            throws SAXException
Process notification of a skipped entity.
Parameters:
name - Name of the skipped entity

startDocument

public void startDocument()
            throws SAXException
Process notification of the beginning of the document being reached.

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes list)
            throws SAXException
Process notification of the start of an XML element being reached.
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.

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String namespaceURI)
            throws SAXException
Process notification that a namespace prefix is coming in to scope.
Parameters:
prefix - Prefix that is being declared
namespaceURI - Corresponding namespace URI being mapped to

unparsedEntityDecl

public void unparsedEntityDecl(String name,
                               String publicId,
                               String systemId,
                               String notation)
Receive notification of an unparsed entity declaration event.
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

warning

public void warning(SAXParseException exception)
            throws SAXException
Forward notification of a parse warning to the application supplied error handler (if any).
Parameters:
exception - The warning information

Copyright 2001-2005 The Apache Software Foundation.