Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Message-ID: <20050213105957.10312.qmail@minotaur.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Date: Sun, 13 Feb 2005 10:59:57 -0000
Subject: svn commit: r153616 -
 jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/SAXHandler.java
To: commons-cvs@jakarta.apache.org
From: skitching@apache.org

Author: skitching
Date: Sun Feb 13 02:59:56 2005
New Revision: 153616

URL: http://svn.apache.org/viewcvs?view=3Drev&rev=3D153616
Log:
Keep local copy of root object, so context can be discarded after parse com=
pletes.

Modified:
    jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/=
commons/digester2/SAXHandler.java

Modified: jakarta/commons/proper/digester/branches/digester2/src/java/org/a=
pache/commons/digester2/SAXHandler.java
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/digester/branches=
/digester2/src/java/org/apache/commons/digester2/SAXHandler.java?view=3Ddif=
f&r1=3D153615&r2=3D153616
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/=
commons/digester2/SAXHandler.java (original)
+++ jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/=
commons/digester2/SAXHandler.java Sun Feb 13 02:59:56 2005
@@ -206,6 +206,10 @@
      * The Locator associated with our parser object. This object can be
      * consulted to find out which line of the input xml document we are
      * currently on - very useful when generating error messages.
+     * <p>
+     * We store this variable on the SAXHandler class as well as the Conte=
xt
+     * because the Context object is not created until the startDocument=20
+     * method is invoked - which is after setDocumentLocator.
      */
     private Locator documentLocator =3D null;
=20
@@ -227,6 +231,15 @@
      */
     private String dtdSystemId =3D null;
=20
+    /**
+     * The object that forms the root of the tree of objects being
+     * created during a parse.=20
+     * <p>
+     * Note that this info is not on the Context because the user may
+     * access this data after the parse has completed.
+     */
+    private Object root;
+
     // ---------------------------------------------------------
     // Constructors
     // ---------------------------------------------------------
@@ -474,7 +487,8 @@
=20
     /**
      * Set the object that the stack should be primed with before parsing
-     * starts.
+     * starts. Note that this value is reset to null after parsing a docum=
ent,
+     * so must be set before each parse.
      */
     public void setInitialObject(Object o) {
         initialObject =3D o;
@@ -485,11 +499,7 @@
      * should not be called until parsing has completed.
      */
     public Object getRoot() {
-        if (context =3D=3D null) {
-            return null;
-        } else {
-            return context.getRoot();
-        }
+        return root;
     }
=20
     /**
@@ -654,15 +664,23 @@
=20
     /**
      * Cleanup method which releases any memory that is no longer needed
-     * after a parse has completed. There is one exception: the root
-     * object generated during the parse is retained so that it can be
-     * retrieved by getRoot(). If this is no longer needed, then setRoot(n=
ull)
-     * should be called to release this member.
+     * after a parse has completed.
+     * <p>
+     * This method should generally be called if the reference to the dige=
ster
+     * is to be retained for some time (eg returned to a pool) in order to
+     * avoid holding memory occupied for more time than is necessary.
+     * <p>
+     * This method definitely needs to be called after a parse has failed,=
 ie
+     * an exception has been thrown, in order to free memory (unless all
+     * references to the digester itself are discarded, allowing it to be
+     * recycled together with its dependent objects).
+     * <p>
+     * After this call, the getRoot method will return null.
      */
     public void clear() {
-        // It would be nice to set
-        //   context =3D null;
-        // but currently that would stuff up the getRoot() method.
+        context =3D null; // only necessary if parse failed
+        initialObject =3D null; // should not be necessary
+        root =3D null;
     }
=20
     // -------------------------------------------------------
@@ -780,6 +798,7 @@
         numEntitiesResolved =3D 0;
         dtdPublicId =3D null;
         dtdSystemId =3D null;
+        root =3D null; // just in case
=20
         // Create a new parsing context. This guarantees that Actions have
         // a clean slate for handling this new input document.
@@ -787,6 +806,10 @@
=20
         if (initialObject !=3D null) {
             context.setRoot(initialObject);
+
+            // Initial object should apply to a single parse only, so lets
+            // enforce it here.
+            initialObject =3D null;=20
         }
=20
         // give subclasses a chance to do custom configuration before each
@@ -846,8 +869,14 @@
             throw new NestedSAXException(ex);
         }
=20
-        // Perform final cleanup to release memory that is no longer neede=
d=2E
-        clear();
+        // store the root object so the user can access it
+        root =3D context.getRoot();
+       =20
+        // And now we don't need the context any more, so allow it to be
+        // reclaimed. Note that in the case where a parse failed, this
+        // method is never called, so the user is responsible for calling
+        // the clear method.
+        context =3D null;
     }
=20
     /**


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org