001 /* $Id: PluginContext.java 476312 2006-11-17 20:59:09Z rahul $
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 package org.apache.commons.digester.plugins;
019
020 import java.util.List;
021 import java.util.LinkedList;
022
023 import org.apache.commons.digester.plugins.strategies.FinderFromFile;
024 import org.apache.commons.digester.plugins.strategies.FinderFromResource;
025 import org.apache.commons.digester.plugins.strategies.FinderFromClass;
026 import org.apache.commons.digester.plugins.strategies.FinderFromMethod;
027 import org.apache.commons.digester.plugins.strategies.FinderFromDfltMethod;
028 import org.apache.commons.digester.plugins.strategies.FinderFromDfltClass;
029 import org.apache.commons.digester.plugins.strategies.FinderFromDfltResource;
030 import org.apache.commons.digester.plugins.strategies.FinderSetProperties;
031
032 /**
033 * Provides data and services which should exist only once per digester.
034 * <p>
035 * This class holds a number of useful items which should be shared by all
036 * plugin objects. Such data cannot be stored on the PluginRules or
037 * PluginManager classes, as there can be multiple instances of these at
038 * various times during a parse.
039 * <p>
040 * The name "Context" refers to the similarity between this class and a
041 * ServletContext class in a servlet engine. A ServletContext object provides
042 * access to the container's services such as obtaining global configuration
043 * parameters for the container, or getting access to logging services. For
044 * plugins, a Digester instance can be regarded as "the container".
045 *
046 * @since 1.6
047 */
048
049 public class PluginContext {
050
051 // TODO: Consider making following four constants static in 2.0
052 // the xml attribute the user uses on an xml element to specify
053 // the plugin's class
054 public final String DFLT_PLUGIN_CLASS_ATTR_NS = null;
055 public final String DFLT_PLUGIN_CLASS_ATTR = "plugin-class";
056
057 // the xml attribute the user uses on an xml element to specify
058 // the plugin's class
059 public final String DFLT_PLUGIN_ID_ATTR_NS = null;
060 public final String DFLT_PLUGIN_ID_ATTR = "plugin-id";
061
062 /** See {@link #setPluginClassAttribute}. */
063 private String pluginClassAttrNs = DFLT_PLUGIN_CLASS_ATTR_NS;
064
065 /** See {@link #setPluginClassAttribute}. */
066 private String pluginClassAttr = DFLT_PLUGIN_CLASS_ATTR;
067
068 /** See {@link #setPluginClassAttribute}. */
069 private String pluginIdAttrNs = DFLT_PLUGIN_ID_ATTR_NS;
070
071 /** See {@link #setPluginClassAttribute}. */
072 private String pluginIdAttr = DFLT_PLUGIN_ID_ATTR;
073
074 /**
075 * A list of RuleFinder objects used by all Declarations (and thus
076 * indirectly by all PluginCreateRules to locate the custom rules
077 * for plugin classes.
078 */
079 private List ruleFinders;
080
081 //------------------- constructors ---------------------------------------
082
083 public PluginContext() {
084 }
085
086 //------------------- methods ---------------------------------------
087
088 /**
089 * Return the list of RuleFinder objects. Under normal circumstances
090 * this method creates a default list of these objects when first called
091 * (ie "on-demand" or "lazy initialization"). However if setRuleFinders
092 * has been called first, then the list specified there is returned.
093 * <p>
094 * It is explicitly permitted for the caller to modify this list
095 * by inserting or removing RuleFinder objects.
096 */
097 public List getRuleFinders() {
098 if (ruleFinders == null) {
099 // when processing a plugin declaration, attempts are made to
100 // find custom rules in the order in which the Finder objects
101 // are added below. However this list can be modified
102 ruleFinders = new LinkedList();
103 ruleFinders.add(new FinderFromFile());
104 ruleFinders.add(new FinderFromResource());
105 ruleFinders.add(new FinderFromClass());
106 ruleFinders.add(new FinderFromMethod());
107 ruleFinders.add(new FinderFromDfltMethod());
108 ruleFinders.add(new FinderFromDfltClass());
109 ruleFinders.add(new FinderFromDfltResource());
110 ruleFinders.add(new FinderFromDfltResource(".xml"));
111 ruleFinders.add(new FinderSetProperties());
112 }
113 return ruleFinders;
114 }
115
116 /**
117 * Set the list of RuleFinder objects. This may be useful if working
118 * in a non-english language, allowing the application developer to
119 * replace the standard list with a list of objects which look for xml
120 * attributes in the local language.
121 * <p>
122 * If the intent is just to add an additional rule-finding algorithm, then
123 * it may be better to call #getRuleFinders, and insert a new object into
124 * the start of the list.
125 */
126 public void setRuleFinders(List ruleFinders) {
127 this.ruleFinders = ruleFinders;
128 }
129
130 /**
131 * Sets the xml attribute which the input xml uses to indicate to a
132 * PluginCreateRule which class should be instantiated.
133 * <p>
134 * Example:
135 * <pre>
136 * setPluginClassAttribute(null, "class");
137 * </pre>
138 * will allow this in the input xml:
139 * <pre>
140 * <root>
141 * <some-plugin class="com.acme.widget"> ......
142 * </pre>
143 * instead of the default syntax:
144 * <pre>
145 * <root>
146 * <some-plugin plugin-class="com.acme.widget"> ......
147 * </pre>
148 * This is particularly useful if the input xml document is not in
149 * English.
150 * <p>
151 * Note that the xml attributes used by PluginDeclarationRules are not
152 * affected by this method.
153 *
154 * @param namespaceUri is the namespace uri that the specified attribute
155 * is in. If the attribute is in no namespace, then this should be null.
156 * Note that if a namespace is used, the attrName value should <i>not</i>
157 * contain any kind of namespace-prefix. Note also that if you are using
158 * a non-namespace-aware parser, this parameter <i>must</i> be null.
159 *
160 * @param attrName is the attribute whose value contains the name of the
161 * class to be instantiated.
162 */
163 public void setPluginClassAttribute(String namespaceUri,
164 String attrName) {
165 pluginClassAttrNs = namespaceUri;
166 pluginClassAttr = attrName;
167 }
168
169 /**
170 * Sets the xml attribute which the input xml uses to indicate to a
171 * PluginCreateRule which plugin declaration is being referenced.
172 * <p>
173 * Example:
174 * <pre>
175 * setPluginIdAttribute(null, "id");
176 * </pre>
177 * will allow this in the input xml:
178 * <pre>
179 * <root>
180 * <some-plugin id="widget"> ......
181 * </pre>
182 * rather than the default behaviour:
183 * <pre>
184 * <root>
185 * <some-plugin plugin-id="widget"> ......
186 * </pre>
187 * This is particularly useful if the input xml document is not in
188 * English.
189 * <p>
190 * Note that the xml attributes used by PluginDeclarationRules are not
191 * affected by this method.
192 *
193 * @param namespaceUri is the namespace uri that the specified attribute
194 * is in. If the attribute is in no namespace, then this should be null.
195 * Note that if a namespace is used, the attrName value should <i>not</i>
196 * contain any kind of namespace-prefix. Note also that if you are using
197 * a non-namespace-aware parser, this parameter <i>must</i> be null.
198 *
199 * @param attrName is the attribute whose value contains the id of the
200 * plugin declaration to be used when instantiating an object.
201 */
202 public void setPluginIdAttribute(String namespaceUri,
203 String attrName) {
204 pluginIdAttrNs = namespaceUri;
205 pluginIdAttr = attrName;
206 }
207
208 /**
209 * Get the namespace for the xml attribute which indicates to a
210 * PluginCreateRule which class is to be plugged in.
211 * <p>
212 * May be null (in fact, normally will be).
213 */
214 public String getPluginClassAttrNs() {
215 return pluginClassAttrNs;
216 }
217
218 /**
219 * Get the namespace for the xml attribute which indicates to a
220 * PluginCreateRule which class is to be plugged in.
221 * <p>
222 * The return value is never null.
223 */
224 public String getPluginClassAttr() {
225 return pluginClassAttr;
226 }
227
228 /**
229 * Get the namespace for the xml attribute which indicates to a
230 * PluginCreateRule which previous plugin declaration should be used.
231 * <p>
232 * May be null (in fact, normally will be).
233 */
234 public String getPluginIdAttrNs() {
235 return pluginIdAttrNs;
236 }
237
238 /**
239 * Get the namespace for the xml attribute which indicates to a
240 * PluginCreateRule which previous plugin declaration should be used.
241 * <p>
242 * The return value is never null.
243 */
244 public String getPluginIdAttr() {
245 return pluginIdAttr;
246 }
247 }