You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2013/04/12 16:52:56 UTC
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
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);
}
}