Java tutorial
package org.apache.commons.digester3.plugins; /* * 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. */ import java.util.List; import org.apache.commons.digester3.Digester; import org.apache.commons.digester3.Rule; import org.apache.commons.digester3.Rules; import org.apache.commons.digester3.RulesBase; import org.apache.commons.logging.Log; import org.xml.sax.Attributes; /** * 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. * * @param decoratedRules The 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. * @throws PluginException if any error occurs */ 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. * * @return the parent Rules object. */ public Rules getParent() { return parent; } /** * Return the Digester instance with which this instance is associated. * * @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. * * @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}. * * @return the list of RuleFinder objects */ public List<RuleFinder> getRuleFinders() { return pluginContext.getRuleFinders(); } /** * See {@link PluginContext#setRuleFinders}. * * @param ruleFinders the list of RuleFinder objects */ public void setRuleFinders(List<RuleFinder> ruleFinders) { pluginContext.setRuleFinders(ruleFinders); } /** * Return the rules factory object (or null if one has not been specified). * * @return the rules factory object. */ 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. * * @param factory the rules factory object */ 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. * * @return The decorated Rule instance */ 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) { Log log = LogUtils.getLogger(digester); boolean debug = log.isDebugEnabled(); if (debug) { log.debug("add entry" + ": mapping pattern [" + pattern + "]" + " to rule of type [" + rule.getClass().getName() + "]"); } // 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 log.warn("An attempt was made to add a rule with a pattern that" + "is not at or below the mountpoint of the current" + " PluginRules object." + " Rule pattern: " + pattern + ", mountpoint: " + mountPoint + ", rule type: " + rule.getClass().getName()); 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. if (debug) { log.debug("Rule initialisation failed", e); } // throw e; -- alas, can't do this return; } } if (debug) { log.debug("add exit" + ": mapped pattern [" + pattern + "]" + " to rule of type [" + rule.getClass().getName() + "]"); } } /** * Clear all rules. */ public void clear() { decoratedRules.clear(); } /** * {@inheritDoc} */ public List<Rule> match(String namespaceURI, String path, String name, Attributes attributes) { Log log = LogUtils.getLogger(digester); boolean debug = log.isDebugEnabled(); if (debug) { log.debug("Matching path [" + path + "] on rules object " + this.toString()); } List<Rule> matches; if ((mountPoint != null) && (path.length() <= mountPoint.length())) { if (debug) { log.debug("Path [" + path + "] delegated to parent."); } matches = parent.match(namespaceURI, path, name, attributes); // 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 { log.debug("delegating to decorated rules."); matches = decoratedRules.match(namespaceURI, path, name, attributes); } return matches; } /** * See {@link PluginContext#setPluginClassAttribute}. * * @param namespaceUri is the namespace uri that the specified attribute is in. If the attribute is in no namespace, * then this should be null. Note that if a namespace is used, the attrName value should <i>not</i> * contain any kind of namespace-prefix. Note also that if you are using a non-namespace-aware parser, * this parameter <i>must</i> be null. * @param attrName is the attribute whose value contains the name of the class to be instantiated. * */ public void setPluginClassAttribute(String namespaceUri, String attrName) { pluginContext.setPluginClassAttribute(namespaceUri, attrName); } /** * See {@link PluginContext#setPluginIdAttribute}. * * @param namespaceUri is the namespace uri that the specified attribute is in. If the attribute is in no namespace, * then this should be null. Note that if a namespace is used, the attrName value should <i>not</i> * contain any kind of namespace-prefix. Note also that if you are using a non-namespace-aware parser, * this parameter <i>must</i> be null. * @param attrName is the attribute whose value contains the id of the plugin declaration to be used when * instantiating an object. **/ public void setPluginIdAttribute(String namespaceUri, String attrName) { pluginContext.setPluginIdAttribute(namespaceUri, attrName); } /** * See {@link PluginContext#getPluginClassAttrNs}. * * @return the namespace for the xml attribute which indicates which class is to be plugged in. */ public String getPluginClassAttrNs() { return pluginContext.getPluginClassAttrNs(); } /** * See {@link PluginContext#getPluginClassAttr}. * * @return the namespace for the xml attribute which indicates which class is to be plugged in. */ public String getPluginClassAttr() { return pluginContext.getPluginClassAttr(); } /** * See {@link PluginContext#getPluginIdAttrNs}. * * @return the namespace for the xml attribute which indicates which previous plugin declaration should be used. */ public String getPluginIdAttrNs() { return pluginContext.getPluginIdAttrNs(); } /** * See {@link PluginContext#getPluginIdAttr}. * * @return the namespace for the xml attribute which indicates which previous plugin declaration should be used. */ public String getPluginIdAttr() { return pluginContext.getPluginIdAttr(); } }