org.microbean.jersey.netty

Class TerminableByteBufInputStream

java.lang.Object

java.io.InputStream

org.microbean.jersey.netty.TerminableByteBufInputStream

All Implemented Interfaces:

Closeable, AutoCloseable

public final class TerminableByteBufInputStream
extends InputStream

An InputStream implementation that reads from a CompositeByteBuf whose contents are updated via the addByteBuf(ByteBuf) method.

This class is designed to bridge the gap between a Netty I/O-focused event loop and a thread where Jersey will be reading content. Reads must block on the Jersey thread, but must not impact the Netty event loop. Instances of this class are used by AbstractContainerRequestDecoder implementations, when they need to supply an InputStream to Jersey so that Jersey can read any incoming entity payloads.

The AbstractContainerRequestDecoder implementation will typically call addByteBuf(ByteBuf) on the Netty event loop, and then will call terminate() when it is done. Meanwhile, Jersey may call the read(byte[], int, int) method on its own thread, and such a call may block at any point until Netty supplies more content.

Author:

Laird Nelson

See Also:

addByteBuf(ByteBuf), CompositeByteBuf, AbstractContainerRequestDecoder.createTerminableByteBufInputStream(ByteBufAllocator)

Constructor Summary

Constructors

Constructor and Description
TerminableByteBufInputStream(ByteBufAllocator byteBufAllocator) Creates a new TerminableByteBufInputStream.

Method Summary

Modifier and Type	Method and Description
void	addByteBuf(ByteBuf byteBuf) Adds content for this TerminableByteBufInputStream to read.
int	available() Returns an estimate of the number of bytes that may be read without blocking.
void	close() Closes this TerminableByteBufInputStream and releases its underlying CompositeByteBuf.
int	read() Reads a single byte from this TerminableByteBufInputStream.
int	read(byte[] targetBytes) Calls the read(byte[], int, int) method with the supplied targetBytes array, 0 and targetBytes.length as arguments and returns its result.
int	read(byte[] targetByteArray, int offset, int length) Attempts to read the desired number of bytes as indicated by the supplied length parameter into the supplied targetByte array, beginning the write at the element in the supplied targetByteArray designated by the offset parameter, and returns the actual number of bytes read, or -1 if no bytes were read and the end of the stream was reached, in which case terminate() must have been called in the past.
void	terminate() Irrevocably disables the addByteBuf(ByteBuf) method such that calling it will result in an IllegalStateException being thrown.

Methods inherited from class java.io.InputStream

mark, markSupported, reset, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

TerminableByteBufInputStream

public TerminableByteBufInputStream(ByteBufAllocator byteBufAllocator)

Creates a new TerminableByteBufInputStream.

Parameters:

byteBufAllocator - a ByteBufAllocator that will allocate a new CompositeByteBuf from which content may be read by another thread; must not be null

Throws:

NullPointerException - if byteBufAllocator is null

See Also:

addByteBuf(ByteBuf), read(byte[], int, int)

Method Detail

close

public final void close()
                 throws IOException

Closes this TerminableByteBufInputStream and releases its underlying CompositeByteBuf.

If this method has been called previously, no further action is taken.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class InputStream

Throws:

IOException - if an error occurs

terminate

public final void terminate()

Irrevocably disables the addByteBuf(ByteBuf) method such that calling it will result in an IllegalStateException being thrown.

If this method has been called before, or if close() has been called before, no action is taken.

See Also:

addByteBuf(ByteBuf), close()

available

public final int available()
                    throws IOException

Returns an estimate of the number of bytes that may be read without blocking.

Overrides:

available in class InputStream

Returns:

an estimate of the number of bytes that may be read without blocking; always 0 or a positive int

Throws:

IOException - if this TerminableByteBufInputStream has been closed

See Also:

close()

read

public final int read()
               throws IOException

Reads a single byte from this TerminableByteBufInputStream.

Specified by:

read in class InputStream

Returns:

the byte read, or -1 if the end of the stream has been reached (for this to happen terminate() must have already been called at some point in the past)

Throws:

IOException - if this TerminableByteBufInputStream has been closed

See Also:

terminate(), close()

read

public final int read(byte[] targetBytes)
               throws IOException

Calls the read(byte[], int, int) method with the supplied targetBytes array, 0 and targetBytes.length as arguments and returns its result.

Overrides:

read in class InputStream

Parameters:

targetBytes - the byte array into which read bytes will be written, beginning at index 0; must not be null

Returns:

the number of bytes actually read, or -1 if the end of the stream has been reached, in which case terminate() must have been called in the past

Throws:

NullPointerException - if targetBytes is null

IOException - if this TerminableByteBufInputStream has been closed

See Also:

read(byte[], int, int), terminate(), close(), addByteBuf(ByteBuf)

read

public final int read(byte[] targetByteArray,
                      int offset,
                      int length)
               throws IOException

Attempts to read the desired number of bytes as indicated by the supplied length parameter into the supplied targetByte array, beginning the write at the element in the supplied targetByteArray designated by the offset parameter, and returns the actual number of bytes read, or -1 if no bytes were read and the end of the stream was reached, in which case terminate() must have been called in the past.

Content to read is supplied by means of the addByteBuf(ByteBuf) method.

Overrides:

read in class InputStream

Parameters:

targetByteArray - an array of bytes to which read bytes will be written, beginning at the element identified by the supplied offset; must not be null

offset - the zero-based index of the element within the supplied targetByteArray that will hold the first byte read; must be 0 or greater and less than the length property of the supplied targetByteArray

length - the number of bytes to read; must be zero or greater and must be less than or equal to the length property of the supplied targetByteArray minus the supplied (valid) offset

Returns:

the number of bytes actually read, or -1 if the end of the stream has been reached, in which case terminate() must have been called in the past

Throws:

NullPointerException - if targetByteArray is null

IndexOutOfBoundsException - if offset is less than 0, or if length is less than 0, or if length is greater than the length property of the supplied targetByteArray parameter minus the supplied offset

IOException - if this TerminableByteBufInputStream has been closed

See Also:

terminate(), close(), addByteBuf(ByteBuf)

addByteBuf

public final void addByteBuf(ByteBuf byteBuf)

Adds content for this TerminableByteBufInputStream to read.

Parameters:

byteBuf - a ByteBuf; must not be null and must be (initially) readable

Throws:

NullPointerException - if byteBuf is null

IllegalArgumentException - if byteBuf is not readable

IllegalStateException - if this TerminableByteBufInputStream is closed or terminated

See Also:

terminate(), close(), read(byte[], int, int)