org.apache.struts.digester
Class Digester

org.apache.struts.digester.Digester

public class Digester

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.

Version:

$Revision: 1.1 $ $Date$

Author:

Craig McClanahan

Field Summary

protected java.lang.StringBuffer	bodyText The body text of the current element.
protected ArrayStack	bodyTexts The stack of body text string buffers for surrounding elements.
protected int	debug The debugging detail level of this component.
protected java.util.HashMap	dtds The URLs of DTDs that have been registered, keyed by the public identifier that corresponds.
protected org.xml.sax.ErrorHandler	errorHandler The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.
protected org.xml.sax.Locator	locator The Locator associated with our parser.
protected java.lang.String	match The current match pattern for nested element processing.
protected javax.xml.parsers.SAXParser	parser The SAXParser we will use to parse the input stream.
protected java.lang.Object	root The "root" element of the stack (in other words, the last object that was popped.
protected java.util.HashMap	rules The set of Rules that have been registered with this Digester.
protected ArrayStack	stack The object stack being constructed.
protected boolean	validating Do we want to use a validating parser?

Constructor Summary

Digester()
Construct a new Digester with default properties.

Method Summary

void	addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount) Add an "call method" rule for the specified parameters.
void	addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes) Add an "call method" rule for the specified parameters.
void	addCallMethod(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes) Add an "call method" rule for the specified parameters.
void	addCallParam(java.lang.String pattern, int paramIndex) Add a "call parameter" rule for the specified parameters.
void	addCallParam(java.lang.String pattern, int paramIndex, java.lang.String attributeName) Add a "call parameter" rule for the specified parameters.
void	addObjectCreate(java.lang.String pattern, java.lang.String className) Add an "object create" rule for the specified parameters.
void	addObjectCreate(java.lang.String pattern, java.lang.String className, java.lang.String attributeName) Add an "object create" rule for the specified parameters.
void	addRule(java.lang.String pattern, Rule rule) Register a new Rule matching the specified pattern.
void	addSetNext(java.lang.String pattern, java.lang.String methodName) Add a "set next" rule for the specified parameters.
void	addSetNext(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType) Add a "set next" rule for the specified parameters.
void	addSetProperties(java.lang.String pattern) Add a "set properties" rule for the specified parameters.
void	addSetProperty(java.lang.String pattern, java.lang.String name, java.lang.String value) Add a "set property" rule for the specified parameters.
void	addSetTop(java.lang.String pattern, java.lang.String methodName) Add a "set top" rule for the specified parameters.
void	addSetTop(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType) Add a "set top" rule for the specified parameters.
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.
void	endDocument() Process notification of the end of the document being reached.
void	endElement(java.lang.String name) Process notification of the end of an XML element being reached.
void	error(org.xml.sax.SAXParseException exception) Forward notification of a parsing error to the application supplied error handler (if any).
void	fatalError(org.xml.sax.SAXParseException exception) Forward notification of a fatal parsing error to the application supplied error handler (if any).
int	getCount() Return the current depth of the element stack.
int	getDebug() Return the debugging detail level of this Digester.
org.xml.sax.ErrorHandler	getErrorHandler() Return the error handler for this Digester.
javax.xml.parsers.SAXParser	getParser() Return the SAXParser we will use to parse the input stream.
protected java.util.List	getRules(java.lang.String match) Return the set of rules that apply to the specified match position.
boolean	getValidating() Return the validating parser flag.
void	ignorableWhitespace(char[] buffer, int start, int len) Process notification of ignorable whitespace received from the body of an XML element.
void	log(java.lang.String message) Log a message to the log writer associated with this context.
void	log(java.lang.String message, java.lang.Throwable exception) Log a message and associated exception to the log writer associated with this context.
void	notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId) Receive notification of a notation declaration event.
java.lang.Object	parse(java.io.File file) Parse the content of the specified file using this Digester.
java.lang.Object	parse(org.xml.sax.InputSource input) Parse the content of the specified input source using this Digester.
java.lang.Object	parse(java.io.InputStream input) Parse the content of the specified input stream using this Digester.
java.lang.Object	parse(java.lang.String uri) Parse the content of the specified URI using this Digester.
java.lang.Object	peek() Return the top object on the stack without removing it.
java.lang.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.
java.lang.Object	pop() Pop the top object off of the stack, and return it.
void	processingInstruction(java.lang.String target, java.lang.String data) Process notification of a processing instruction that was encountered.
void	push(java.lang.Object object) Push a new object onto the top of the object stack.
void	register(java.lang.String publicId, java.lang.String dtdURL) Register the specified DTD URL for the specified public identifier.
org.xml.sax.InputSource	resolveEntity(java.lang.String publicId, java.lang.String systemId) Resolve the requested external entity.
void	setDebug(int debug) Set the debugging detail level of this Digester.
void	setDocumentLocator(org.xml.sax.Locator locator) Set the document locator associated with our parser.
void	setErrorHandler(org.xml.sax.ErrorHandler errorHandler) Set the error handler for this Digester.
void	setValidating(boolean validating) Set the validating parser flag.
void	startDocument() Process notification of the beginning of the document being reached.
void	startElement(java.lang.String name, org.xml.sax.AttributeList list) Process notification of the start of an XML element being reached.
void	unparsedEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notation) Receive notification of an unparsed entity declaration event.
void	warning(org.xml.sax.SAXParseException exception) Forward notification of a parse warning to the application supplied error handler (if any).

Field Detail

bodyText

protected java.lang.StringBuffer bodyText

The body text of the current element.

bodyTexts

protected ArrayStack bodyTexts

The stack of body text string buffers for surrounding elements.

debug

protected int debug

The debugging detail level of this component.

dtds

protected java.util.HashMap dtds

The URLs of DTDs that have been registered, keyed by the public identifier that corresponds.

errorHandler

protected org.xml.sax.ErrorHandler errorHandler

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

locator

protected org.xml.sax.Locator locator

The Locator associated with our parser.

match

protected java.lang.String match

The current match pattern for nested element processing.

parser

protected javax.xml.parsers.SAXParser parser

The SAXParser we will use to parse the input stream.

root

protected java.lang.Object root

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

rules

protected java.util.HashMap rules

The set of Rules that have been registered with this Digester. The key is the matching pattern against the current element stack, and the value is a List containing the Rules for that pattern, in the order that they were registered.

stack

protected ArrayStack stack

The object stack being constructed.

validating

protected boolean validating

Do we want to use a validating parser?

Constructor Detail

Digester

public Digester()

Construct a new Digester with default properties.

Method Detail

getCount

public int getCount()

Return the current depth of the element stack.

getDebug

public int getDebug()

Return the debugging detail level of this Digester.

setDebug

public void setDebug(int debug)

Set the debugging detail level of this Digester.

Parameters:

debug - The new debugging detail level

getErrorHandler

public org.xml.sax.ErrorHandler getErrorHandler()

Return the error handler for this Digester.

setErrorHandler

public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)

Set the error handler for this Digester.

Parameters:

errorHandler - The new error handler

getParser

public javax.xml.parsers.SAXParser getParser()

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

getValidating

public boolean getValidating()

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

characters

public void characters(char[] buffer,
                       int start,
                       int length)
                throws org.xml.sax.SAXException

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

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 org.xml.sax.SAXException

Process notification of the end of the document being reached.

Throws:

SAXException - if a parsing error is to be reported

endElement

public void endElement(java.lang.String name)
                throws org.xml.sax.SAXException

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

Parameters:

name - Name of the element that is ending

Throws:

SAXException - if a parsing error is to be reported

ignorableWhitespace

public void ignorableWhitespace(char[] buffer,
                                int start,
                                int len)
                         throws org.xml.sax.SAXException

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

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

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException

Process notification of a processing instruction that was encountered.

Parameters:

target - The processing instruction target

data - The processing instruction data (if any)

Throws:

SAXException - if a parsing error is to be reported

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)

Set the document locator associated with our parser.

Parameters:

locator - The new locator

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException

Process notification of the beginning of the document being reached.

Throws:

SAXException - if a parsing error is to be reported

startElement

public void startElement(java.lang.String name,
                         org.xml.sax.AttributeList list)
                  throws org.xml.sax.SAXException

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

Parameters:

name - Name of the element that is starting

list - The attributes associated with this element

Throws:

SAXException - if a parsing error is to be reported

notationDecl

public void notationDecl(java.lang.String name,
                         java.lang.String publicId,
                         java.lang.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)

unparsedEntityDecl

public void unparsedEntityDecl(java.lang.String name,
                               java.lang.String publicId,
                               java.lang.String systemId,
                               java.lang.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

resolveEntity

public org.xml.sax.InputSource resolveEntity(java.lang.String publicId,
                                             java.lang.String systemId)
                                      throws org.xml.sax.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

Throws:

SAXException - if a parsing exception occurs

error

public void error(org.xml.sax.SAXParseException exception)
           throws org.xml.sax.SAXException

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

Parameters:

exception - The error information

Throws:

SAXException - if a parsing exception occurs

fatalError

public void fatalError(org.xml.sax.SAXParseException exception)
                throws org.xml.sax.SAXException

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

Parameters:

exception - The fatal error information

Throws:

SAXException - if a parsing exception occurs

warning

public void warning(org.xml.sax.SAXParseException exception)
             throws org.xml.sax.SAXException

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

Parameters:

exception - The warning information

Throws:

SAXException - if a parsing exception occurs

log

public void log(java.lang.String message)

Log a message to the log writer associated with this context.

Parameters:

message - The message to be logged

log

public void log(java.lang.String message,
                java.lang.Throwable exception)

Log a message and associated exception to the log writer associated with this context.

Parameters:

message - The message to be logged

exception - The associated exception to be logged

parse

public java.lang.Object parse(java.io.File file)
                       throws java.io.IOException,
                              org.xml.sax.SAXException

Parse the content of the specified file using this Digester. Returns the root element from the object stack (if any).

Parameters:

file - File containing the XML data to be parsed

Throws:

java.io.IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public java.lang.Object parse(org.xml.sax.InputSource input)
                       throws java.io.IOException,
                              org.xml.sax.SAXException

Parse the content of the specified input source using this Digester. Returns the root element from the object stack (if any).

Parameters:

input - Input source containing the XML data to be parsed

Throws:

java.io.IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public java.lang.Object parse(java.io.InputStream input)
                       throws java.io.IOException,
                              org.xml.sax.SAXException

Parse the content of the specified input stream using this Digester. Returns the root element from the object stack (if any).

Parameters:

input - Input stream containing the XML data to be parsed

Throws:

java.io.IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

parse

public java.lang.Object parse(java.lang.String uri)
                       throws java.io.IOException,
                              org.xml.sax.SAXException

Parse the content of the specified URI using this Digester. Returns the root element from the object stack (if any).

Parameters:

uri - URI containing the XML data to be parsed

Throws:

java.io.IOException - if an input/output error occurs

SAXException - if a parsing exception occurs

register

public void register(java.lang.String publicId,
                     java.lang.String dtdURL)

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

Parameters:

publicId - Public identifier of the DTD to be resolved

dtdURL - The URL to use for reading this DTD

addRule

public void addRule(java.lang.String pattern,
                    Rule rule)

Register a new Rule matching the specified pattern.

Parameters:

pattern - Element matching pattern

rule - Rule to be registered

addCallMethod

public void addCallMethod(java.lang.String pattern,
                          java.lang.String methodName,
                          int paramCount)

Add an "call method" rule for the specified parameters.

Parameters:

pattern - Element matching 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(java.lang.String pattern,
                          java.lang.String methodName,
                          int paramCount,
                          java.lang.String[] paramTypes)

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)

paramTypes - Set of Java class names for the types of the expected parameters (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)

addCallMethod

public void addCallMethod(java.lang.String pattern,
                          java.lang.String methodName,
                          int paramCount,
                          java.lang.Class[] paramTypes)

Add an "call method" rule for the specified parameters.

Parameters:

pattern - Element matching pattern

methodName - Method name to be called

paramCount - Number of expected parameters (or zero for a single parameter from the body of this element)

paramTypes - The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)

addCallParam

public void addCallParam(java.lang.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(java.lang.String pattern,
                         int paramIndex,
                         java.lang.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

addObjectCreate

public void addObjectCreate(java.lang.String pattern,
                            java.lang.String className)

Add an "object create" rule for the specified parameters.

Parameters:

pattern - Element matching pattern

className - Java class name to be created

addObjectCreate

public void addObjectCreate(java.lang.String pattern,
                            java.lang.String className,
                            java.lang.String attributeName)

Add an "object create" rule for the specified parameters.

Parameters:

pattern - Element matching pattern

className - Default Java class name to be created

attributeName - Attribute name that optionally overrides the default Java class name to be created

addSetNext

public void addSetNext(java.lang.String pattern,
                       java.lang.String methodName)

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

Parameters:

pattern - Element matching pattern

methodName - Method name to call on the parent element

addSetNext

public void addSetNext(java.lang.String pattern,
                       java.lang.String methodName,
                       java.lang.String paramType)

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

Parameters:

pattern - Element matching 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(java.lang.String pattern)

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

Parameters:

pattern - Element matching pattern

addSetProperty

public void addSetProperty(java.lang.String pattern,
                           java.lang.String name,
                           java.lang.String value)

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

Parameters:

pattern - Element matching pattern

name - Attribute name containing the property name to be set

value - Attribute name containing the property value to set

addSetTop

public void addSetTop(java.lang.String pattern,
                      java.lang.String methodName)

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

Parameters:

pattern - Element matching pattern

methodName - Method name to call on the parent element

addSetTop

public void addSetTop(java.lang.String pattern,
                      java.lang.String methodName,
                      java.lang.String paramType)

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

Parameters:

pattern - Element matching 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)

clear

public void clear()

Clear the current contents of the object stack.

peek

public java.lang.Object peek()

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

peek

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

pop

public java.lang.Object pop()

Pop the top object off of the stack, and return it. If there are no objects on the stack, return null.

push

public void push(java.lang.Object object)

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

Parameters:

object - The new object

getRules

protected java.util.List getRules(java.lang.String match)

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