| 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(); |
| } |
| |
| } |