Package org.apache.tomcat.util.digester

Class Digester

java.lang.Object

org.xml.sax.helpers.DefaultHandler

org.xml.sax.ext.DefaultHandler2

org.apache.tomcat.util.digester.Digester

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler, DeclHandler, EntityResolver2, LexicalHandler

public class Digester
extends DefaultHandler2

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Digester.GeneratedCodeLoader

Field Summary

Fields

Modifier and Type	Field	Description
protected StringBuilder	bodyText	The body text of the current element.
protected ArrayStack<StringBuilder>	bodyTexts	The stack of body text string buffers for surrounding elements.
protected ClassLoader	classLoader	The class loader to use for instantiating application objects.
protected StringBuilder	code	Generated code.
protected boolean	configured	Has this Digester been configured yet.
protected EntityResolver	entityResolver	The EntityResolver used by the SAX parser.
protected HashMap<String,String>	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 Map<Class<?>,List<String>>	fakeAttributes	Fake attributes map (attributes are often used for object creation).
protected ArrayList<Object>	known
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<List<Rule>>	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<String,ArrayStack<String>>	namespaces	Registered namespaces we are currently processing.
protected ArrayStack<Object>	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 static IntrospectionUtils.PropertySource[]	propertySources
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 boolean	rulesValidation	Warn on missing attributes and elements.
protected Log	saxLog	The Log to which all SAX event related logging calls will be made.
protected static final StringManager	sm
protected IntrospectionUtils.PropertySource[]	source
protected ArrayStack<Object>	stack	The object stack being constructed.
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

Constructors

Constructor	Description
Digester()

Method Summary

Modifier and Type	Method	Description
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	addCallParam(String pattern, int paramIndex)	Add a "call parameter" rule for the specified parameters.
void	addFactoryCreate(String pattern, ObjectCreationFactory creationFactory, boolean ignoreCreateExceptions)	Add a "factory create" rule for the specified parameters.
static void	addGeneratedClass(String className)
void	addObjectCreate(String pattern, String className)	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	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	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[] excludes)
void	characters(char[] buffer, int start, int length)	Process notification of character data received from the body of an XML element.
void	clear()	Clear the current contents of the object stack.
protected void	configure()	Provide a hook for lazy configuration of this Digester instance.
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	endGeneratingCode()
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()
String	getCurrentElementName()
Locator	getDocumentLocator()	Gets the document locator associated with our parser.
EntityResolver	getEntityResolver()	Return the Entity Resolver used by the SAX parser.
ErrorHandler	getErrorHandler()
SAXParserFactory	getFactory()	SAX parser factory method.
Map<Class<?>,List<String>>	getFakeAttributes()
static String[]	getGeneratedClasses()
StringBuilder	getGeneratedCode()
Log	getLogger()
String	getMatch()
boolean	getNamespaceAware()
SAXParser	getParser()
Object	getProperty(String property)	Return the current value of the specified property for the underlying XMLReader implementation.
String	getPublicId()
Object	getRoot()	When the Digester is being used as a SAXContentHandler, this method allows you to access the root object that has been created after parsing.
Rules	getRules()	Return the Rules implementation object containing our rules collection and associated matching policy.
boolean	getRulesValidation()
Log	getSAXLogger()	Gets the logger used for logging SAX-related information.
boolean	getUseContextClassLoader()
boolean	getValidating()
XMLReader	getXMLReader()	Return the XMLReader to be used for parsing the input document.
void	ignorableWhitespace(char[] buffer, int start, int len)	Process notification of ignorable whitespace received from the body of an XML element.
boolean	isFakeAttribute(Object object, String name)	Determine if an attribute is a fake attribute.
static boolean	isGeneratedCodeLoaderSet()
static Object	loadGeneratedClass(String className)
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(InputStream input)	Parse the content of the specified input stream using this Digester.
Object	parse(InputSource input)	Parse the content of the specified input source using this Digester.
Object	peek()	Return the top object on the stack without removing it.
Object	peek(int n)	Return the n'th object down the stack, where 0 is the top element and [getCount()-1] is the bottom element.
Object	peekParams()	Return the top object on the parameters stack without removing it.
Object	pop()	Pop the top object off of the stack, and return it.
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	pushParams(Object object)	Push a new object onto the top of the parameters stack.
void	register(String publicId, String entityURL)	Register the specified DTD URL for the specified public identifier.
static void	replaceSystemProperties()
void	reset()
InputSource	resolveEntity(String name, String publicId, String baseURI, String systemId)
void	setClassLoader(ClassLoader classLoader)	Set the class loader to be used for instantiating application objects when required.
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	setFakeAttributes(Map<Class<?>,List<String>> fakeAttributes)	Set the fake attributes.
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.
static void	setGeneratedCodeLoader(Digester.GeneratedCodeLoader generatedCodeLoader)
void	setKnown(Object object)
void	setLogger(Log log)	Set the current logger for this Digester.
void	setNamespaceAware(boolean namespaceAware)	Set the "namespace aware" flag for parsers we create.
static void	setPropertySource(IntrospectionUtils.PropertySource propertySource)
static void	setPropertySource(IntrospectionUtils.PropertySource[] propertySources)
void	setPublicId(String publicId)	Set the public id of the current file being parse.
void	setRules(Rules rules)	Set the Rules implementation object containing our rules collection and associated matching policy.
void	setRulesValidation(boolean rulesValidation)	Set the rules validation flag.
void	setSAXLogger(Log saxLog)	Sets the logger used for logging SAX-related information.
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	startDTD(String name, String publicId, String systemId)
void	startElement(String namespaceURI, String localName, String qName, Attributes list)	Process notification of the start of an XML element being reached.
void	startGeneratingCode()
void	startPrefixMapping(String prefix, String namespaceURI)	Process notification that a namespace prefix is coming in to scope.
String	toVariableName(Object object)
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).

Methods inherited from class org.xml.sax.ext.DefaultHandler2

attributeDecl, comment, elementDecl, endCDATA, endDTD, endEntity, externalEntityDecl, getExternalSubset, internalEntityDecl, resolveEntity, startCDATA, startEntity

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.xml.sax.ContentHandler

declaration

Field Details

propertySources

protected static IntrospectionUtils.PropertySource[] propertySources

sm

protected static final StringManager sm

source

protected IntrospectionUtils.PropertySource[] source

bodyText

protected StringBuilder bodyText

The body text of the current element.

bodyTexts

protected ArrayStack<StringBuilder> bodyTexts

The stack of body text string buffers for surrounding elements.

matches

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

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.

entityResolver

protected EntityResolver entityResolver

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

entityValidator

protected HashMap<String,String> 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.

locator

protected Locator locator

The Locator associated with our parser.

match

protected String match

The current match pattern for nested element processing.

namespaceAware

protected boolean namespaceAware

Do we want a "namespace aware" parser.

namespaces

protected HashMap<String,ArrayStack<String>> 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<Object> 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.

stack

protected ArrayStack<Object> stack

The object stack being constructed.

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.

rulesValidation

protected boolean rulesValidation

Warn on missing attributes and elements.

fakeAttributes

protected Map<Class<?>,List<String>> fakeAttributes

Fake attributes map (attributes are often used for object creation).

log

protected Log log

The Log to which most logging calls will be made.

saxLog

protected Log saxLog

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

code

protected StringBuilder code

Generated code.

known

protected ArrayList<Object> known

Constructor Details

Digester

public Digester()

Method Details

setPropertySource

public static void setPropertySource(IntrospectionUtils.PropertySource propertySource)

setPropertySource

public static void setPropertySource(IntrospectionUtils.PropertySource[] propertySources)

addGeneratedClass

public static void addGeneratedClass(String className)

getGeneratedClasses

public static String[] getGeneratedClasses()

isGeneratedCodeLoaderSet

public static boolean isGeneratedCodeLoaderSet()

setGeneratedCodeLoader

public static void setGeneratedCodeLoader(Digester.GeneratedCodeLoader generatedCodeLoader)

loadGeneratedClass

public static Object loadGeneratedClass(String className)

replaceSystemProperties

public static void replaceSystemProperties()

startGeneratingCode

public void startGeneratingCode()

endGeneratingCode

public void endGeneratingCode()

getGeneratedCode

public StringBuilder getGeneratedCode()

setKnown

public void setKnown(Object object)

toVariableName

public String toVariableName(Object object)

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

Returns:

the namespace URI

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.

Returns:

the classloader

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

getCount

public int getCount()

Returns:

the current depth of the element stack.

getCurrentElementName

public String getCurrentElementName()

Returns:

the name of the XML element that is currently being processed.

getErrorHandler

public ErrorHandler getErrorHandler()

Returns:

the error handler for this Digester.

setErrorHandler

public void setErrorHandler(ErrorHandler errorHandler)

Set the error handler for this Digester.

Parameters:

errorHandler - The new error handler

getFactory

public SAXParserFactory getFactory()
                            throws SAXNotRecognizedException,
SAXNotSupportedException,
ParserConfigurationException

SAX parser factory method.

Returns:

the SAXParserFactory we will use, creating one if necessary.

Throws:

ParserConfigurationException - Error creating parser

SAXNotSupportedException - Error creating parser

SAXNotRecognizedException - Error creating parser

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 http://www.saxproject.org/apidoc/xml/sax/package-summary.html#package-description for information about the standard SAX2 feature flags. In order to be effective, this method must be called before the getParser() method is called for the first time, either directly or indirectly.

Parameters:

feature - Name of the feature to set the status for

value - The new value for this feature

Throws:

ParserConfigurationException - if a parser configuration error occurs

SAXNotRecognizedException - if the property name is not recognized

SAXNotSupportedException - if the property name is recognized but not supported

getLogger

public Log getLogger()

Returns:

the current Logger associated with this instance of the Digester

setLogger

public void setLogger(Log log)

Set the current logger for this Digester.

Parameters:

log - The logger that will be used

getSAXLogger

public Log getSAXLogger()

Gets the logger used for logging SAX-related information. Note the output is finely grained.

Returns:

the SAX logger

Since:

1.6

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

getMatch

public String getMatch()

Returns:

the current rule match path

getNamespaceAware

public boolean getNamespaceAware()

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

setPublicId

public void setPublicId(String publicId)

Set the public id of the current file being parse.

Parameters:

publicId - the DTD/Schema public's id.

getPublicId

public String getPublicId()

Returns:

the public identifier of the DTD we are currently parsing under, if any.

getParser

public SAXParser getParser()

Returns:

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

Return the current value of the specified property for the underlying XMLReader implementation. See http://www.saxproject.org/apidoc/xml/sax/package-summary.html#package-description for information about the standard SAX2 properties.

Parameters:

property - Property name to be retrieved

Returns:

the property value

Throws:

SAXNotRecognizedException - if the property name is not recognized

SAXNotSupportedException - if the property name is recognized but not supported

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.

Returns:

the rules

setRules

public void setRules(Rules rules)

Set the Rules implementation object containing our rules collection and associated matching policy.

Parameters:

rules - New Rules implementation

getUseContextClassLoader

public boolean getUseContextClassLoader()

Returns:

the boolean as to whether the context classloader should be used.

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.

getValidating

public boolean getValidating()

Returns:

the validating parser flag.

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.

getRulesValidation

public boolean getRulesValidation()

Returns:

the rules validation flag.

setRulesValidation

public void setRulesValidation(boolean rulesValidation)

Set the rules validation flag. This must be called before parse() is called the first time.

Parameters:

rulesValidation - The new rules validation flag.

getFakeAttributes

public Map<Class<?>,List<String>> getFakeAttributes()

Returns:

the fake attributes list.

isFakeAttribute

public boolean isFakeAttribute(Object object,
 String name)

Determine if an attribute is a fake attribute.

Parameters:

object - The object

name - The attribute name

Returns:

true if this is a fake attribute

setFakeAttributes

public void setFakeAttributes(Map<Class<?>,List<String>> fakeAttributes)

Set the fake attributes.

Parameters:

fakeAttributes - The new fake attributes.

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.

Returns:

the XML reader

Throws:

SAXException - if no XMLReader can be instantiated

characters

public void characters(char[] buffer,
 int start,
 int length)
                throws SAXException

Process notification of character data received from the body of an XML element.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class DefaultHandler

Parameters:

buffer - The characters from the XML document

start - Starting offset into the buffer

length - Number of characters from the buffer

Throws:

SAXException - if a parsing error is to be reported

endDocument

public void endDocument()
                 throws SAXException

Process notification of the end of the document being reached.

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class DefaultHandler

Throws:

SAXException - if a parsing error is to be reported

endElement

public void endElement(String namespaceURI,
 String localName,
 String qName)
                throws SAXException

Process notification of the end of an XML element being reached.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class DefaultHandler

Parameters:

namespaceURI - - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

localName - - The local name (without prefix), or the empty string if Namespace processing is not being performed.

qName - - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.

Throws:

SAXException - if a parsing error is to be reported

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Process notification that a namespace prefix is going out of scope.

Specified by:

endPrefixMapping in interface ContentHandler

Overrides:

endPrefixMapping in class DefaultHandler

Parameters:

prefix - Prefix that is going out of scope

Throws:

SAXException - if a parsing error is to be reported

ignorableWhitespace

public void ignorableWhitespace(char[] buffer,
 int start,
 int len)
                         throws SAXException

Process notification of ignorable whitespace received from the body of an XML element.

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

ignorableWhitespace in class DefaultHandler

Parameters:

buffer - The characters from the XML document

start - Starting offset into the buffer

len - Number of characters from the buffer

Throws:

SAXException - if a parsing error is to be reported

processingInstruction

public void processingInstruction(String target,
 String data)
                           throws SAXException

Process notification of a processing instruction that was encountered.

Specified by:

processingInstruction in interface ContentHandler

Overrides:

processingInstruction in class DefaultHandler

Parameters:

target - The processing instruction target

data - The processing instruction data (if any)

Throws:

SAXException - if a parsing error is to be reported

getDocumentLocator

public Locator getDocumentLocator()

Gets the document locator associated with our parser.

Returns:

the Locator supplied by the document parser

setDocumentLocator

public void setDocumentLocator(Locator locator)

Sets the document locator associated with our parser.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

setDocumentLocator in class DefaultHandler

Parameters:

locator - The new locator

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Process notification of a skipped entity.

Specified by:

skippedEntity in interface ContentHandler

Overrides:

skippedEntity in class DefaultHandler

Parameters:

name - Name of the skipped entity

Throws:

SAXException - if a parsing error is to be reported

startDocument

public void startDocument()
                   throws SAXException

Process notification of the beginning of the document being reached.

Specified by:

startDocument in interface ContentHandler

Overrides:

startDocument in class DefaultHandler

Throws:

SAXException - if a parsing error is to be reported

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.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class DefaultHandler

Parameters:

namespaceURI - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.

qName - The qualified name (with prefix), or the empty string if qualified names are not available.\

list - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.

Throws:

SAXException - if a parsing error is to be reported

startPrefixMapping

public void startPrefixMapping(String prefix,
 String namespaceURI)
                        throws SAXException

Process notification that a namespace prefix is coming in to scope.

Specified by:

startPrefixMapping in interface ContentHandler

Overrides:

startPrefixMapping in class DefaultHandler

Parameters:

prefix - Prefix that is being declared

namespaceURI - Corresponding namespace URI being mapped to

Throws:

SAXException - if a parsing error is to be reported

notationDecl

public void notationDecl(String name,
 String publicId,
 String systemId)

Receive notification of a notation declaration event.

Specified by:

notationDecl in interface DTDHandler

Overrides:

notationDecl in class DefaultHandler

Parameters:

name - The notation name

publicId - The public identifier (if any)

systemId - The system identifier (if any)

unparsedEntityDecl

public void unparsedEntityDecl(String name,
 String publicId,
 String systemId,
 String notation)

Receive notification of an unparsed entity declaration event.

Specified by:

unparsedEntityDecl in interface DTDHandler

Overrides:

unparsedEntityDecl in class DefaultHandler

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

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.

getEntityResolver

public EntityResolver getEntityResolver()

Return the Entity Resolver used by the SAX parser.

Returns:

Return the Entity Resolver used by the SAX parser.

resolveEntity

public InputSource resolveEntity(String name,
 String publicId,
 String baseURI,
 String systemId)
                          throws SAXException,
IOException

Specified by:

resolveEntity in interface EntityResolver2

Overrides:

resolveEntity in class DefaultHandler2

Throws:

SAXException

IOException

startDTD

public void startDTD(String name,
 String publicId,
 String systemId)
              throws SAXException

Specified by:

startDTD in interface LexicalHandler

Overrides:

startDTD in class DefaultHandler2

Throws:

SAXException

error

public void error(SAXParseException exception)
           throws SAXException

Forward notification of a parsing error to the application supplied error handler (if any).

Specified by:

error in interface ErrorHandler

Overrides:

error in class DefaultHandler

Parameters:

exception - The error information

Throws:

SAXException - if a parsing exception occurs

fatalError

public void fatalError(SAXParseException exception)
                throws SAXException

Forward notification of a fatal parsing error to the application supplied error handler (if any).

Specified by:

fatalError in interface ErrorHandler

Overrides:

fatalError in class DefaultHandler

Parameters:

exception - The fatal error information

Throws:

SAXException - if a parsing exception occurs

warning

public void warning(SAXParseException exception)
             throws SAXException

Forward notification of a parse warning to the application supplied error handler (if any).

Specified by:

warning in interface ErrorHandler

Overrides:

warning in class DefaultHandler

Parameters:

exception - The warning information

Throws:

SAXException - if a parsing exception occurs

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

Returns:

the root object

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

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

Returns:

the root object

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

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

Returns:

the root object

Throws:

IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

register

public void register(String publicId,
 String entityURL)

Register the specified DTD URL for the specified public identifier. This must be called before the first call to parse().

Digester contains an internal EntityResolver implementation. This maps PUBLICID's to URLs (from which the resource will be loaded). A common use case for this method is to register local URLs (possibly computed at runtime by a classloader) for DTDs. This allows the performance advantage of using a local version without having to ensure every SYSTEM URI on every processed xml document is local. This implementation provides only basic functionality. If more sophisticated features are required, using setEntityResolver(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 custom EntityResolver overrides the internal implementation.)

Parameters:

publicId - Public identifier of the DTD to be resolved

entityURL - The URL to use for reading this DTD

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

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

See Also:

• CallMethodRule

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)

See Also:

• CallMethodRule

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)

See Also:

• CallParamRule

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.

See Also:

• FactoryCreateRule

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

See Also:

• ObjectCreateRule

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

See Also:

• ObjectCreateRule

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 corresponding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)

See Also:

• SetNextRule

addSetProperties

public void addSetProperties(String pattern)

Add a "set properties" rule for the specified parameters.

Parameters:

pattern - Element matching pattern

See Also:

• SetPropertiesRule

addSetProperties

public void addSetProperties(String pattern,
 String[] excludes)

clear

public void clear()

Clear the current contents of the object stack.

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.

reset

public void reset()

peek

public Object peek()

Return the top object on the stack without removing it. If there are no objects on the stack, return null.

Returns:

the top object

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.

Returns:

the specified object

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.

Returns:

the top object

push

public void push(Object object)

Push a new object onto the top of the object stack.

Parameters:

object - The new object

getRoot

public Object getRoot()

When the Digester is being used as a SAXContentHandler, this method allows you to access the root object that has been created after parsing.

Returns:

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

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.

peekParams

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

Returns:

the top object on the parameters stack

popParams

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

Returns:

the top object on the parameters stack

pushParams

public void pushParams(Object object)

Push a new object onto the top of the parameters stack.

The parameters stack is used to store CallMethodRule parameters. See params.

Parameters:

object - The new object

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

Parameters:

message - The error message

e - The root cause

Returns:

the new exception

createSAXException

public SAXException createSAXException(Exception e)

Create a SAX exception which also understands about the location in the digester file where the exception occurs

Parameters:

e - The root cause

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

Parameters:

message - The error message

Returns:

the new exception