001 /* $Id: PluginContext.java 729117 2008-12-23 21:09:13Z 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<RuleFinder> 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<RuleFinder> 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<RuleFinder>(); 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<RuleFinder> 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 }