Package edu.umd.cs.piccolo.util

Class PObjectOutputStream

java.lang.Object
java.io.OutputStream
java.io.ObjectOutputStream
edu.umd.cs.piccolo.util.PObjectOutputStream
All Implemented Interfaces:
Closeable, DataOutput, Flushable, ObjectOutput, ObjectStreamConstants, AutoCloseable
public class PObjectOutputStream extends ObjectOutputStream
PObjectOutputStream is an extension of ObjectOutputStream to handle optional elements. This is similar to the concept of Java's "weak references", but applied to object serialization rather than garbage collection. Here, PObjectOutputStream provides a method, writeConditionalObject, which only serializes the specified object to the stream if there is a strong reference (if it has been written somewhere else using writeObject()) to that object elsewhere in the stream.

To discover strong references to objects, PObjectOutputStream uses a two-phase writing process. First, a "discovery" phase is used to find out what objects are about to be serialized. This works by effectively serializing the object graph to /dev/null, recording which objects are unconditionally written using the standard writeObject method. Then, in the second "write" phase, ObjectOutputStream actually serializes the data to the output stream. During this phase, calls to writeConditionalObject() will only write the specified object if the object was found to be serialized during the discovery stage. If the object was not recorded during the discovery stage, a an optional null (the default) is unconditionally written in place of the object. To skip writting out the null use writeConditionalObject(object, false)

By careful implementation of readObject and writeObject methods, streams serialized using PObjectOutputStream can be deserialized using the standard ObjectInputStream.

Version:
1.0
Author:
Jon Meyer, Jesse Grosjean

  • Constructor Details

    • PObjectOutputStream

      public PObjectOutputStream(OutputStream out) throws IOException
      Constructs a PObjectOutputStream that wraps the provided OutputStream.
      Parameters:
      out - underlying outputstream that will receive the serialized objects
      Throws:
      IOException - when underlying subsystem throws one

  • Method Details

    • toByteArray

      public static byte[] toByteArray(Object object) throws IOException
      Transform the given object into an array of bytes.
      Parameters:
      object - the object to be transformed
      Returns:
      array of bytes representing the given object
      Throws:
      IOException - when serialization system throws one

    • writeObjectTree

      public void writeObjectTree(Object object) throws IOException
      Writes the provided object to the underlying stream like an ordination ObjectOutputStream except that it does not record duplicates at all.
      Parameters:
      object - object to be serialized
      Throws:
      IOException - when underlying subsystem throws one

    • writeConditionalObject

      public void writeConditionalObject(Object object) throws IOException
      Writes the given object, but only if it was not in the object tree multiple times.
      Parameters:
      object - object to write to the stream.
      Throws:
      IOException - when underlying subsystem throws one

    • reset

      public void reset() throws IOException
      Resets the ObjectOutputStream clearing any memory about objects already being written while it's at it.
      Overrides:
      reset in class ObjectOutputStream
      Throws:
      IOException - when underlying subsystem throws one

    • recordUnconditionallyWritten

      protected void recordUnconditionallyWritten(Object aRoot) throws IOException
      Performs a scan of objects that can be serialized once.
      Parameters:
      aRoot - Object from which to start the scan
      Throws:
      IOException - when serialization fails