commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From skitch...@apache.org
Subject svn commit: r151630 - in jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2: AbstractRuleManager.java DefaultRuleManager.java RuleManager.java
Date Sun, 06 Feb 2005 22:48:37 GMT
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message