001 /* $Id: Rule.java 471661 2006-11-06 08:09:25Z skitching $ 002 * 003 * Licensed to the Apache Software Foundation (ASF) under one or more 004 * contributor license agreements. See the NOTICE file distributed with 005 * this work for additional information regarding copyright ownership. 006 * The ASF licenses this file to You under the Apache License, Version 2.0 007 * (the "License"); you may not use this file except in compliance with 008 * the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018 019 020 package org.apache.commons.digester; 021 022 023 import org.xml.sax.Attributes; 024 025 026 /** 027 * Concrete implementations of this class implement actions to be taken when 028 * a corresponding nested pattern of XML elements has been matched. 029 * <p> 030 * Writing a custom Rule is considered perfectly normal when using Digester, 031 * and is encouraged whenever the default set of Rule classes don't meet your 032 * requirements; the digester framework can help process xml even when the 033 * built-in rules aren't quite what is needed. Creating a custom Rule is 034 * just as easy as subclassing javax.servlet.http.HttpServlet for webapps, 035 * or javax.swing.Action for GUI applications. 036 * <p> 037 * If a rule wishes to manipulate a digester stack (the default object stack, 038 * a named stack, or the parameter stack) then it should only ever push 039 * objects in the rule's begin method and always pop exactly the same 040 * number of objects off the stack during the rule's end method. Of course 041 * peeking at the objects on the stacks can be done from anywhere. 042 * <p> 043 * Rule objects should be stateless, ie they should not update any instance 044 * member during the parsing process. A rule instance that changes state 045 * will encounter problems if invoked in a "nested" manner; this can happen 046 * if the same instance is added to digester multiple times or if a 047 * wildcard pattern is used which can match both an element and a child of the 048 * same element. The digester object stack and named stacks should be used to 049 * store any state that a rule requires, making the rule class safe under all 050 * possible uses. 051 */ 052 053 public abstract class Rule { 054 055 056 // ----------------------------------------------------------- Constructors 057 058 059 /** 060 * Constructor sets the associated Digester. 061 * 062 * @param digester The digester with which this rule is associated 063 * @deprecated The digester instance is now set in the {@link Digester#addRule} method. Use {@link #Rule()} instead. 064 */ 065 public Rule(Digester digester) { 066 067 super(); 068 setDigester(digester); 069 070 } 071 072 /** 073 * <p>Base constructor. 074 * Now the digester will be set when the rule is added.</p> 075 */ 076 public Rule() {} 077 078 079 // ----------------------------------------------------- Instance Variables 080 081 082 /** 083 * The Digester with which this Rule is associated. 084 */ 085 protected Digester digester = null; 086 087 088 /** 089 * The namespace URI for which this Rule is relevant, if any. 090 */ 091 protected String namespaceURI = null; 092 093 094 // ------------------------------------------------------------- Properties 095 096 097 /** 098 * Return the Digester with which this Rule is associated. 099 */ 100 public Digester getDigester() { 101 102 return (this.digester); 103 104 } 105 106 /** 107 * Set the <code>Digester</code> with which this <code>Rule</code> is associated. 108 */ 109 public void setDigester(Digester digester) { 110 111 this.digester = digester; 112 113 } 114 115 /** 116 * Return the namespace URI for which this Rule is relevant, if any. 117 */ 118 public String getNamespaceURI() { 119 120 return (this.namespaceURI); 121 122 } 123 124 125 /** 126 * Set the namespace URI for which this Rule is relevant, if any. 127 * 128 * @param namespaceURI Namespace URI for which this Rule is relevant, 129 * or <code>null</code> to match independent of namespace. 130 */ 131 public void setNamespaceURI(String namespaceURI) { 132 133 this.namespaceURI = namespaceURI; 134 135 } 136 137 138 // --------------------------------------------------------- Public Methods 139 140 141 /** 142 * This method is called when the beginning of a matching XML element 143 * is encountered. 144 * 145 * @param attributes The attribute list of this element 146 * @deprecated Use the {@link #begin(String,String,Attributes) begin} 147 * method with <code>namespace</code> and <code>name</code> 148 * parameters instead. 149 */ 150 public void begin(Attributes attributes) throws Exception { 151 152 ; // The default implementation does nothing 153 154 } 155 156 157 /** 158 * This method is called when the beginning of a matching XML element 159 * is encountered. The default implementation delegates to the deprecated 160 * method {@link #begin(Attributes) begin} without the 161 * <code>namespace</code> and <code>name</code> parameters, to retain 162 * backwards compatibility. 163 * 164 * @param namespace the namespace URI of the matching element, or an 165 * empty string if the parser is not namespace aware or the element has 166 * no namespace 167 * @param name the local name if the parser is namespace aware, or just 168 * the element name otherwise 169 * @param attributes The attribute list of this element 170 * @since Digester 1.4 171 */ 172 public void begin(String namespace, String name, Attributes attributes) 173 throws Exception { 174 175 begin(attributes); 176 177 } 178 179 180 /** 181 * This method is called when the body of a matching XML element 182 * is encountered. If the element has no body, this method is 183 * called with an empty string as the body text. 184 * 185 * @param text The text of the body of this element 186 * @deprecated Use the {@link #body(String,String,String) body} method 187 * with <code>namespace</code> and <code>name</code> parameters 188 * instead. 189 */ 190 public void body(String text) throws Exception { 191 192 ; // The default implementation does nothing 193 194 } 195 196 197 /** 198 * This method is called when the body of a matching XML element is 199 * encountered. If the element has no body, this method is 200 * called with an empty string as the body text. 201 * <p> 202 * The default implementation delegates to the deprecated method 203 * {@link #body(String) body} without the <code>namespace</code> and 204 * <code>name</code> parameters, to retain backwards compatibility. 205 * 206 * @param namespace the namespace URI of the matching element, or an 207 * empty string if the parser is not namespace aware or the element has 208 * no namespace 209 * @param name the local name if the parser is namespace aware, or just 210 * the element name otherwise 211 * @param text The text of the body of this element 212 * @since Digester 1.4 213 */ 214 public void body(String namespace, String name, String text) 215 throws Exception { 216 217 body(text); 218 219 } 220 221 222 /** 223 * This method is called when the end of a matching XML element 224 * is encountered. 225 * 226 * @deprecated Use the {@link #end(String,String) end} method with 227 * <code>namespace</code> and <code>name</code> parameters instead. 228 */ 229 public void end() throws Exception { 230 231 ; // The default implementation does nothing 232 233 } 234 235 236 /** 237 * This method is called when the end of a matching XML element 238 * is encountered. The default implementation delegates to the deprecated 239 * method {@link #end end} without the 240 * <code>namespace</code> and <code>name</code> parameters, to retain 241 * backwards compatibility. 242 * 243 * @param namespace the namespace URI of the matching element, or an 244 * empty string if the parser is not namespace aware or the element has 245 * no namespace 246 * @param name the local name if the parser is namespace aware, or just 247 * the element name otherwise 248 * @since Digester 1.4 249 */ 250 public void end(String namespace, String name) 251 throws Exception { 252 253 end(); 254 255 } 256 257 258 /** 259 * This method is called after all parsing methods have been 260 * called, to allow Rules to remove temporary data. 261 */ 262 public void finish() throws Exception { 263 264 ; // The default implementation does nothing 265 266 } 267 268 269 }