Java tutorial
/* $Id: PluginRules.java 992104 2010-09-02 20:24:31Z simonetripodi $ * * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.digester.plugins; import java.util.List; import org.apache.commons.digester.Digester; import org.apache.commons.digester.Rule; import org.apache.commons.digester.Rules; import org.apache.commons.digester.RulesBase; /** * A custom digester Rules manager which must be used as the Rules object * when using the plugins module functionality. * <p> * During parsing, a linked list of PluginCreateRule instances develop, and * this list also acts like a stack. The original instance that was set before * the Digester started parsing is always at the tail of the list, and the * Digester always holds a reference to the instance at the head of the list * in the rules member. Initially, this list/stack holds just one instance, * ie head and tail are the same object. * <p> * When the start of an xml element causes a PluginCreateRule to fire, a new * PluginRules instance is created and inserted at the head of the list (ie * pushed onto the stack of Rules objects). Digester.getRules() therefore * returns this new Rules object, and any custom rules associated with that * plugin are added to that instance. * <p> * When the end of the xml element is encountered (and therefore the * PluginCreateRule end method fires), the stack of Rules objects is popped, * so that Digester.getRules returns the previous Rules object. * * @since 1.6 */ public class PluginRules implements Rules { /** * The Digester instance with which this Rules instance is associated. */ protected Digester digester = null; /** * The (optional) object which generates new rules instances. */ private RulesFactory rulesFactory; /** * The rules implementation that we are "enhancing" with plugins * functionality, as per the Decorator pattern. */ private Rules decoratedRules; /** Object which contains information about all known plugins. */ private PluginManager pluginManager; /** * The path below which this rules object has responsibility. * For paths shorter than or equal the mountpoint, the parent's * match is called. */ private String mountPoint = null; /** * The Rules object that holds rules applying "above" the mountpoint, * ie the next Rules object down in the stack. */ private PluginRules parent = null; /** * A reference to the object that holds all data which should only * exist once per digester instance. */ private PluginContext pluginContext = null; // ------------------------------------------------------------- Constructor /** * Constructor for top-level Rules objects. Exactly one of these must * be created and installed into the Digester instance as the Rules * object before parsing starts. */ public PluginRules() { this(new RulesBase()); } /** * Constructor for top-level Rules object which handles rule-matching * using the specified implementation. */ public PluginRules(Rules decoratedRules) { this.decoratedRules = decoratedRules; pluginContext = new PluginContext(); pluginManager = new PluginManager(pluginContext); } /** * Constructs a Rules instance which has a parent Rules object * (which is different from having a delegate rules object). * <p> * One of these is created each time a PluginCreateRule's begin method * fires, in order to manage the custom rules associated with whatever * concrete plugin class the user has specified. * * @param digester is the object this rules will be associated with. * @param mountPoint is the digester match path for the element * matching a PluginCreateRule which caused this "nested parsing scope" * to begin. This is expected to be equal to digester.getMatch(). * @param parent must be non-null. * @param pluginClass is the plugin class whose custom rules will be * loaded into this new PluginRules object. */ PluginRules(Digester digester, String mountPoint, PluginRules parent, Class<?> pluginClass) throws PluginException { // no need to set digester or decoratedRules.digester, // because when Digester.setRules is called, the setDigester // method on this object will be called. this.digester = digester; this.mountPoint = mountPoint; this.parent = parent; this.rulesFactory = parent.rulesFactory; if (rulesFactory == null) { decoratedRules = new RulesBase(); } else { decoratedRules = rulesFactory.newRules(digester, pluginClass); } pluginContext = parent.pluginContext; pluginManager = new PluginManager(parent.pluginManager); } // ------------------------------------------------------------- Properties /** * Return the parent Rules object. */ public Rules getParent() { return parent; } /** * Return the Digester instance with which this instance is associated. */ public Digester getDigester() { return digester; } /** * Set the Digester instance with which this Rules instance is associated. * * @param digester The newly associated Digester instance */ public void setDigester(Digester digester) { this.digester = digester; decoratedRules.setDigester(digester); } /** * Return the namespace URI that will be applied to all subsequently * added <code>Rule</code> objects. */ public String getNamespaceURI() { return decoratedRules.getNamespaceURI(); } /** * Set the namespace URI that will be applied to all subsequently * added <code>Rule</code> objects. * * @param namespaceURI Namespace URI that must match on all * subsequently added rules, or <code>null</code> for matching * regardless of the current namespace URI */ public void setNamespaceURI(String namespaceURI) { decoratedRules.setNamespaceURI(namespaceURI); } /** * Return the object which "knows" about all declared plugins. * * @return The pluginManager value */ public PluginManager getPluginManager() { return pluginManager; } /** * See {@link PluginContext#getRuleFinders}. */ public List<RuleFinder> getRuleFinders() { return pluginContext.getRuleFinders(); } /** * See {@link PluginContext#setRuleFinders}. */ public void setRuleFinders(List<RuleFinder> ruleFinders) { pluginContext.setRuleFinders(ruleFinders); } /** * Return the rules factory object (or null if one has not been specified). */ public RulesFactory getRulesFactory() { return rulesFactory; } /** * Set the object which is used to generate the new Rules instances created * to hold and process the rules associated with each plugged-in class. */ public void setRulesFactory(RulesFactory factory) { rulesFactory = factory; } // --------------------------------------------------------- Public Methods /** * This package-scope method is used by the PluginCreateRule class to * get direct access to the rules that were dynamically added by the * plugin. No other class should need access to this object. */ Rules getDecoratedRules() { return decoratedRules; } /** * Return the list of rules registered with this object, in the order * they were registered with this object. * <p> * Note that Rule objects stored in parent Rules objects are not * returned by this method. * * @return list of all Rule objects known to this Rules instance. */ public List<Rule> rules() { return decoratedRules.rules(); } /** * Register a new Rule instance matching the specified pattern. * * @param pattern Nesting pattern to be matched for this Rule. * This parameter treats equally patterns that begin with and without * a leading slash ('/'). * @param rule Rule instance to be registered */ public void add(String pattern, Rule rule) { // allow patterns with a leading slash character if (pattern.startsWith("/")) { pattern = pattern.substring(1); } if (mountPoint != null && !pattern.equals(mountPoint) && !pattern.startsWith(mountPoint + "/")) { // This can only occur if a plugin attempts to add a // rule with a pattern that doesn't start with the // prefix passed to the addRules method. Plugins mustn't // add rules outside the scope of the tag they were specified // on, so refuse this. // alas, can't throw exception return; } decoratedRules.add(pattern, rule); if (rule instanceof InitializableRule) { try { ((InitializableRule) rule).postRegisterInit(pattern); } catch (PluginConfigurationException e) { // Currently, Digester doesn't handle exceptions well // from the add method. The workaround is for the // initialisable rule to remember that its initialisation // failed, and to throw the exception when begin is // called for the first time. // throw e; -- alas, can't do this return; } } } /** * Clear all rules. */ public void clear() { decoratedRules.clear(); } /** * Return a List of all registered Rule instances that match the specified * nesting pattern, or a zero-length List if there are no matches. If more * than one Rule instance matches, they <strong>must</strong> be returned * in the order originally registered through the <code>add()</code> * method. * * @param path the path to the xml nodes to be matched. * * @deprecated Call match(namespaceURI,pattern) instead. */ @Deprecated public List<Rule> match(String path) { return (match(null, path)); } /** * Return a List of all registered Rule instances that match the specified * nodepath, or a zero-length List if there are no matches. If more * than one Rule instance matches, they <strong>must</strong> be returned * in the order originally registered through the <code>add()</code> * method. * <p> * @param namespaceURI Namespace URI for which to select matching rules, * or <code>null</code> to match regardless of namespace URI * @param path the path to the xml nodes to be matched. */ public List<Rule> match(String namespaceURI, String path) { List<Rule> matches; if ((mountPoint != null) && (path.length() <= mountPoint.length())) { matches = parent.match(namespaceURI, path); // Note that in the case where path equals mountPoint, // we deliberately return only the rules from the parent, // even though this object may hold some rules matching // this same path. See PluginCreateRule's begin, body and end // methods for the reason. } else { matches = decoratedRules.match(namespaceURI, path); } return matches; } /** See {@link PluginContext#setPluginClassAttribute}. */ public void setPluginClassAttribute(String namespaceUri, String attrName) { pluginContext.setPluginClassAttribute(namespaceUri, attrName); } /** See {@link PluginContext#setPluginIdAttribute}. */ public void setPluginIdAttribute(String namespaceUri, String attrName) { pluginContext.setPluginIdAttribute(namespaceUri, attrName); } /** See {@link PluginContext#getPluginClassAttrNs}. */ public String getPluginClassAttrNs() { return pluginContext.getPluginClassAttrNs(); } /** See {@link PluginContext#getPluginClassAttr}. */ public String getPluginClassAttr() { return pluginContext.getPluginClassAttr(); } /** See {@link PluginContext#getPluginIdAttrNs}. */ public String getPluginIdAttrNs() { return pluginContext.getPluginIdAttrNs(); } /** See {@link PluginContext#getPluginIdAttr}. */ public String getPluginIdAttr() { return pluginContext.getPluginIdAttr(); } }