com.healthmarketscience.rmiio
Class RemoteInputStreamServer

java.lang.Object
  com.healthmarketscience.rmiio.RemoteStreamServer<RemoteInputStreamServer,RemoteInputStream>
      com.healthmarketscience.rmiio.RemoteInputStreamServer

All Implemented Interfaces:

RemoteInputStream, Closeable, Serializable, Remote, Unreferenced

Direct Known Subclasses:

GZIPRemoteInputStream, SimpleRemoteInputStream

public abstract class RemoteInputStreamServer
extends RemoteStreamServer<RemoteInputStreamServer,RemoteInputStream>
implements RemoteInputStream

Server implementation base class for a RemoteInputStream. Handles the retry logic (the sequence ids) and the RemoteStreamMonitor updates for the server. Subclasses must implement the actual data handling methods.

Author:

James Ahlborn

See Also:

RemoteStreamServer.writeReplace(), Serialized Form

Field Summary

protected int	_chunkSize the target chunk size for data packets sent over the wire
protected InputStream	_in the real input stream from which we are reading data
static int	DEFAULT_CHUNK_SIZE default chunk size for shuffling data over the wire.
static RemoteStreamMonitor<RemoteInputStreamServer>	DUMMY_MONITOR Default monitor for operations done by RemoteInputStreamServer which does nothing.

Fields inherited from class com.healthmarketscience.rmiio.RemoteStreamServer

_monitor, INITIAL_INVALID_SEQUENCE_ID, INITIAL_VALID_SEQUENCE_ID, LOG

Constructor Summary

protected	RemoteInputStreamServer(InputStream in)
protected	RemoteInputStreamServer(InputStream in, RemoteStreamMonitor<RemoteInputStreamServer> monitor)
	RemoteInputStreamServer(InputStream in, RemoteStreamMonitor<RemoteInputStreamServer> monitor, int chunkSize)

Method Summary

int	available() Returns the number of bytes that can be read from this stream without blocking.
protected abstract int	availableImpl() 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.
protected void	closeImpl(boolean readSuccess) Closes (possibly flushes) the underlying streams and cleans up any resources.
protected RemoteInputStreamServer	getAsSub() Returns a handle to this object as a subclass instance.
InputStream	getInputStream() Returns the real InputStream from which this stream is reading data
protected Object	getLock() Returns a handle to the object used to lock the underlying stream operations for this remote stream.
Class<RemoteInputStream>	getRemoteClass()
protected abstract byte[]	readPacket() Reads the next packet of approximately _chunkSize from the underlying stream and returns it.
byte[]	readPacket(int packetId) Reads the next chunk of data for this stream.
protected abstract long	skip(long n) Skips at most the given amount of bytes in the underlying stream and returns the actual number of bytes skipped.
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.

Methods inherited from class com.healthmarketscience.rmiio.RemoteStreamServer

abort, checkAborted, close, export, exported, finish, isClosed, unreferenced, writeReplace

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.healthmarketscience.rmiio.RemoteInputStream

usingGZIPCompression

Field Detail

DEFAULT_CHUNK_SIZE

public static final int DEFAULT_CHUNK_SIZE

default chunk size for shuffling data over the wire.

See Also:

Constant Field Values

DUMMY_MONITOR

public static final RemoteStreamMonitor<RemoteInputStreamServer> DUMMY_MONITOR

Default monitor for operations done by RemoteInputStreamServer which does nothing.

_in

protected final transient InputStream _in

the real input stream from which we are reading data

_chunkSize

protected final transient int _chunkSize

the target chunk size for data packets sent over the wire

Constructor Detail

RemoteInputStreamServer

protected RemoteInputStreamServer(InputStream in)

RemoteInputStreamServer

protected RemoteInputStreamServer(InputStream in,
                                  RemoteStreamMonitor<RemoteInputStreamServer> monitor)

RemoteInputStreamServer

public RemoteInputStreamServer(InputStream in,
                               RemoteStreamMonitor<RemoteInputStreamServer> monitor,
                               int chunkSize)

Parameters:

in - the real input stream from which the data will be read

monitor - monitor for tracking the progress of the stream usage

chunkSize - target value for the byte size of the packets of data sent over the wire. note that this is a suggestion, actual package sizes may vary.

Method Detail

getInputStream

public InputStream getInputStream()

Returns the real InputStream from which this stream is reading data

getLock

protected final Object getLock()

Description copied from class: RemoteStreamServer

Returns a handle to the object used to lock the underlying stream operations for this remote stream.

Specified by:

getLock in class RemoteStreamServer<RemoteInputStreamServer,RemoteInputStream>

getAsSub

protected RemoteInputStreamServer getAsSub()

Description copied from class: RemoteStreamServer

Returns a handle to this object as a subclass instance.

Specified by:

getAsSub in class RemoteStreamServer<RemoteInputStreamServer,RemoteInputStream>

getRemoteClass

public Class<RemoteInputStream> getRemoteClass()

Specified by:

getRemoteClass in class RemoteStreamServer<RemoteInputStreamServer,RemoteInputStream>

Returns:

the class of the remote stream interface for this server

closeImpl

protected void closeImpl(boolean readSuccess)
                  throws IOException

Description copied from class: RemoteStreamServer

Closes (possibly flushes) the underlying streams and cleans up any resources. Called by the finish() method.

Specified by:

closeImpl in class RemoteStreamServer<RemoteInputStreamServer,RemoteInputStream>

Parameters:

readSuccess - true iff all data was successfully transferred, false otherwise

Throws:

IOException

close

public final void close(boolean readSuccess)
                 throws IOException

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

available

public final int available()
                    throws IOException

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

readPacket

public final byte[] readPacket(int packetId)
                        throws IOException

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

skip

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

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

availableImpl

protected abstract int availableImpl()
                              throws IOException

Returns the number of bytes that can be read from this stream without blocking.

Returns:

the number of bytes that can be read without blocking

Throws:

IOException

readPacket

protected abstract byte[] readPacket()
                              throws IOException

Reads the next packet of approximately _chunkSize from the underlying stream and returns it. If this stream is using compression, this packet should contain compressed data.

Returns:

the next packet of data for this stream

Throws:

IOException

skip

protected abstract long skip(long n)
                      throws IOException

Skips at most the given amount of bytes in the underlying stream and returns the actual number of bytes skipped.

Returns:

the actual number of bytes skipped

Throws:

IOException