com.healthmarketscience.rmiio
Class DirectRemoteInputStream

java.lang.Object
  com.healthmarketscience.rmiio.DirectRemoteInputStream

All Implemented Interfaces:

RemoteInputStream, Closeable, Serializable, Remote

public class DirectRemoteInputStream
extends Object
implements RemoteInputStream, Closeable, Serializable

RemoteInputStream implementation which mimics the RemoteInputStream functionality while not actually causing any additional RMI invocations. This class is not recommended for general use, but may be useful (or even required) in certain scenarios. It basically works by writing the stream data directly into the ObjectOutputStream during serialization. There are a variety of implications to this approach, so please read the pros and cons list carefully before deciding to use this class.

• Pros:
• No extra RMI invocations are needed, so this implementation will not have problems with firewalls.
• Since this implementation is not an RMI server, no extra RMI related objects are instantiated (servers, stubs, etc.) and no export is needed.
• Cons:
• Send operations cannot be retried automatically. Once the underlying stream has begun serialization, it can no longer be reserialized. And, since potentially lots of data may be sent in one invocation, the chance of network failures is increased. All in all, this implementation is much more fragile in the face of network failures. Note, however, that the application layer may be able to manually handle retries if the underlying stream is "restartable", such as a stream based on a File.
• If the RPC implementation keeps the entire invocation in memory, you will have memory consumption problems again. This should not be a problem with vanilla RMI, which should write the data directly to an underlying socket.
• The server side process cannot start processing the data until the entire stream is sent (whereas with the other implementations, the data can be processed as it is received).
• The stream data is temporarily stored on the server's local filesystem. This can have any number of implications including slower performance, excess disk consumption, and/or exposure of sensitive data if temp file attributes are incorrect.
• This implementation is RMI specific, so it cannot be used with any non-RMI compatible RPC frameworks (e.g. CORBA).

Finally, the good news is that since this implementation is a RemoteInputStream, the client-side decision to use this class will not impact the server. If the need arises in the future, client code which uses this class may switch over to using one of the more robust RemoteInputStream implementations without any changes to the server.

Author:

James Ahlborn

See Also:

Serialized Form

Constructor Summary

DirectRemoteInputStream(InputStream in)

DirectRemoteInputStream(InputStream in, boolean compress)

DirectRemoteInputStream(InputStream in, boolean compress, RemoteStreamMonitor<RemoteInputStreamServer> monitor)

Method Summary

int	available() Returns the number of bytes that can be read from this stream without blocking.
void	close()
void	close(boolean readSuccess) Closes the input stream and releases the resources for this server object.
byte[]	readPacket(int packetId) Reads the next chunk of data for this stream.
long	skip(long n, int skipId) Skips and discards up to the given number of bytes in the stream, and returns the actual number of bytes skipped.
boolean	usingGZIPCompression() Returns true if the stream is using GZIP compression over the wire.

Methods inherited from class java.lang.Object

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

Constructor Detail

DirectRemoteInputStream

public DirectRemoteInputStream(InputStream in)

DirectRemoteInputStream

public DirectRemoteInputStream(InputStream in,
                               boolean compress)

DirectRemoteInputStream

public DirectRemoteInputStream(InputStream in,
                               boolean compress,
                               RemoteStreamMonitor<RemoteInputStreamServer> monitor)

Method Detail

usingGZIPCompression

public boolean usingGZIPCompression()
                             throws IOException,
                                    RemoteException

Description copied from interface: RemoteInputStream

Returns true if the stream is using GZIP compression over the wire.

Specified by:

usingGZIPCompression in interface RemoteInputStream

Returns:

true iff the stream data is compressed, false otherwise

Throws:

IOException

RemoteException

available

public int available()
              throws IOException,
                     RemoteException

Description copied from interface: RemoteInputStream

Returns the number of bytes that can be read from this stream without blocking. Note that this is an approximate number and should be treated as such.

Specified by:

available in interface RemoteInputStream

Returns:

the number of bytes that can be read without blocking

Throws:

IOException

RemoteException

close

public void close(boolean readSuccess)
           throws IOException,
                  RemoteException

Description copied from interface: RemoteInputStream

Closes the input stream and releases the resources for this server object. Note that the remote object may no longer be accessible after this call (depending on the implementation), so clients should not attempt to use this stream after making this call.

Specified by:

close in interface RemoteInputStream

Parameters:

readSuccess - true iff all data was read successfully by the client, false otherwise

Throws:

IOException

RemoteException

readPacket

public byte[] readPacket(int packetId)
                  throws IOException,
                         RemoteException

Description copied from interface: RemoteInputStream

Reads the next chunk of data for this stream. The amount of data returned is up to the underlying implementation. The given packetId parameter (if used correctly) allows this operation to be idempotent. This parameter must be a monotonically increasing, positive integer. If the client fails to receive a given packet, it may reattempt to retrieve the same packet by giving the same packetId as from the failed call. However, only the current packet may be reattempted (the client cannot attempt to retrieve any other previous packets). When requesting a new packet, the caller does not need to give a sequential id, just a greater one (hence the term monotonically increasing).

Specified by:

readPacket in interface RemoteInputStream

Parameters:

packetId - client specified id for this packet

Returns:

iff the packetId was the same one from the last read call, returns the last read chunk of data. Otherwise, reads and returns a new chunk of data.

Throws:

IOException

RemoteException

skip

public long skip(long n,
                 int skipId)
          throws IOException,
                 RemoteException

Description copied from interface: RemoteInputStream

Skips and discards up to the given number of bytes in the stream, and returns the actual number of bytes skipped. This method is not allowed to be called if using compression on the wire (because of the various layers of buffering). The given skipId parameter (if used correctly) allows this operation to be idempotent. This parameter must be a monotonically increasing, positive integer. If the client fails to receive the return from a skip call, it may reattempt the same skip call by giving the same skipId as from the failed call. However, only the current skip may be reattempted (the client cannot reattempt previous skips). When attempting a new skip call, the caller does not need to give a sequential id, just a greater one (hence the term monotonically increasing).

Specified by:

skip in interface RemoteInputStream

Parameters:

n - the number of bytes to skip

skipId - client specified id for this skip attempt

Returns:

iff the skipId was the same one from the last skip call, returns the result of the last skip call. Otherwise, skips up to the given number of bytes and returns the actual number of bytes skipped.

Throws:

IOException

RemoteException

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Throws:

IOException