sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1467296 - in /sis/branches/JDK7/sis-utility/src: main/java/org/apache/sis/xml/MarshallerPool.java main/java/org/apache/sis/xml/XML.java test/java/org/apache/sis/xml/MarshallerPoolTest.java
Date Fri, 12 Apr 2013 14:52:56 GMT
Author: desruisseaux
Date: Fri Apr 12 14:52:56 2013
New Revision: 1467296

URL: http://svn.apache.org/r1467296
Log:
Renamed MarshallerPool.release(...) as recycle(...) since its purpose is not to release resources.
The old name was misleading since developers put the 'recycle' method in a try ... finally
block,
while we should not.

Modified:
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XML.java
    sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/xml/MarshallerPoolTest.java

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java?rev=1467296&r1=1467295&r2=1467296&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java [UTF-8]
(original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java [UTF-8]
Fri Apr 12 14:52:56 2013
@@ -41,7 +41,7 @@ import org.apache.sis.internal.jaxb.Adap
  * {@preformat java
  *     Marshaller marshaller = pool.acquireMarshaller();
  *     marshaller.marchall(...);
- *     pool.release(marshaller);
+ *     pool.recycle(marshaller);
  * }
  *
  * {@section Configuring (un)marshallers}
@@ -101,7 +101,7 @@ public class MarshallerPool {
      * synchronized block.</p>
      *
      * @see #acquireMarshaller()
-     * @see #release(Marshaller)
+     * @see #recycle(Marshaller)
      */
     private final Deque<Marshaller> marshallers;
 
@@ -114,7 +114,7 @@ public class MarshallerPool {
      * synchronized block.</p>
      *
      * @see #acquireUnmarshaller()
-     * @see #release(Unmarshaller)
+     * @see #recycle(Unmarshaller)
      */
     private final Deque<Unmarshaller> unmarshallers;
 
@@ -237,13 +237,13 @@ public class MarshallerPool {
      *   <li>Registers a delayed task for disposing expired (un)marshallers after the
timeout.</li>
      * </ul>
      */
-    private <T> void release(final Deque<T> queue, final T marshaller) {
+    private <T> void recycle(final Deque<T> queue, final T marshaller) {
         try {
             ((Pooled) marshaller).reset();
         } catch (JAXBException exception) {
             // Not expected to happen because we are supposed
             // to reset the properties to their initial values.
-            Logging.unexpectedException(MarshallerPool.class, "release", exception);
+            Logging.unexpectedException(MarshallerPool.class, "recycle", exception);
             return;
         }
         queue.push(marshaller);
@@ -325,12 +325,11 @@ public class MarshallerPool {
      * {@preformat java
      *     Marshaller marshaller = pool.acquireMarshaller();
      *     marshaller.marchall(...);
-     *     pool.release(marshaller);
+     *     pool.recycle(marshaller);
      * }
      *
-     * Note that this is not strictly required to release the marshaller in a {@code finally}
-     * block. Actually it is safer to let the garbage collector disposes the marshaller if
an
-     * error occurred while marshalling the object.
+     * Note that {@link #recycle(Marshaller)} shall not be invoked in case of exception,
+     * since the marshaller may be in an invalid state.
      *
      * @return A marshaller configured for formatting OGC/ISO XML.
      * @throws JAXBException If an error occurred while creating and configuring a marshaller.
@@ -352,12 +351,11 @@ public class MarshallerPool {
      * {@preformat java
      *     Unmarshaller unmarshaller = pool.acquireUnmarshaller();
      *     Unmarshaller.unmarchall(...);
-     *     pool.release(unmarshaller);
+     *     pool.recycle(unmarshaller);
      * }
      *
-     * Note that this is not strictly required to release the unmarshaller in a {@code finally}
-     * block. Actually it is safer to let the garbage collector disposes the unmarshaller
if an
-     * error occurred while unmarshalling the object.
+     * Note that {@link #recycle(Unmarshaller)} shall not be invoked in case of exception,
+     * since the unmarshaller may be in an invalid state.
      *
      * @return A unmarshaller configured for parsing OGC/ISO XML.
      * @throws JAXBException If an error occurred while creating and configuring the unmarshaller.
@@ -371,23 +369,31 @@ public class MarshallerPool {
     }
 
     /**
-     * Declares a marshaller as available for reuse. The caller should not use
-     * anymore the marshaller after this method call.
+     * Declares a marshaller as available for reuse.
+     * The caller should not use anymore the given marshaller after this method call.
+     *
+     * <p>Do not invoke this method if the marshaller threw an exception, since the
+     * marshaller may be in an invalid state. In particular, this method should not
+     * be invoked in a {@code finally} block.</p>
      *
      * @param marshaller The marshaller to return to the pool.
      */
-    public void release(final Marshaller marshaller) {
-        release(marshallers, marshaller);
+    public void recycle(final Marshaller marshaller) {
+        recycle(marshallers, marshaller);
     }
 
     /**
-     * Declares a unmarshaller as available for reuse. The caller should not use
-     * anymore the unmarshaller after this method call.
+     * Declares a unmarshaller as available for reuse.
+     * The caller should not use anymore the given unmarshaller after this method call.
+     *
+     * <p>Do not invoke this method if the marshaller threw an exception, since the
+     * marshaller may be in an invalid state. In particular, this method should not
+     * be invoked in a {@code finally} block.</p>
      *
      * @param unmarshaller The unmarshaller to return to the pool.
      */
-    public void release(final Unmarshaller unmarshaller) {
-        release(unmarshallers, unmarshaller);
+    public void recycle(final Unmarshaller unmarshaller) {
+        recycle(unmarshallers, unmarshaller);
     }
 
     /**

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XML.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XML.java?rev=1467296&r1=1467295&r2=1467296&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XML.java [UTF-8] (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/XML.java [UTF-8] Fri Apr
12 14:52:56 2013
@@ -147,7 +147,7 @@ public final class XML extends Static {
      *     Unmarshaller um = marshallerPool.acquireUnmarshaller();
      *     um.setProperty(XML.RESOLVER, myResolver);
      *     Object obj = um.unmarshal(xml);
-     *     marshallerPool.release(um);
+     *     marshallerPool.recycle(um);
      * }
      *
      * @see Unmarshaller#setProperty(String, Object)
@@ -195,7 +195,7 @@ public final class XML extends Static {
      *     Unmarshaller um = marshallerPool.acquireUnmarshaller();
      *     um.setProperty(XML.CONVERTER, myWarningList);
      *     Object obj = um.unmarshal(xml);
-     *     marshallerPool.release(um);
+     *     marshallerPool.recycle(um);
      *     if (!myWarningList.isEmpty()) {
      *         // Report here the warnings to the user.
      *     }
@@ -298,7 +298,7 @@ public final class XML extends Static {
         final MarshallerPool pool = getPool();
         final Marshaller marshaller = pool.acquireMarshaller();
         marshaller.marshal(object, output);
-        pool.release(marshaller);
+        pool.recycle(marshaller);
         return output.toString();
     }
 
@@ -313,7 +313,7 @@ public final class XML extends Static {
         final MarshallerPool pool = getPool();
         final Marshaller marshaller = pool.acquireMarshaller();
         marshaller.marshal(object, output);
-        pool.release(marshaller);
+        pool.recycle(marshaller);
     }
 
     /**
@@ -327,7 +327,7 @@ public final class XML extends Static {
         final MarshallerPool pool = getPool();
         final Marshaller marshaller = pool.acquireMarshaller();
         marshaller.marshal(object, output);
-        pool.release(marshaller);
+        pool.recycle(marshaller);
     }
 
     /**
@@ -342,7 +342,7 @@ public final class XML extends Static {
         final MarshallerPool pool = getPool();
         final Unmarshaller unmarshaller = pool.acquireUnmarshaller();
         final Object object = unmarshaller.unmarshal(in);
-        pool.release(unmarshaller);
+        pool.recycle(unmarshaller);
         return object;
     }
 
@@ -357,7 +357,7 @@ public final class XML extends Static {
         final MarshallerPool pool = getPool();
         final Unmarshaller unmarshaller = pool.acquireUnmarshaller();
         final Object object = unmarshaller.unmarshal(input);
-        pool.release(unmarshaller);
+        pool.recycle(unmarshaller);
         return object;
     }
 
@@ -372,7 +372,7 @@ public final class XML extends Static {
         final MarshallerPool pool = getPool();
         final Unmarshaller unmarshaller = pool.acquireUnmarshaller();
         final Object object = unmarshaller.unmarshal(input);
-        pool.release(unmarshaller);
+        pool.recycle(unmarshaller);
         return object;
     }
 }

Modified: sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/xml/MarshallerPoolTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/xml/MarshallerPoolTest.java?rev=1467296&r1=1467295&r2=1467296&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/xml/MarshallerPoolTest.java
[UTF-8] (original)
+++ sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/xml/MarshallerPoolTest.java
[UTF-8] Fri Apr 12 14:52:56 2013
@@ -57,13 +57,13 @@ public final strictfp class MarshallerPo
         /*
          * MarshallerPool should reset the properties to their initial state.
          */
-        pool.release(marshaller);
+        pool.recycle(marshaller);
         assertSame(marshaller, pool.acquireMarshaller());
         /*
          * Following should be null, but has been replaced by "" under the hood
          * for avoiding a NullPointerException in current JAXB implementation.
          */
         assertEquals("", marshaller.getProperty("com.sun.xml.bind.xmlHeaders"));
-        pool.release(marshaller);
+        pool.recycle(marshaller);
     }
 }



Mime
View raw message