PluginContext


1   /* $Id: PluginContext.java 179714 2005-06-03 03:53:39Z skitching $
2    *
3    * Copyright 2004 The Apache Software Foundation.
4    * 
5    * Licensed under the Apache License, Version 2.0 (the "License");
6    * you may not use this file except in compliance with the License.
7    * 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.digester.plugins;
18  
19  import java.util.List  ;
20  import java.util.LinkedList  ;
21  
22  import org.apache.commons.digester.plugins.strategies.FinderFromFile;
23  import org.apache.commons.digester.plugins.strategies.FinderFromResource;
24  import org.apache.commons.digester.plugins.strategies.FinderFromClass;
25  import org.apache.commons.digester.plugins.strategies.FinderFromMethod;
26  import org.apache.commons.digester.plugins.strategies.FinderFromDfltMethod;
27  import org.apache.commons.digester.plugins.strategies.FinderFromDfltClass;
28  import org.apache.commons.digester.plugins.strategies.FinderFromDfltResource;
29  import org.apache.commons.digester.plugins.strategies.FinderSetProperties;
30  
31  /**
32   * Provides data and services which should exist only once per digester.
33   * <p>
34   * This class holds a number of useful items which should be shared by all
35   * plugin objects. Such data cannot be stored on the PluginRules or 
36   * PluginManager classes, as there can be multiple instances of these at 
37   * various times during a parse. 
38   * <p>
39   * The name "Context" refers to the similarity between this class and a
40   * ServletContext class in a servlet engine. A ServletContext object provides
41   * access to the container's services such as obtaining global configuration
42   * parameters for the container, or getting access to logging services. For
43   * plugins, a Digester instance can be regarded as "the container".
44   *
45   * @since 1.6
46   */
47  
48  public class PluginContext {
49  
50      // the xml attribute the user uses on an xml element to specify
51      // the plugin's class
52      public final String   DFLT_PLUGIN_CLASS_ATTR_NS = null;
53      public final String   DFLT_PLUGIN_CLASS_ATTR = "plugin-class";
54  
55      // the xml attribute the user uses on an xml element to specify
56      // the plugin's class
57      public final String   DFLT_PLUGIN_ID_ATTR_NS = null;
58      public final String   DFLT_PLUGIN_ID_ATTR = "plugin-id";
59      
60      /** See {@link #setPluginClassAttribute}. */
61      private String   pluginClassAttrNs = DFLT_PLUGIN_CLASS_ATTR_NS;
62  
63      /** See {@link #setPluginClassAttribute}. */
64      private String   pluginClassAttr = DFLT_PLUGIN_CLASS_ATTR;
65  
66      /** See {@link #setPluginClassAttribute}. */
67      private String   pluginIdAttrNs = DFLT_PLUGIN_ID_ATTR_NS;
68  
69      /** See {@link #setPluginClassAttribute}. */
70      private String   pluginIdAttr = DFLT_PLUGIN_ID_ATTR;
71      
72      /** 
73       * A list of RuleFinder objects used by all Declarations (and thus
74       * indirectly by all PluginCreateRules to locate the custom rules
75       * for plugin classes.
76       */
77      private List   ruleFinders;
78  
79      //------------------- constructors ---------------------------------------
80      
81      public PluginContext() {
82      }
83      
84      //------------------- methods ---------------------------------------
85  
86      /**
87       * Return the list of RuleFinder objects. Under normal circumstances
88       * this method creates a default list of these objects when first called
89       * (ie "on-demand" or "lazy initialization"). However if setRuleFinders
90       * has been called first, then the list specified there is returned.
91       * <p>
92       * It is explicitly permitted for the caller to modify this list
93       * by inserting or removing RuleFinder objects.
94       */
95      public List   getRuleFinders() {
96          if (ruleFinders == null) {
97              // when processing a plugin declaration, attempts are made to
98              // find custom rules in the order in which the Finder objects
99              // are added below. However this list can be modified
100             ruleFinders = new LinkedList  ();
101             ruleFinders.add(new FinderFromFile());
102             ruleFinders.add(new FinderFromResource());
103             ruleFinders.add(new FinderFromClass());
104             ruleFinders.add(new FinderFromMethod());
105             ruleFinders.add(new FinderFromDfltMethod());
106             ruleFinders.add(new FinderFromDfltClass());
107             ruleFinders.add(new FinderFromDfltResource());
108             ruleFinders.add(new FinderFromDfltResource(".xml"));
109             ruleFinders.add(new FinderSetProperties());
110         }
111         return ruleFinders;
112     }
113     
114     /**
115      * Set the list of RuleFinder objects. This may be useful if working
116      * in a non-english language, allowing the application developer to
117      * replace the standard list with a list of objects which look for xml 
118      * attributes in the local language.
119      * <p>
120      * If the intent is just to add an additional rule-finding algorithm, then
121      * it may be better to call #getRuleFinders, and insert a new object into 
122      * the start of the list.
123      */
124     public void setRuleFinders(List   ruleFinders) {
125         this.ruleFinders = ruleFinders;
126     }
127 
128     /**
129      * Sets the xml attribute which the input xml uses to indicate to a 
130      * PluginCreateRule which class should be instantiated.
131      * <p>
132      * Example:
133      * <pre>
134      * setPluginClassAttribute(null, "class");
135      * </pre>
136      * will allow this in the input xml:
137      * <pre>
138      *  &lt;root&gt;
139      *    &lt;some-plugin class="com.acme.widget"&gt; ......
140      * </pre>
141      * instead of the default syntax:
142      * <pre>
143      *  &lt;root&gt;
144      *    &lt;some-plugin plugin-class="com.acme.widget"&gt; ......
145      * </pre>
146      * This is particularly useful if the input xml document is not in
147      * English.
148      * <p>
149      * Note that the xml attributes used by PluginDeclarationRules are not
150      * affected by this method.
151      *
152      * @param namespaceUri is the namespace uri that the specified attribute
153      * is in. If the attribute is in no namespace, then this should be null.
154      * Note that if a namespace is used, the attrName value should <i>not</i>
155      * contain any kind of namespace-prefix. Note also that if you are using
156      * a non-namespace-aware parser, this parameter <i>must</i> be null.
157      *
158      * @param attrName is the attribute whose value contains the name of the
159      * class to be instantiated.
160      */
161     public void setPluginClassAttribute(String   namespaceUri, 
162                                         String   attrName) {
163         pluginClassAttrNs = namespaceUri;
164         pluginClassAttr = attrName;
165     }
166 
167     /**
168      * Sets the xml attribute which the input xml uses to indicate to a 
169      * PluginCreateRule which plugin declaration is being referenced.
170      * <p>
171      * Example:
172      * <pre>
173      * setPluginIdAttribute(null, "id");
174      * </pre>
175      * will allow this in the input xml:
176      * <pre>
177      *  &lt;root&gt;
178      *    &lt;some-plugin id="widget"&gt; ......
179      * </pre>
180      * rather than the default behaviour:
181      * <pre>
182      *  &lt;root&gt;
183      *    &lt;some-plugin plugin-id="widget"&gt; ......
184      * </pre>
185      * This is particularly useful if the input xml document is not in
186      * English.
187      * <p>
188      * Note that the xml attributes used by PluginDeclarationRules are not
189      * affected by this method.
190      *
191      * @param namespaceUri is the namespace uri that the specified attribute
192      * is in. If the attribute is in no namespace, then this should be null.
193      * Note that if a namespace is used, the attrName value should <i>not</i>
194      * contain any kind of namespace-prefix. Note also that if you are using
195      * a non-namespace-aware parser, this parameter <i>must</i> be null.
196      *
197      * @param attrName is the attribute whose value contains the id of the
198      * plugin declaration to be used when instantiating an object.
199      */
200     public void setPluginIdAttribute(String   namespaceUri, 
201                                      String   attrName) {
202         pluginIdAttrNs = namespaceUri;
203         pluginIdAttr = attrName;
204     }
205 
206     /**
207      * Get the namespace for the xml attribute which indicates to a 
208      * PluginCreateRule which class is to be plugged in.
209      * <p>
210      * May be null (in fact, normally will be).
211      */
212     public String   getPluginClassAttrNs() {
213         return pluginClassAttrNs;
214     }
215     
216     /**
217      * Get the namespace for the xml attribute which indicates to a 
218      * PluginCreateRule which class is to be plugged in.
219      * <p>
220      * The return value is never null.
221      */
222     public String   getPluginClassAttr() {
223         return pluginClassAttr;
224     }
225     
226     /**
227      * Get the namespace for the xml attribute which indicates to a 
228      * PluginCreateRule which previous plugin declaration should be used.
229      * <p>
230      * May be null (in fact, normally will be).
231      */
232     public String   getPluginIdAttrNs() {
233         return pluginIdAttrNs;
234     }
235     
236     /**
237      * Get the namespace for the xml attribute which indicates to a 
238      * PluginCreateRule which previous plugin declaration should be used.
239      * <p>
240      * The return value is never null.
241      */
242     public String   getPluginIdAttr() {
243         return pluginIdAttr;
244     }
245 }
246
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags