[DIGESTER-161] Document thread-safety in javadoc of Rule class - patch provided by Eduard Papa
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/digester/trunk@1239133 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
index f0be32c..ff79fc1 100644
--- a/RELEASE-NOTES.txt
+++ b/RELEASE-NOTES.txt
@@ -18,7 +18,7 @@
Commons Digester Package
- Version 3.2
+ Version 3.3
Release Notes
@@ -27,7 +27,7 @@
This is a maintenance release with new features. New projects are encouraged to
use this release of digester. There is no urgency for existing projects to
-upgrade; Digester 3.1 has proven to be a stable release.
+upgrade; Digester 3.2 has proven to be a stable release.
IMPORTANT NOTES
================
@@ -48,23 +48,17 @@
NEW FEATURES
=============
- * [DIGESTER-153] Add Constructor support to ObjectCreateRule.
+ * NONE
BUGS FIXED SINCE PREVIOUS RELEASE
===========================
- * [DIGESTER-159] */object-param-rule is not managed in the XML rules.
- * [DIGESTER-155] ClassLoader reference set to DigesterLoader not set in produced Digester instances
- * [DIGESTER-154] The DigesterBinder is not able to load primitive classes by name
+ * [DIGESTER-161] Document thread-safety in javadoc of Rule class.
IMPROVEMENTS OVER PREVIOUS RELEASE
===================================
- * [DIGESTER-160] provide an additional artifact with shaded dependencies
- * [DIGESTER-157] Improve Set(Nested)PropertiesRuleAlias performances in the XML ruleset while binding rules
- * [DIGESTER-156] Make (Nested|Set)PropertiesBuilder#addAlias() fluent.
- * [DIGESTER-152] The DigesterLoader doesn't allow binding a default Locator
- * [DIGESTER-151] The DigesterLoader doesn't allow binding a default ErrorHandler.
+ NONE
DEPRECATIONS
============
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index dc539bc..cf1e575 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -22,6 +22,11 @@
<title>Apache Commons Digester Changes</title>
</properties>
<body>
+ <release version="3.3" date="201?-??-??" description="Maintenance release.">
+ <action dev="simonetripodi" type="fix" issue="DIGESTER-161" due-to="Eduard Papa">
+ Document thread-safety in javadoc of Rule class
+ </action>
+ </release>
<release version="3.2" date="2011-12-13" description="Maintenance release.">
<action dev="simonetripodi" type="fix" issue="DIGESTER-160">
provide an additional artifact with shaded dependencies
diff --git a/src/main/java/org/apache/commons/digester3/Rule.java b/src/main/java/org/apache/commons/digester3/Rule.java
index 7abcb22..45bcb05 100644
--- a/src/main/java/org/apache/commons/digester3/Rule.java
+++ b/src/main/java/org/apache/commons/digester3/Rule.java
@@ -22,25 +22,34 @@
import org.xml.sax.Attributes;
/**
- * Concrete implementations of this class implement actions to be taken when a corresponding nested pattern of XML
- * elements has been matched.
+ * Concrete implementations of this class implement actions to be taken when a
+ * corresponding nested pattern of XML elements has been matched.
* <p>
- * Writing a custom Rule is considered perfectly normal when using Digester, and is encouraged whenever the default set
- * of Rule classes don't meet your requirements; the digester framework can help process xml even when the built-in
- * rules aren't quite what is needed. Creating a custom Rule is just as easy as subclassing
- * javax.servlet.http.HttpServlet for webapps, or javax.swing.Action for GUI applications.
+ * Writing a custom Rule is considered perfectly normal when using Digester, and
+ * is encouraged whenever the default set of Rule classes don't meet your
+ * requirements; the digester framework can help process xml even when the
+ * built-in rules aren't quite what is needed. Creating a custom Rule is just as
+ * easy as subclassing javax.servlet.http.HttpServlet for webapps, or
+ * javax.swing.Action for GUI applications.
* <p>
- * If a rule wishes to manipulate a digester stack (the default object stack, a named stack, or the parameter stack)
- * then it should only ever push objects in the rule's begin method and always pop exactly the same number of objects
- * off the stack during the rule's end method. Of course peeking at the objects on the stacks can be done from anywhere.
+ * If a rule wishes to manipulate a digester stack (the default object stack, a
+ * named stack, or the parameter stack) then it should only ever push objects in
+ * the rule's begin method and always pop exactly the same number of objects off
+ * the stack during the rule's end method. Of course peeking at the objects on
+ * the stacks can be done from anywhere.
* <p>
- * Rule objects should be stateless, ie they should not update any instance member during the parsing process. A rule
- * instance that changes state will encounter problems if invoked in a "nested" manner; this can happen if the same
- * instance is added to digester multiple times or if a wildcard pattern is used which can match both an element and a
- * child of the same element. The digester object stack and named stacks should be used to store any state that a rule
- * requires, making the rule class safe under all possible uses.
- */
-public abstract class Rule
+ * Rule objects should limit their state data to the digester object stack and
+ * named stacks. Storing state in instance fields (other than digester) during
+ * the parsing process will cause problems if invoked in a "nested" manner; this
+ * can happen if the same instance is added to digester multiple times or if a
+ * wildcard pattern is used which can match both an element and a child of the
+ * same element.
+ * <p>
+ * Rule objects are not thread-safe when each thread creates a new digester, as
+ * is commonly the case. In a multithreaded context you should create new Rule
+ * instances for every digester or synchronize read/write access to the digester
+ * within the Rule.
+ */public abstract class Rule
{
// ----------------------------------------------------- Instance Variables
@@ -89,7 +98,7 @@
/**
* Set the namespace URI for which this Rule is relevant, if any.
- *
+ *
* @param namespaceURI Namespace URI for which this Rule is relevant, or <code>null</code> to match independent of
* namespace.
*/
@@ -102,7 +111,7 @@
/**
* This method is called when the beginning of a matching XML element is encountered.
- *
+ *
* @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
* aware or the element has no namespace
* @param name the local name if the parser is namespace aware, or just the element name otherwise
@@ -119,7 +128,7 @@
/**
* This method is called when the body of a matching XML element is encountered. If the element has no body, this
* method is called with an empty string as the body text.
- *
+ *
* @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
* aware or the element has no namespace
* @param name the local name if the parser is namespace aware, or just the element name otherwise
@@ -135,7 +144,7 @@
/**
* This method is called when the end of a matching XML element is encountered.
- *
+ *
* @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace
* aware or the element has no namespace
* @param name the local name if the parser is namespace aware, or just the element name otherwise
