001 package 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
022 import 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 */
043 public 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 }