001: /* $Id: PluginRules.java 471661 2006-11-06 08:09:25Z skitching $
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:
022: import org.apache.commons.digester.Digester;
023: import org.apache.commons.digester.Rule;
024: import org.apache.commons.digester.Rules;
025: import org.apache.commons.digester.RulesBase;
026: import org.apache.commons.logging.Log;
027:
028: /**
029: * A custom digester Rules manager which must be used as the Rules object
030: * when using the plugins module functionality.
031: * <p>
032: * During parsing, a linked list of PluginCreateRule instances develop, and
033: * this list also acts like a stack. The original instance that was set before
034: * the Digester started parsing is always at the tail of the list, and the
035: * Digester always holds a reference to the instance at the head of the list
036: * in the rules member. Initially, this list/stack holds just one instance,
037: * ie head and tail are the same object.
038: * <p>
039: * When the start of an xml element causes a PluginCreateRule to fire, a new
040: * PluginRules instance is created and inserted at the head of the list (ie
041: * pushed onto the stack of Rules objects). Digester.getRules() therefore
042: * returns this new Rules object, and any custom rules associated with that
043: * plugin are added to that instance.
044: * <p>
045: * When the end of the xml element is encountered (and therefore the
046: * PluginCreateRule end method fires), the stack of Rules objects is popped,
047: * so that Digester.getRules returns the previous Rules object.
048: *
049: * @since 1.6
050: */
051:
052: public class PluginRules implements Rules {
053:
054: /**
055: * The Digester instance with which this Rules instance is associated.
056: */
057: protected Digester digester = null;
058:
059: /**
060: * The (optional) object which generates new rules instances.
061: */
062: private RulesFactory rulesFactory;
063:
064: /**
065: * The rules implementation that we are "enhancing" with plugins
066: * functionality, as per the Decorator pattern.
067: */
068: private Rules decoratedRules;
069:
070: /** Object which contains information about all known plugins. */
071: private PluginManager pluginManager;
072:
073: /**
074: * The path below which this rules object has responsibility.
075: * For paths shorter than or equal the mountpoint, the parent's
076: * match is called.
077: */
078: private String mountPoint = null;
079:
080: /**
081: * The Rules object that holds rules applying "above" the mountpoint,
082: * ie the next Rules object down in the stack.
083: */
084: private PluginRules parent = null;
085:
086: /**
087: * A reference to the object that holds all data which should only
088: * exist once per digester instance.
089: */
090: private PluginContext pluginContext = null;
091:
092: // ------------------------------------------------------------- Constructor
093:
094: /**
095: * Constructor for top-level Rules objects. Exactly one of these must
096: * be created and installed into the Digester instance as the Rules
097: * object before parsing starts.
098: */
099: public PluginRules() {
100: this (new RulesBase());
101: }
102:
103: /**
104: * Constructor for top-level Rules object which handles rule-matching
105: * using the specified implementation.
106: */
107: public PluginRules(Rules decoratedRules) {
108: this .decoratedRules = decoratedRules;
109:
110: pluginContext = new PluginContext();
111: pluginManager = new PluginManager(pluginContext);
112: }
113:
114: /**
115: * Constructs a Rules instance which has a parent Rules object
116: * (which is different from having a delegate rules object).
117: * <p>
118: * One of these is created each time a PluginCreateRule's begin method
119: * fires, in order to manage the custom rules associated with whatever
120: * concrete plugin class the user has specified.
121: *
122: * @param digester is the object this rules will be associated with.
123: * @param mountPoint is the digester match path for the element
124: * matching a PluginCreateRule which caused this "nested parsing scope"
125: * to begin. This is expected to be equal to digester.getMatch().
126: * @param parent must be non-null.
127: * @param pluginClass is the plugin class whose custom rules will be
128: * loaded into this new PluginRules object.
129: */
130: PluginRules(Digester digester, String mountPoint,
131: PluginRules parent, Class pluginClass)
132: throws PluginException {
133: // no need to set digester or decoratedRules.digester,
134: // because when Digester.setRules is called, the setDigester
135: // method on this object will be called.
136:
137: this .digester = digester;
138: this .mountPoint = mountPoint;
139: this .parent = parent;
140: this .rulesFactory = parent.rulesFactory;
141:
142: if (rulesFactory == null) {
143: decoratedRules = new RulesBase();
144: } else {
145: decoratedRules = rulesFactory.newRules(digester,
146: pluginClass);
147: }
148:
149: pluginContext = parent.pluginContext;
150: pluginManager = new PluginManager(parent.pluginManager);
151: }
152:
153: // ------------------------------------------------------------- Properties
154:
155: /**
156: * Return the parent Rules object.
157: */
158: public Rules getParent() {
159: return parent;
160: }
161:
162: /**
163: * Return the Digester instance with which this instance is associated.
164: */
165: public Digester getDigester() {
166: return digester;
167: }
168:
169: /**
170: * Set the Digester instance with which this Rules instance is associated.
171: *
172: * @param digester The newly associated Digester instance
173: */
174: public void setDigester(Digester digester) {
175: this .digester = digester;
176: decoratedRules.setDigester(digester);
177: }
178:
179: /**
180: * Return the namespace URI that will be applied to all subsequently
181: * added <code>Rule</code> objects.
182: */
183: public String getNamespaceURI() {
184: return decoratedRules.getNamespaceURI();
185: }
186:
187: /**
188: * Set the namespace URI that will be applied to all subsequently
189: * added <code>Rule</code> objects.
190: *
191: * @param namespaceURI Namespace URI that must match on all
192: * subsequently added rules, or <code>null</code> for matching
193: * regardless of the current namespace URI
194: */
195: public void setNamespaceURI(String namespaceURI) {
196: decoratedRules.setNamespaceURI(namespaceURI);
197: }
198:
199: /**
200: * Return the object which "knows" about all declared plugins.
201: *
202: * @return The pluginManager value
203: */
204: public PluginManager getPluginManager() {
205: return pluginManager;
206: }
207:
208: /**
209: * See {@link PluginContext#getRuleFinders}.
210: */
211: public List getRuleFinders() {
212: return pluginContext.getRuleFinders();
213: }
214:
215: /**
216: * See {@link PluginContext#setRuleFinders}.
217: */
218: public void setRuleFinders(List ruleFinders) {
219: pluginContext.setRuleFinders(ruleFinders);
220: }
221:
222: /**
223: * Return the rules factory object (or null if one has not been specified).
224: */
225: public RulesFactory getRulesFactory() {
226: return rulesFactory;
227: }
228:
229: /**
230: * Set the object which is used to generate the new Rules instances created
231: * to hold and process the rules associated with each plugged-in class.
232: */
233: public void setRulesFactory(RulesFactory factory) {
234: rulesFactory = factory;
235: }
236:
237: // --------------------------------------------------------- Public Methods
238:
239: /**
240: * This package-scope method is used by the PluginCreateRule class to
241: * get direct access to the rules that were dynamically added by the
242: * plugin. No other class should need access to this object.
243: */
244: Rules getDecoratedRules() {
245: return decoratedRules;
246: }
247:
248: /**
249: * Return the list of rules registered with this object, in the order
250: * they were registered with this object.
251: * <p>
252: * Note that Rule objects stored in parent Rules objects are not
253: * returned by this method.
254: *
255: * @return list of all Rule objects known to this Rules instance.
256: */
257: public List rules() {
258: return decoratedRules.rules();
259: }
260:
261: /**
262: * Register a new Rule instance matching the specified pattern.
263: *
264: * @param pattern Nesting pattern to be matched for this Rule.
265: * This parameter treats equally patterns that begin with and without
266: * a leading slash ('/').
267: * @param rule Rule instance to be registered
268: */
269: public void add(String pattern, Rule rule) {
270: Log log = LogUtils.getLogger(digester);
271: boolean debug = log.isDebugEnabled();
272:
273: if (debug) {
274: log.debug("add entry" + ": mapping pattern [" + pattern
275: + "]" + " to rule of type ["
276: + rule.getClass().getName() + "]");
277: }
278:
279: // allow patterns with a leading slash character
280: if (pattern.startsWith("/")) {
281: pattern = pattern.substring(1);
282: }
283:
284: if (mountPoint != null) {
285: if (!pattern.equals(mountPoint)
286: && !pattern.startsWith(mountPoint + "/")) {
287: // This can only occur if a plugin attempts to add a
288: // rule with a pattern that doesn't start with the
289: // prefix passed to the addRules method. Plugins mustn't
290: // add rules outside the scope of the tag they were specified
291: // on, so refuse this.
292:
293: // alas, can't throw exception
294: log
295: .warn("An attempt was made to add a rule with a pattern that"
296: + "is not at or below the mountpoint of the current"
297: + " PluginRules object."
298: + " Rule pattern: "
299: + pattern
300: + ", mountpoint: "
301: + mountPoint
302: + ", rule type: "
303: + rule.getClass().getName());
304: return;
305: }
306: }
307:
308: decoratedRules.add(pattern, rule);
309:
310: if (rule instanceof InitializableRule) {
311: try {
312: ((InitializableRule) rule).postRegisterInit(pattern);
313: } catch (PluginConfigurationException e) {
314: // Currently, Digester doesn't handle exceptions well
315: // from the add method. The workaround is for the
316: // initialisable rule to remember that its initialisation
317: // failed, and to throw the exception when begin is
318: // called for the first time.
319: if (debug) {
320: log.debug("Rule initialisation failed", e);
321: }
322: // throw e; -- alas, can't do this
323: return;
324: }
325: }
326:
327: if (debug) {
328: log.debug("add exit" + ": mapped pattern [" + pattern + "]"
329: + " to rule of type [" + rule.getClass().getName()
330: + "]");
331: }
332: }
333:
334: /**
335: * Clear all rules.
336: */
337: public void clear() {
338: decoratedRules.clear();
339: }
340:
341: /**
342: * Return a List of all registered Rule instances that match the specified
343: * nesting pattern, or a zero-length List if there are no matches. If more
344: * than one Rule instance matches, they <strong>must</strong> be returned
345: * in the order originally registered through the <code>add()</code>
346: * method.
347: *
348: * @param path the path to the xml nodes to be matched.
349: *
350: * @deprecated Call match(namespaceURI,pattern) instead.
351: */
352: public List match(String path) {
353: return (match(null, path));
354: }
355:
356: /**
357: * Return a List of all registered Rule instances that match the specified
358: * nodepath, or a zero-length List if there are no matches. If more
359: * than one Rule instance matches, they <strong>must</strong> be returned
360: * in the order originally registered through the <code>add()</code>
361: * method.
362: * <p>
363: * @param namespaceURI Namespace URI for which to select matching rules,
364: * or <code>null</code> to match regardless of namespace URI
365: * @param path the path to the xml nodes to be matched.
366: */
367: public List match(String namespaceURI, String path) {
368: Log log = LogUtils.getLogger(digester);
369: boolean debug = log.isDebugEnabled();
370:
371: if (debug) {
372: log.debug("Matching path [" + path + "] on rules object "
373: + this .toString());
374: }
375:
376: List matches;
377: if ((mountPoint != null)
378: && (path.length() <= mountPoint.length())) {
379: if (debug) {
380: log.debug("Path [" + path + "] delegated to parent.");
381: }
382:
383: matches = parent.match(namespaceURI, path);
384:
385: // Note that in the case where path equals mountPoint,
386: // we deliberately return only the rules from the parent,
387: // even though this object may hold some rules matching
388: // this same path. See PluginCreateRule's begin, body and end
389: // methods for the reason.
390: } else {
391: log.debug("delegating to decorated rules.");
392: matches = decoratedRules.match(namespaceURI, path);
393: }
394:
395: return matches;
396: }
397:
398: /** See {@link PluginContext#setPluginClassAttribute}. */
399: public void setPluginClassAttribute(String namespaceUri,
400: String attrName) {
401: pluginContext.setPluginClassAttribute(namespaceUri, attrName);
402: }
403:
404: /** See {@link PluginContext#setPluginIdAttribute}. */
405: public void setPluginIdAttribute(String namespaceUri,
406: String attrName) {
407: pluginContext.setPluginIdAttribute(namespaceUri, attrName);
408: }
409:
410: /** See {@link PluginContext#getPluginClassAttrNs}. */
411: public String getPluginClassAttrNs() {
412: return pluginContext.getPluginClassAttrNs();
413: }
414:
415: /** See {@link PluginContext#getPluginClassAttr}. */
416: public String getPluginClassAttr() {
417: return pluginContext.getPluginClassAttr();
418: }
419:
420: /** See {@link PluginContext#getPluginIdAttrNs}. */
421: public String getPluginIdAttrNs() {
422: return pluginContext.getPluginIdAttrNs();
423: }
424:
425: /** See {@link PluginContext#getPluginIdAttr}. */
426: public String getPluginIdAttr() {
427: return pluginContext.getPluginIdAttr();
428: }
429: }
|