Author: skitching Date: Sun Feb 6 14:48:36 2005 New Revision: 151630 URL: http://svn.apache.org/viewcvs?view=rev&rev=151630 Log: Made RuleManager an interface, and defined AbstractRuleManager as an abstract base class. This makes RuleManager consistent with Action.
Also added svn:keywords property so $Id$ will get expanded. Added: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/AbstractRuleManager.java Modified: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/DefaultRuleManager.java (contents, props changed) jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/RuleManager.java (contents, props changed) Added: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/AbstractRuleManager.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/AbstractRuleManager.java?view=auto&rev=151630 ============================================================================== --- jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/AbstractRuleManager.java (added) +++ jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/AbstractRuleManager.java Sun Feb 6 14:48:36 2005 @@ -0,0 +1,93 @@ +/* $Id$ + * + * Copyright 2001-2005 The Apache Software Foundation. + * + * Licensed 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.digester2; + +import java.util.List; + +/** + * Provides a base implementation for custom RuleManagers (ie classes that + * match input xml elements to lists of Actions to be executed). + * <p> + * Note that extending this abstract class rather than directly implementing + * the RuleManager interface provides much better "forward compatibility". + * Digester minor releases (2.x -> 2.y) guarantee not to break any classes that + * subclass this abstract class. However no such guarantee exists for classes + * that directly implement the RuleManager interface. + */ + +public abstract class AbstractRuleManager implements RuleManager { + + /** + * Returns a new instance with the same type as the concrete object this + * method is invoked on, complete with contained Actions and patterns. Note + * that the new RuleManager instance may contain references to the same + * Action instances as the old one, as Action instances are expected to be + * stateless and therefore can be safely shared between RuleManagers. + */ + public abstract RuleManager copy(); + + /** + * Invoked before parsing each input document, this method gives the + * RuleManager and the managed Action objects the opportunity to do + * per-parse initialisation if required. + */ + public void startParse(Context context) throws DigestionException {} + + /** + * Invoked after parsing each input document, this method gives the + * RuleManager and the managed Action objects the opportunity to do + * per-parse cleanup if required. + */ + public void finishParse(Context context) throws DigestionException {} + + /** + * Define a mapping between xml element prefix and namespace uri + * for use when rule patterns contain namespace prefixes. + */ + public abstract void addNamespace(String prefix, String uri); + + /** + * Cause the specified Action to be invoked whenever an xml element + * is encountered in the input which matches the specified pattern. + * <p> + * If the pattern contains any namespace prefixes, eg "/myns:item", + * then an exception will be thrown unless that prefix has previously + * been defined via a call to method addNamespace. + * <p> + * Note that it is permitted for the same Action to be added multiple + * times with different associated patterns. + */ + public abstract void addRule(String pattern, Action action) + throws InvalidRuleException; + + /** + * Return a List of all registered Action instances that match the specified + * nesting pattern, or a zero-length List if there are no matches. If more + * than one Action instance matches, they <strong>must</strong> be returned + * in the order originally registered through the <code>addRule()</code> + * method. + * + * @param path is a string of form + * <pre>/{namespace}elementName/{namespace}elementName"</pre> + * identifying the path from the root of the input document to the element + * for which the caller wants the set of matching Action objects. If an + * element has no namespace, then the {} part is omitted. + */ + public abstract List getMatchingActions(String path) + throws DigestionException; +} Modified: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/DefaultRuleManager.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/DefaultRuleManager.java?view=diff&r1=151629&r2=151630 ============================================================================== --- jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/DefaultRuleManager.java (original) +++ jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/DefaultRuleManager.java Sun Feb 6 14:48:36 2005 @@ -1,6 +1,6 @@ -/* $Id: $ +/* $Id$ * - * Copyright 2001-2004 The Apache Software Foundation. + * Copyright 2001-2005 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -48,9 +48,11 @@ * an existing RuleManager instance. */ -public class DefaultRuleManager extends RuleManager { +public class DefaultRuleManager extends AbstractRuleManager { - // ----------------------------------------------------- Instance Variables + // ----------------------------------------------------- + // Instance Variables + // ----------------------------------------------------- /** * Map of namespace-prefix to namespace-uri, used only by the @@ -72,7 +74,9 @@ */ private MultiHashMap rules = new MultiHashMap(); - // --------------------------------------------------------- Public Methods + // --------------------------------------------------------- + // Public Methods + // --------------------------------------------------------- /** * Return a clone of this object. The Action objects currently @@ -229,7 +233,6 @@ } } - /** * Return a List of all registered Action instances, or a zero-length List * if there are no registered Action instances. @@ -238,8 +241,7 @@ * instance has been added multiple times, then its order is set by the * first time it was added. */ - public List actions() { + public List getActions() { return this.actions; } - } Propchange: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/DefaultRuleManager.java ------------------------------------------------------------------------------ svn:keywords = Id Modified: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/RuleManager.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/RuleManager.java?view=diff&r1=151629&r2=151630 ============================================================================== --- jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/RuleManager.java (original) +++ jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/RuleManager.java Sun Feb 6 14:48:36 2005 @@ -1,6 +1,6 @@ -/* $Id: $ +/* $Id$ * - * Copyright 2001-2004 The Apache Software Foundation. + * Copyright 2001-2005 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -30,12 +30,16 @@ * <li>Pattern: a string with namespace prefixes in it, eg "/foo:bob"</li> * <li>Path: a string with namespace uris in it, eg /{urn:foo}bob"</li> * </ul> - * + * <p> + * <strong>IMPORTANT NOTE</strong>: Anyone implementing a custom RuleManager is + * strongly encouraged to subclass AbstractRuleManager rather than implement this + * interface directly. Digester minor releases (2.x -> 2.y) guarantee that + * subclasses of AbstractRuleManager will not be broken. However the RuleManager + * interface <i>may</i> change in minor releases, which will break any class + * which implements this interface directly. */ -public abstract class RuleManager { - - // --------------------------------------------------------- Public Methods +public interface RuleManager { /** * Returns a new instance with the same type as the concrete object this @@ -44,27 +48,27 @@ * Action instances as the old one, as Action instances are expected to be * stateless and therefore can be safely shared between RuleManagers. */ - public abstract RuleManager copy(); + public RuleManager copy(); /** * Invoked before parsing each input document, this method gives the * RuleManager and the managed Action objects the opportunity to do * per-parse initialisation if required. */ - public void startParse(Context context) throws DigestionException {} + public void startParse(Context context) throws DigestionException; /** * Invoked after parsing each input document, this method gives the * RuleManager and the managed Action objects the opportunity to do * per-parse cleanup if required. */ - public void finishParse(Context context) throws DigestionException {} + public void finishParse(Context context) throws DigestionException; /** * Define a mapping between xml element prefix and namespace uri * for use when rule patterns contain namespace prefixes. */ - public abstract void addNamespace(String prefix, String uri); + public void addNamespace(String prefix, String uri); /** * Cause the specified Action to be invoked whenever an xml element @@ -77,8 +81,7 @@ * Note that it is permitted for the same Action to be added multiple * times with different associated patterns. */ - public abstract void addRule(String pattern, Action action) - throws InvalidRuleException; + public void addRule(String pattern, Action action) throws InvalidRuleException; /** * Return a List of all registered Action instances that match the specified @@ -93,6 +96,5 @@ * for which the caller wants the set of matching Action objects. If an * element has no namespace, then the {} part is omitted. */ - public abstract List getMatchingActions(String path) - throws DigestionException; + public List getMatchingActions(String path) throws DigestionException; } Propchange: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/RuleManager.java ------------------------------------------------------------------------------ svn:keywords = Id --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]