Author: ggregory
Date: Fri Apr 6 20:57:05 2012
New Revision: 1310584
URL: http://svn.apache.org/viewvc?rev=1310584&view=rev
Log:
Add comments for [LANG-798] Use generics in SerializationUtils.
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/SerializationUtils.java
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/SerializationUtils.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/SerializationUtils.java?rev=1310584&r1=1310583&r2=1310584&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/SerializationUtils.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/SerializationUtils.java
Fri Apr 6 20:57:05 2012
@@ -167,24 +167,36 @@ public class SerializationUtils {
// Deserialize
//-----------------------------------------------------------------------
/**
- * <p>Deserializes an {@code Object} from the specified stream.</p>
- *
- * <p>The stream will be closed once the object is written. This
- * avoids the need for a finally clause, and maybe also exception
- * handling, in the application code.</p>
- *
- * <p>The stream passed in is not buffered internally within this method.
- * This is the responsibility of your application if desired.</p>
- *
- * @param inputStream the serialized object input stream, must not be null
+ * <p>
+ * Deserializes an {@code Object} from the specified stream.
+ * </p>
+ *
+ * <p>
+ * The stream will be closed once the object is written. This avoids the
need for a finally clause, and maybe also
+ * exception handling, in the application code.
+ * </p>
+ *
+ * <p>
+ * The stream passed in is not buffered internally within this method.
This is the responsibility of your
+ * application if desired.
+ * </p>
+ *
+ * <p>
+ * If the call site incorrectly types the return value, a {@link
ClassCastException} is thrown from the call site.
+ * Without Generics in this declaration, the call site must type cast and
can cause the same ClassCastException.
+ * Note that in both cases, the ClassCastException is in the call site,
not in this method.
+ * </p>
+ *
+ * @param inputStream
+ * the serialized object input stream, must not be null
* @return the deserialized object
- * @throws IllegalArgumentException if {@code inputStream} is {@code null}
- * @throws SerializationException (runtime) if the serialization fails
+ * @throws IllegalArgumentException
+ * if {@code inputStream} is {@code null}
+ * @throws SerializationException
+ * (runtime) if the serialization fails
*/
@SuppressWarnings("unchecked")
// Don't warn about "(T) deserialize" because we want the avoid type
casting call sites.
- // If the call site incorrectly types the return value, a
ClassCastException is thrown.
- // Without Generics in this declaration, the call site must type cast and
can cause the same ClassCastException.
public static <T> T deserialize(InputStream inputStream) {
if (inputStream == null) {
throw new IllegalArgumentException("The InputStream must not be
null");
@@ -211,17 +223,26 @@ public class SerializationUtils {
}
/**
- * <p>Deserializes a single {@code Object} from an array of bytes.</p>
- *
- * @param objectData the serialized object, must not be null
+ * <p>
+ * Deserializes a single {@code Object} from an array of bytes.
+ * </p>
+ *
+ * <p>
+ * If the call site incorrectly types the return value, a {@link
ClassCastException} is thrown from the call site.
+ * Without Generics in this declaration, the call site must type cast and
can cause the same ClassCastException.
+ * Note that in both cases, the ClassCastException is in the call site,
not in this method.
+ * </p>
+ *
+ * @param objectData
+ * the serialized object, must not be null
* @return the deserialized object
- * @throws IllegalArgumentException if {@code objectData} is {@code null}
- * @throws SerializationException (runtime) if the serialization fails
+ * @throws IllegalArgumentException
+ * if {@code objectData} is {@code null}
+ * @throws SerializationException
+ * (runtime) if the serialization fails
*/
@SuppressWarnings("unchecked")
// Don't warn about "(T) deserialize" because we want the avoid type
casting call sites.
- // If the call site incorrectly types the return value, a
ClassCastException is thrown.
- // Without Generics in this declaration, the call site must type cast and
can cause the same ClassCastException.
public static <T> T deserialize(byte[] objectData) {
if (objectData == null) {
throw new IllegalArgumentException("The byte[] must not be null");
