Apache Struts API Documentation: Class Digester

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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: 2001-09-17 21:13:30 +0100 (Mon, 17 Sep 2001) $
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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2001 - Apache Software Foundation