SerializationUtils (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3, class: SerializationUtils

Package org.apache.commons.lang3

# Class SerializationUtils

java.lang.Object
org.apache.commons.lang3.SerializationUtils

public class SerializationUtils extends Object
Assists with the serialization process and performs additional functionality based on serialization.

- Deep clone using serialization
- Serialize managing finally and IOException
- Deserialize managing finally and IOException

This class throws exceptions for invalid `null` inputs. Each method documents its behavior in more detail.

#ThreadSafe#

Since:
  1.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SerializationUtils()`
  Deprecated.
  TODO Make private in 4.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T extends Serializable>
  T`
  `clone(T object)`
  Deep clone an `Object` using serialization.
  `static <T> T`
  `deserialize(byte[] objectData)`
  Deserializes a single `Object` from an array of bytes.
  `static <T> T`
  `deserialize(InputStream inputStream)`
  Deserializes an `Object` from the specified stream.
  `static <T extends Serializable>
  T`
  `roundtrip(T obj)`
  Performs a serialization roundtrip.
  `static byte[]`
  `serialize(Serializable obj)`
  Serializes an `Object` to a byte array for storage/serialization.
  `static void`
  `serialize(Serializable obj, OutputStream outputStream)`
  Serializes an `Object` to the specified stream.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### SerializationUtils

    @Deprecated public SerializationUtils()
    Deprecated.
    TODO Make private in 4.0.
    SerializationUtils instances should NOT be constructed in standard programming. Instead, the class should be used as `SerializationUtils.clone(object)`.

    This constructor is public to permit tools that require a JavaBean instance to operate.

    Since:
      2.0

- ## Method Details

  - ### clone

    public static <T extends Serializable> T clone(T object)
    Deep clone an `Object` using serialization.

    This is many times slower than writing clone methods by hand on all objects in your object graph. However, for complex object graphs, or for those that don't support deep cloning this can be a simple alternative implementation. Of course all the objects must be `Serializable`.

    Type Parameters:
      `T` - the type of the object involved
    Parameters:
      `object` - the `Serializable` object to clone
    Returns:
      the cloned object
    Throws:
      `SerializationException` - (runtime) if the serialization fails

  - ### deserialize

    public static <T> T deserialize(byte[] objectData)
    Deserializes a single `Object` from an array of bytes.

    If the call site incorrectly types the return value, a `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.

    Type Parameters:
      `T` - the object type to be deserialized
    Parameters:
      `objectData` - the serialized object, must not be null
    Returns:
      the deserialized object
    Throws:
      `NullPointerException` - if `objectData` is `null`
      `SerializationException` - (runtime) if the serialization fails

  - ### deserialize

    public static <T> T deserialize(InputStream inputStream)
    Deserializes an `Object` from the specified stream.

    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.

    The stream passed in is not buffered internally within this method. This is the responsibility of your application if desired.

    If the call site incorrectly types the return value, a `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.

    Type Parameters:
      `T` - the object type to be deserialized
    Parameters:
      `inputStream` - the serialized object input stream, must not be null
    Returns:
      the deserialized object
    Throws:
      `NullPointerException` - if `inputStream` is `null`
      `SerializationException` - (runtime) if the serialization fails

  - ### roundtrip

    public static <T extends Serializable> T roundtrip(T obj)
    Performs a serialization roundtrip. Serializes and deserializes the given object, great for testing objects that implement `Serializable`.
    Type Parameters:
      `T` - the type of the object involved
    Parameters:
      `obj` - the object to roundtrip
    Returns:
      the serialized and deserialized object
    Since:
      3.3

  - ### serialize

    public static byte[] serialize(Serializable obj)
    Serializes an `Object` to a byte array for storage/serialization.
    Parameters:
      `obj` - the object to serialize to bytes
    Returns:
      a byte[] with the converted Serializable
    Throws:
      `SerializationException` - (runtime) if the serialization fails

  - ### serialize

    public static void serialize(Serializable obj, OutputStream outputStream)
    Serializes an `Object` to the specified stream.

    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.

    The stream passed in is not buffered internally within this method. This is the responsibility of your application if desired.

    Parameters:
      `obj` - the object to serialize to bytes, may be null
      `outputStream` - the stream to write to, must not be null
    Throws:
      `NullPointerException` - if `outputStream` is `null`
      `SerializationException` - (runtime) if the serialization fails