001package org.apache.commons.digester3;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import org.xml.sax.Attributes;
023
024/**
025 * Concrete implementations of this class implement actions to be taken when a corresponding nested pattern of XML
026 * elements has been matched.
027 * <p>
028 * Writing a custom Rule is considered perfectly normal when using Digester, and is encouraged whenever the default set
029 * of Rule classes don't meet your requirements; the digester framework can help process xml even when the built-in
030 * rules aren't quite what is needed. Creating a custom Rule is just as easy as subclassing
031 * javax.servlet.http.HttpServlet for webapps, or javax.swing.Action for GUI applications.
032 * <p>
033 * If a rule wishes to manipulate a digester stack (the default object stack, a named stack, or the parameter stack)
034 * then it should only ever push objects in the rule's begin method and always pop exactly the same number of objects
035 * off the stack during the rule's end method. Of course peeking at the objects on the stacks can be done from anywhere.
036 * <p>
037 * Rule objects should be stateless, ie they should not update any instance member during the parsing process. A rule
038 * instance that changes state will encounter problems if invoked in a "nested" manner; this can happen if the same
039 * instance is added to digester multiple times or if a wildcard pattern is used which can match both an element and a
040 * child of the same element. The digester object stack and named stacks should be used to store any state that a rule
041 * requires, making the rule class safe under all possible uses.
042 */
043public abstract class Rule
044{
045
046    // ----------------------------------------------------- Instance Variables
047
048    /**
049     * The Digester with which this Rule is associated.
050     */
051    private Digester digester = null;
052
053    /**
054     * The namespace URI for which this Rule is relevant, if any.
055     */
056    private String namespaceURI = null;
057
058    // ------------------------------------------------------------- Properties
059
060    /**
061     * Return the Digester with which this Rule is associated.
062     *
063     * @return the Digester with which this Rule is associated
064     */
065    public Digester getDigester()
066    {
067        return ( this.digester );
068    }
069
070    /**
071     * Set the <code>Digester</code> with which this <code>Rule</code> is associated.
072     *
073     * @param digester the <code>Digester</code> with which this <code>Rule</code> is associated
074     */
075    public void setDigester( Digester digester )
076    {
077        this.digester = digester;
078    }
079
080    /**
081     * Return the namespace URI for which this Rule is relevant, if any.
082     *
083     * @return the namespace URI for which this Rule is relevant, if any
084     */
085    public String getNamespaceURI()
086    {
087        return ( this.namespaceURI );
088    }
089
090    /**
091     * Set the namespace URI for which this Rule is relevant, if any.
092     * 
093     * @param namespaceURI Namespace URI for which this Rule is relevant, or <code>null</code> to match independent of
094     *            namespace.
095     */
096    public void setNamespaceURI( String namespaceURI )
097    {
098        this.namespaceURI = namespaceURI;
099    }
100
101    // --------------------------------------------------------- Public Methods
102
103    /**
104     * This method is called when the beginning of a matching XML element is encountered.
105     * 
106     * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
107     *            aware or the element has no namespace
108     * @param name the local name if the parser is namespace aware, or just the element name otherwise
109     * @param attributes The attribute list of this element
110     * @throws Exception if any error occurs
111     * @since Digester 1.4
112     */
113    public void begin( String namespace, String name, Attributes attributes )
114        throws Exception
115    {
116        // The default implementation does nothing
117    }
118
119    /**
120     * This method is called when the body of a matching XML element is encountered. If the element has no body, this
121     * method is called with an empty string as the body text.
122     * 
123     * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
124     *            aware or the element has no namespace
125     * @param name the local name if the parser is namespace aware, or just the element name otherwise
126     * @param text The text of the body of this element
127     * @throws Exception if any error occurs
128     * @since Digester 1.4
129     */
130    public void body( String namespace, String name, String text )
131        throws Exception
132    {
133        // The default implementation does nothing
134    }
135
136    /**
137     * This method is called when the end of a matching XML element is encountered.
138     * 
139     * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
140     *            aware or the element has no namespace
141     * @param name the local name if the parser is namespace aware, or just the element name otherwise
142     * @throws Exception if any error occurs
143     * @since Digester 1.4
144     */
145    public void end( String namespace, String name )
146        throws Exception
147    {
148        // The default implementation does nothing
149    }
150
151    /**
152     * This method is called after all parsing methods have been called, to allow Rules to remove temporary data.
153     *
154     * @throws Exception if any error occurs
155     */
156    public void finish()
157        throws Exception
158    {
159        // The default implementation does nothing
160    }
161
162}