1 package org.apache.commons.digester3; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import org.xml.sax.Attributes; 23 24 /** 25 * Concrete implementations of this class implement actions to be taken when a 26 * corresponding nested pattern of XML elements has been matched. 27 * <p> 28 * Writing a custom Rule is considered perfectly normal when using Digester, and 29 * is encouraged whenever the default set of Rule classes don't meet your 30 * requirements; the digester framework can help process xml even when the 31 * built-in rules aren't quite what is needed. Creating a custom Rule is just as 32 * easy as subclassing javax.servlet.http.HttpServlet for webapps, or 33 * javax.swing.Action for GUI applications. 34 * <p> 35 * If a rule wishes to manipulate a digester stack (the default object stack, a 36 * named stack, or the parameter stack) then it should only ever push objects in 37 * the rule's begin method and always pop exactly the same number of objects off 38 * the stack during the rule's end method. Of course peeking at the objects on 39 * the stacks can be done from anywhere. 40 * <p> 41 * Rule objects should limit their state data to the digester object stack and 42 * named stacks. Storing state in instance fields (other than digester) during 43 * the parsing process will cause problems if invoked in a "nested" manner; this 44 * can happen if the same instance is added to digester multiple times or if a 45 * wildcard pattern is used which can match both an element and a child of the 46 * same element. 47 * <p> 48 * Rule objects are not thread-safe when each thread creates a new digester, as 49 * is commonly the case. In a multithreaded context you should create new Rule 50 * instances for every digester or synchronize read/write access to the digester 51 * within the Rule. 52 */public abstract class Rule 53 { 54 55 // ----------------------------------------------------- Instance Variables 56 57 /** 58 * The Digester with which this Rule is associated. 59 */ 60 private Digester digester = null; 61 62 /** 63 * The namespace URI for which this Rule is relevant, if any. 64 */ 65 private String namespaceURI = null; 66 67 // ------------------------------------------------------------- Properties 68 69 /** 70 * Return the Digester with which this Rule is associated. 71 * 72 * @return the Digester with which this Rule is associated 73 */ 74 public Digester getDigester() 75 { 76 return ( this.digester ); 77 } 78 79 /** 80 * Set the <code>Digester</code> with which this <code>Rule</code> is associated. 81 * 82 * @param digester the <code>Digester</code> with which this <code>Rule</code> is associated 83 */ 84 public void setDigester( Digester digester ) 85 { 86 this.digester = digester; 87 } 88 89 /** 90 * Return the namespace URI for which this Rule is relevant, if any. 91 * 92 * @return the namespace URI for which this Rule is relevant, if any 93 */ 94 public String getNamespaceURI() 95 { 96 return ( this.namespaceURI ); 97 } 98 99 /** 100 * Set the namespace URI for which this Rule is relevant, if any. 101 * 102 * @param namespaceURI Namespace URI for which this Rule is relevant, or <code>null</code> to match independent of 103 * namespace. 104 */ 105 public void setNamespaceURI( String namespaceURI ) 106 { 107 this.namespaceURI = namespaceURI; 108 } 109 110 // --------------------------------------------------------- Public Methods 111 112 /** 113 * This method is called when the beginning of a matching XML element is encountered. 114 * 115 * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace 116 * aware or the element has no namespace 117 * @param name the local name if the parser is namespace aware, or just the element name otherwise 118 * @param attributes The attribute list of this element 119 * @throws Exception if any error occurs 120 * @since Digester 1.4 121 */ 122 public void begin( String namespace, String name, Attributes attributes ) 123 throws Exception 124 { 125 // The default implementation does nothing 126 } 127 128 /** 129 * This method is called when the body of a matching XML element is encountered. If the element has no body, this 130 * method is called with an empty string as the body text. 131 * 132 * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace 133 * aware or the element has no namespace 134 * @param name the local name if the parser is namespace aware, or just the element name otherwise 135 * @param text The text of the body of this element 136 * @throws Exception if any error occurs 137 * @since Digester 1.4 138 */ 139 public void body( String namespace, String name, String text ) 140 throws Exception 141 { 142 // The default implementation does nothing 143 } 144 145 /** 146 * This method is called when the end of a matching XML element is encountered. 147 * 148 * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace 149 * aware or the element has no namespace 150 * @param name the local name if the parser is namespace aware, or just the element name otherwise 151 * @throws Exception if any error occurs 152 * @since Digester 1.4 153 */ 154 public void end( String namespace, String name ) 155 throws Exception 156 { 157 // The default implementation does nothing 158 } 159 160 /** 161 * This method is called after all parsing methods have been called, to allow Rules to remove temporary data. 162 * 163 * @throws Exception if any error occurs 164 */ 165 public void finish() 166 throws Exception 167 { 168 // The default implementation does nothing 169 } 170 171 }