http://commons.apache.org/digester/: The Apache Commons Digester package lets you configure an XML to Java object mapping module which triggers certain actions called rules whenever a particular pattern of nested XML elements is recognized. (The Apache Software Foundation)
  • Bradley M. Handy
  • Christopher Lenz
  • Ted Husted
  • David H. Martin
  • Henri Chen
  • Janek Bogucki
  • Mark Huisman
  • Paul Jack
  • Anton Maslovsky
  • Matt Cleveland
  • Gabriele Carcassi
  • Wendy Smoak
  • Kevin Ross
  • Daniele Testa
  • Craig McClanahan
  • Robert Burrell Donkin
  • Scott Sanders
  • James Strachan
  • Jason van Zyl
  • Tim OBrien
  • Jean-Francois Arcand
  • Simon Kitching
  • Rahul Akolkar
  • Simone Tripodi
  • Matt Benson 
package org.apache.commons.digester3;

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import org.xml.sax.Attributes;


Concrete implementations of this class implement actions to be taken when a corresponding nested pattern of XML
elements has been matched.


Writing a custom Rule is considered perfectly normal when using Digester, and is encouraged whenever the default set
of Rule classes don't meet your requirements; the digester framework can help process xml even when the built-in
rules aren't quite what is needed. Creating a custom Rule is just as easy as subclassing
javax.servlet.http.HttpServlet for webapps, or javax.swing.Action for GUI applications.


If a rule wishes to manipulate a digester stack (the default object stack, a named stack, or the parameter stack)
then it should only ever push objects in the rule's begin method and always pop exactly the same number of objects
off the stack during the rule's end method. Of course peeking at the objects on the stacks can be done from anywhere.


Rule objects should be stateless, ie they should not update any instance member during the parsing process. A rule
instance that changes state will encounter problems if invoked in a "nested" manner; this can happen if the same
instance is added to digester multiple times or if a wildcard pattern is used which can match both an element and a
child of the same element. The digester object stack and named stacks should be used to store any state that a rule
requires, making the rule class safe under all possible uses.

/**
 * Concrete implementations of this class implement actions to be taken when a corresponding nested pattern of XML
 * elements has been matched.
 * <p>
 * Writing a custom Rule is considered perfectly normal when using Digester, and is encouraged whenever the default set
 * of Rule classes don't meet your requirements; the digester framework can help process xml even when the built-in
 * rules aren't quite what is needed. Creating a custom Rule is just as easy as subclassing
 * javax.servlet.http.HttpServlet for webapps, or javax.swing.Action for GUI applications.
 * <p>
 * If a rule wishes to manipulate a digester stack (the default object stack, a named stack, or the parameter stack)
 * then it should only ever push objects in the rule's begin method and always pop exactly the same number of objects
 * off the stack during the rule's end method. Of course peeking at the objects on the stacks can be done from anywhere.
 * <p>
 * Rule objects should be stateless, ie they should not update any instance member during the parsing process. A rule
 * instance that changes state will encounter problems if invoked in a "nested" manner; this can happen if the same
 * instance is added to digester multiple times or if a wildcard pattern is used which can match both an element and a
 * child of the same element. The digester object stack and named stacks should be used to store any state that a rule
 * requires, making the rule class safe under all possible uses.
 */
public abstract class Rule
{

    // ----------------------------------------------------- Instance Variables

    
The Digester with which this Rule is associated.

/**
     * The Digester with which this Rule is associated.
     */
    private Digester digester = null;

    
The namespace URI for which this Rule is relevant, if any.

/**
     * The namespace URI for which this Rule is relevant, if any.
     */
    private String namespaceURI = null;

    // ------------------------------------------------------------- Properties

    
Return the Digester with which this Rule is associated.

Returns:the Digester with which this Rule is associated
/**
     * Return the Digester with which this Rule is associated.
     *
     * @return the Digester with which this Rule is associated
     */
    public Digester getDigester()
    {
        return ( this.digester );
    }

    
Set the Digester with which this Rule is associated.

Params:
  • digester – the Digester with which this Rule is associated
/**
     * Set the <code>Digester</code> with which this <code>Rule</code> is associated.
     *
     * @param digester the <code>Digester</code> with which this <code>Rule</code> is associated
     */
    public void setDigester( Digester digester )
    {
        this.digester = digester;
    }

    
Return the namespace URI for which this Rule is relevant, if any.

Returns:the namespace URI for which this Rule is relevant, if any
/**
     * Return the namespace URI for which this Rule is relevant, if any.
     *
     * @return the namespace URI for which this Rule is relevant, if any
     */
    public String getNamespaceURI()
    {
        return ( this.namespaceURI );
    }

    
Set the namespace URI for which this Rule is relevant, if any.

Params:
  • namespaceURI – Namespace URI for which this Rule is relevant, or null to match independent of
           namespace.
/**
     * Set the namespace URI for which this Rule is relevant, if any.
     * 
     * @param namespaceURI Namespace URI for which this Rule is relevant, or <code>null</code> to match independent of
     *            namespace.
     */
    public void setNamespaceURI( String namespaceURI )
    {
        this.namespaceURI = namespaceURI;
    }

    // --------------------------------------------------------- Public Methods

    
This method is called when the beginning of a matching XML element is encountered.

Params:
  • namespace – the namespace URI of the matching element, or an empty string if the parser is not namespace
           aware or the element has no namespace
  • name – the local name if the parser is namespace aware, or just the element name otherwise
  • attributes – The attribute list of this element
Throws:
Since:Digester 1.4
/**
     * This method is called when the beginning of a matching XML element is encountered.
     * 
     * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
     *            aware or the element has no namespace
     * @param name the local name if the parser is namespace aware, or just the element name otherwise
     * @param attributes The attribute list of this element
     * @throws Exception if any error occurs
     * @since Digester 1.4
     */
    public void begin( String namespace, String name, Attributes attributes )
        throws Exception
    {
        // The default implementation does nothing
    }

    
This method is called when the body of a matching XML element is encountered. If the element has no body, this
method is called with an empty string as the body text.

Params:
  • namespace – the namespace URI of the matching element, or an empty string if the parser is not namespace
           aware or the element has no namespace
  • name – the local name if the parser is namespace aware, or just the element name otherwise
  • text – The text of the body of this element
Throws:
Since:Digester 1.4
/**
     * This method is called when the body of a matching XML element is encountered. If the element has no body, this
     * method is called with an empty string as the body text.
     * 
     * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
     *            aware or the element has no namespace
     * @param name the local name if the parser is namespace aware, or just the element name otherwise
     * @param text The text of the body of this element
     * @throws Exception if any error occurs
     * @since Digester 1.4
     */
    public void body( String namespace, String name, String text )
        throws Exception
    {
        // The default implementation does nothing
    }

    
This method is called when the end of a matching XML element is encountered.

Params:
  • namespace – the namespace URI of the matching element, or an empty string if the parser is not namespace
           aware or the element has no namespace
  • name – the local name if the parser is namespace aware, or just the element name otherwise
Throws:
Since:Digester 1.4
/**
     * This method is called when the end of a matching XML element is encountered.
     * 
     * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
     *            aware or the element has no namespace
     * @param name the local name if the parser is namespace aware, or just the element name otherwise
     * @throws Exception if any error occurs
     * @since Digester 1.4
     */
    public void end( String namespace, String name )
        throws Exception
    {
        // The default implementation does nothing
    }

    
This method is called after all parsing methods have been called, to allow Rules to remove temporary data.

Throws:
  • Exception – if any error occurs
/**
     * This method is called after all parsing methods have been called, to allow Rules to remove temporary data.
     *
     * @throws Exception if any error occurs
     */
    public void finish()
        throws Exception
    {
        // The default implementation does nothing
    }

}