View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.chain.config;
18  
19  import org.apache.commons.digester.Digester;
20  import org.apache.commons.digester.RuleSetBase;
21  
22  /**
23   * Digester {@code RuleSet} for configuring <em>Chain of
24   * Responsibility</em> command chains, and adding them to an appropriate
25   * {@link org.apache.commons.chain.Catalog}. The following properties
26   * may be configured prior to executing the {@code addRuleInstance()}
27   * method in order to influence the rules that get added, with default
28   * values in square brackets:
29   * <ul>
30   * <li><strong>catalogClass</strong> -- Fully qualified name of the
31   *     implementation class used to create new
32   *     {@link org.apache.commons.chain.Catalog} instances.
33   *     If not specified, the default value is
34   *     {@code org.apache.commons.chain.impl.CatalogBase}.</li>
35   * <li><strong>catalogElement</strong> -- Name of the XML element representing
36   *     the addition of a {@link org.apache.commons.chain.Catalog}.
37   *     Any such catalog that is created will be registered with the
38   *     {@link org.apache.commons.chain.CatalogFactory} instance for our
39   *     application, under the name specified by the {@code nameAttribute}
40   *     attribute (if present), or as the default {@link org.apache.commons.chain.Catalog}.
41   *     If not specified, the default value is {@code catalog}.</li>
42   * <li><strong>chainClass</strong> -- Fully qualified name of the implementation
43   *     class used to create new {@link org.apache.commons.chain.Chain} instances.
44   *     If not specified, the default value is
45   *     {@code org.apache.commons.chain.impl.ChainBase}.
46   *     </li>
47   * <li><strong>chainElement</strong> -- Name of the XML element representing
48   *     the addition of a {@link org.apache.commons.chain.Chain}. A chain
49   *     element has the same functionality as a command element, except that
50   *     it defaults the implementation class to
51   *     {@code org.apache.commons.chain.impl.ChainBase}. [chain]</li>
52   * <li><strong>classAttribute</strong> -- Attribute on a chain (optional) or
53   *     command (required) element that specifies the fully qualified class
54   *     name of the implementation class that should be instantiated.
55   *     [className]</li>
56   * <li><strong>commandElement</strong> -- Name of the XML element
57   *     representing the addition of a {@link org.apache.commons.chain.Command}.
58   *     An implementation class name must be provided on the attribute named by the
59   *     {@code classAttribute} property. [command]</li>
60   * <li><strong>defineElement</strong> -- Name of the XML element
61   *     that associates the element specified by the {@code nameAttribute}
62   *     attributes with a {@link org.apache.commons.chain.Command} or
63   *     {@link org.apache.commons.chain.Chain} implementation class
64   *     named by the {@code classAttribute} attribute. [define]</li>
65   * <li><strong>nameAttribute</strong> -- Attribute on an outermost chain or
66   *     command element that will be used to register this command with the
67   *     associated {@link org.apache.commons.chain.Catalog} instance on the stack.
68   *     [name]</li>
69   * <li><strong>namespaceURI</strong> -- The XML namespace URI with which these
70   *     rules will be associated, or {@code null} for no namespace.
71   *     [null]</li>
72   * </ul>
73   *
74   * @author Craig R. McClanahan
75   * @version $Revision$ $Date$
76   */
77  public class ConfigRuleSet extends RuleSetBase {
78  
79      // ----------------------------------------------------- Instance Variables
80  
81      private String catalogClass = "org.apache.commons.chain.impl.CatalogBase";
82      private String catalogElement = "catalog";
83      private String chainClass = "org.apache.commons.chain.impl.ChainBase";
84      private String chainElement = "chain";
85      private String classAttribute = "className";
86      private String commandElement = "command";
87      private String defineElement = "define";
88      private String nameAttribute = "name";
89  
90      // ----------------------------------------------------------- Constructors
91  
92      /**
93       * The Default-Constructor for this class.
94       */
95      public ConfigRuleSet() {
96      }
97  
98      // ------------------------------------------------------------- Properties
99  
100     /**
101      * Return the fully qualified {@link org.apache.commons.chain.Catalog}
102      * implementation class.
103      *
104      * @return The Catalog's class name.
105      */
106     public String getCatalogClass() {
107         return this.catalogClass;
108     }
109 
110     /**
111      * Set the fully qualified {@link org.apache.commons.chain.Catalog}
112      * implementation class.
113      *
114      * @param catalogClass The new {@link org.apache.commons.chain.Catalog}
115      *        implementation class
116      */
117     public void setCatalogClass(String catalogClass) {
118         this.catalogClass = catalogClass;
119     }
120 
121     /**
122      * Return the element name of a catalog element.
123      *
124      * @return The element name of a catalog element.
125      */
126     public String getCatalogElement() {
127         return this.catalogElement;
128     }
129 
130     /**
131      * Set the element name of a catalog element.
132      *
133      * @param catalogElement The new element name
134      */
135     public void setCatalogElement(String catalogElement) {
136         this.catalogElement = catalogElement;
137     }
138 
139     /**
140      * Return the fully qualified {@link org.apache.commons.chain.Chain}
141      * implementation class.
142      *
143      * @return The Chain's class name.
144      */
145     public String getChainClass() {
146         return this.chainClass;
147     }
148 
149     /**
150      * Set the fully qualified {@link org.apache.commons.chain.Chain}
151      * implementation class.
152      *
153      * @param chainClass The new {@link org.apache.commons.chain.Chain}
154      *        implementation class
155      */
156     public void setChainClass(String chainClass) {
157         this.chainClass = chainClass;
158     }
159 
160     /**
161      * Return the element name of a chain element.
162      *
163      * @return The element name of a catalog element.
164      */
165     public String getChainElement() {
166         return this.chainElement;
167     }
168 
169     /**
170      * Set the element name of a chain element.
171      *
172      * @param chainElement The new element name
173      */
174     public void setChainElement(String chainElement) {
175         this.chainElement = chainElement;
176     }
177 
178     /**
179      * Return the attribute name of a class attribute.
180      *
181      * @return The attribute name of a class attribute.
182      */
183     public String getClassAttribute() {
184         return this.classAttribute;
185     }
186 
187     /**
188      * Set the attribute name of a class attribute.
189      *
190      * @param classAttribute The new attribute name
191      */
192     public void setClassAttribute(String classAttribute) {
193         this.classAttribute = classAttribute;
194     }
195 
196     /**
197      * Return the element name of a command element.
198      *
199      * @return The element name of a command element.
200      */
201     public String getCommandElement() {
202         return this.commandElement;
203     }
204 
205     /**
206      * Set the element name of a command element.
207      *
208      * @param commandElement The new element name
209      */
210     public void setCommandElement(String commandElement) {
211         this.commandElement = commandElement;
212     }
213 
214     /**
215      * Return the element name of a define element.
216      *
217      * @return The element name of a define element.
218      */
219     public String getDefineElement() {
220         return this.defineElement;
221     }
222 
223     /**
224      * Set the element name of a define element.
225      *
226      * @param defineElement The new element name
227      */
228     public void setDefineElement(String defineElement) {
229         this.defineElement = defineElement;
230     }
231 
232     /**
233      * Return the attribute name of a name attribute.
234      *
235      * @return The attribute name of an attribute element.
236      */
237     public String getNameAttribute() {
238         return this.nameAttribute;
239     }
240 
241     /**
242      * Set the attribute name of a name attribute.
243      *
244      * @param nameAttribute The new attribute name
245      */
246     public void setNameAttribute(String nameAttribute) {
247         this.nameAttribute = nameAttribute;
248     }
249 
250     // --------------------------------------------------------- Public Methods
251 
252     /**
253      * Add the set of Rule instances defined in this RuleSet to the
254      * specified {@code Digester} instance, associating them with
255      * our namespace URI (if any). This method should only be called
256      * by a Digester instance.
257      *
258      * @param digester Digester instance to which the new Rule instances
259      *        should be added.
260      */
261     @Override
262     public void addRuleInstances(Digester digester) {
263         // Add rules for a catalog element
264         digester.addRule("*/" + getCatalogElement(),
265                          new ConfigCatalogRule(nameAttribute, catalogClass));
266         digester.addSetProperties("*/" + getCatalogElement());
267 
268         // Add rules for a chain element
269         digester.addObjectCreate("*/" + getChainElement(),
270                                  getChainClass(),
271                                  getClassAttribute());
272         digester.addSetProperties("*/" + getChainElement());
273         digester.addRule("*/" + getChainElement(),
274                          new ConfigRegisterRule(nameAttribute));
275 
276         // Add rules for a command element
277         digester.addObjectCreate("*/" + getCommandElement(),
278                                  null,
279                                  getClassAttribute());
280         digester.addSetProperties("*/" + getCommandElement());
281         digester.addRule("*/" + getCommandElement(),
282                          new ConfigRegisterRule(nameAttribute));
283 
284         // Add rules for a define element
285         digester.addRule("*/" + getDefineElement(),
286                          new ConfigDefineRule(getNameAttribute(),
287                                               getClassAttribute()));
288     }
289 }