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