com.healthmarketscience.rmiio
Interface RemoteInputStream

All Superinterfaces:

Remote

All Known Implementing Classes:

DirectRemoteInputStream, GZIPRemoteInputStream, RemoteInputStreamClientProxy, RemoteInputStreamServer, RemoteInputStreamWrapper, SimpleRemoteInputStream

public interface RemoteInputStream
extends Remote

Remote interface which allows exporting an InputStream-like interface over the network. When combined with the RemoteInputStreamServer subclasses on the server side and the RemoteInputStreamClient on the client side, this class provides a true remote InputStream (in other words, should never be used alone, use the utility classes).

Note that all methods on this interface are idempotent (when used correctly), and can therefore be retried as necessary in the face of RemoteExceptions.

An actual instance of this class is not intended for use by more than one client, and should be treated in a similar manner to an "un-synchronized" local interface.

Author:

James Ahlborn

Method Summary

int	available() Returns the number of bytes that can be read from this stream without blocking.
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.

Method Detail

usingGZIPCompression

boolean usingGZIPCompression()
                             throws IOException,
                                    RemoteException

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

Returns:

true iff the stream data is compressed, false otherwise

Throws:

IOException

RemoteException

available

int available()
              throws IOException,
                     RemoteException

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.

Returns:

the number of bytes that can be read without blocking

Throws:

IOException

RemoteException

close

void close(boolean readSuccess)
           throws IOException,
                  RemoteException

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.

Parameters:

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

Throws:

IOException

RemoteException

readPacket

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

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).

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

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

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).

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