Module org.cojen.dirmi
Package org.cojen.dirmi

Interface Pipe

All Superinterfaces:
AutoCloseable, Closeable, DataInput, DataOutput, Flushable, Link, ObjectInput, ObjectOutput
public interface Pipe extends Closeable, Flushable, ObjectInput, ObjectOutput, Link
A pipe is a bidirectional stream which supports basic object serialization. Only simple types and collections can be serialized, and the original classes aren't necessarily preserved. Graph structure isn't preserved unless reference tracking is enabled.

Pipes are only partially thread-safe. Reading and writing is concurrent, but at most one thread can be reading, and at most one thread can be writing.

Pipes are fully buffered, and closing the pipe directly discards any buffered writes. Closing the OutputStream will attempt to flush the buffer first, although it can only be called from the thread which is allowed to perform writes. Closing either stream has the side effect of also fully closing the pipe.

Here's an example remote method declaration which uses a pipe: The remote method declaration requires the return type to be a pipe, and one parameter must also be a pipe. The client-side invocation of the remote method simply passes null for the pipe parameter, and the server-side implementation returns null instead of a pipe. Example client call: The remote method implementation might look like this: When using a pipe, writes must be explicitly flushed. When a client calls a piped method, the flush method must be called to ensure that the method name and parameters are actually sent to the remote endpoint. Care must be taken when recycling pipes. There must not be any pending input or unflushed output, and the pipe must not be used again directly. Closing the pipe is safer, although it might force a new pipe connection to be established.

Note: The pipe implementation isn't strictly compatible with DataInput and DataOutput. The contract for those interfaces specifies a modified UTF-8 encoding, but pipes adhere to the standard UTF-8 format. Also, floating point values are written in their "raw" form, preserving non-canonical NaN values.

  • Method Details

    • enableReferences

      void enableReferences()
      Enables tracking of object references as they are written, for correctly serializing object graphs, and to potentially reduce the overall encoding size. This mode has higher memory overhead because each object flowing through the pipe must be remembered.

      This method counts the number of times it's invoked, and a matching number of calls to disableReferences() is required to fully disable the mode.

    • disableReferences

      boolean disableReferences()
      Disables tracking of object references. Memory isn't freed on the remote side until it reads another object.
      Returns:
      true if fully disabled
      Throws:
      IllegalStateException - if not currently enabled

    • inputStream

      InputStream inputStream()
      Returns the pipe's InputStream, which also implements ObjectInput. Closing the stream is equivalent to closing the pipe.

    • outputStream

      OutputStream outputStream()
      Returns the pipe's OutputStream, which also implements ObjectOutput. Closing the stream is equivalent to closing the pipe.

    • recycle

      void recycle() throws IOException
      Attempt to recycle the connection instead of closing it. The caller must ensure that the pipe has no pending input or unflushed output.
      Throws:
      IllegalStateException - if it's detected that the pipe isn't in a recyclable state
      IOException

    • readObject

      Object readObject() throws IOException
      Read and return an object. Unlike the inherited method, reading from a pipe never throws a ClassNotFoundException.
      Specified by:
      readObject in interface ObjectInput
      Throws:
      IOException

    • readThrowable

      Object readThrowable() throws IOException
      Read and return an object, and if it's a Throwable instance, a local stack trace is stitched in.
      Throws:
      IOException

    • writeObject

      void writeObject(Object obj) throws IOException
      Write an object (or null) to the pipe.
      Specified by:
      writeObject in interface ObjectOutput
      Throws:
      IOException

    • writeNull

      void writeNull() throws IOException
      Write a null object reference.
      Throws:
      IOException

    • transferTo

      long transferTo(OutputStream out, long n) throws IOException
      Reads up to n bytes from this pipe and writes them into the given stream. Fewer than n bytes are written if the pipe has no more input to read.
      Returns:
      the number of bytes transferred
      Throws:
      IOException