org.microbean.jersey.netty

Class AbstractChannelOutboundInvokingOutputStream<T>

java.lang.Object

java.io.OutputStream

org.microbean.jersey.netty.AbstractChannelOutboundInvokingOutputStream<T>

Type Parameters:

T - the type of message that will be written; see createMessage(byte[], int, int)

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

Direct Known Subclasses:

AbstractByteBufBackedChannelOutboundInvokingOutputStream

public abstract class AbstractChannelOutboundInvokingOutputStream<T>
extends OutputStream

An OutputStream that delegates writing and flushing operations to a ChannelOutboundInvoker.

Thread Safety

Instances of this class are safe for concurrent use by multiple threads.

Author:

Laird Nelson

See Also:

ChannelOutboundInvoker

Field Summary

Fields

Modifier and Type	Field and Description
protected ChannelOutboundInvoker	channelOutboundInvoker The ChannelOutboundInvoker underlying this AbstractChannelOutboundInvokingOutputStream implementation to which most operations are adapted.
protected boolean	closeChannelOutboundInvoker Indicates whether the ChannelOutboundInvoker should also be closed when close() is called.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker channelOutboundInvoker) Creates a new AbstractChannelOutboundInvokingOutputStream that does not automatically flush and that does not ever close the supplied ChannelOutboundInvoker.
protected	AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker channelOutboundInvoker, boolean closeChannelOutboundInvoker) Creates a new AbstractChannelOutboundInvokingOutputStream that does not automatically flush.
protected	AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker channelOutboundInvoker, int flushThreshold, boolean closeChannelOutboundInvoker) Creates a new AbstractChannelOutboundInvokingOutputStream.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this AbstractChannelOutboundInvokingOutputStream, optionally writing and flushing a final message, or simply just flushing first, before possibly closing the underlying ChannelOutboundInvoker.
protected T	createLastMessage() Returns a new, possibly null, message that should be written when close() is invoked.
protected abstract T	createMessage(byte[] bytes, int offset, int length) Returns a new message representing a portion (or all) of the supplied byte array that will be written by this AbstractChannelOutboundInvokingOutputStream's various write methods.
protected T	createMessage(int singleByte) Returns a new message representing the single supplied byte to be written by this AbstractChannelOutboundInvokingOutputStream's various write methods.
void	flush() Calls the ChannelOutboundInvoker.flush() method on the ChannelOutboundInvoker supplied at construction time.
int	getFlushThreshold() Returns the minimum number of bytes that this AbstractChannelOutboundInvokingOutputStream implementation has to write before an automatic flush will take place.
protected ChannelPromise	newPromise() Creates and returns new ChannelPromises that will be used in many ChannelOutboundInvoker operations.
void	write(byte[] bytes)
void	write(byte[] bytes, int offset, int length)
void	write(int singleByte)

Methods inherited from class java.lang.Object

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

Field Detail

channelOutboundInvoker

protected final ChannelOutboundInvoker channelOutboundInvoker

The ChannelOutboundInvoker underlying this AbstractChannelOutboundInvokingOutputStream implementation to which most operations are adapted.

See Also:

ChannelOutboundInvoker, AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean)

closeChannelOutboundInvoker

protected final boolean closeChannelOutboundInvoker

Indicates whether the ChannelOutboundInvoker should also be closed when close() is called.

See Also:

AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean)

Constructor Detail

AbstractChannelOutboundInvokingOutputStream

protected AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker channelOutboundInvoker)

Creates a new AbstractChannelOutboundInvokingOutputStream that does not automatically flush and that does not ever close the supplied ChannelOutboundInvoker.

Parameters:

channelOutboundInvoker - the ChannelOutboundInvoker to which operations are adapted; must not be null

Throws:

NullPointerException - if channelOutboundInvoker is null

See Also:

AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean), ChannelOutboundInvoker

AbstractChannelOutboundInvokingOutputStream

protected AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker channelOutboundInvoker,
                                                      boolean closeChannelOutboundInvoker)

Creates a new AbstractChannelOutboundInvokingOutputStream that does not automatically flush.

Parameters:

channelOutboundInvoker - the ChannelOutboundInvoker to which operations are adapted; must not be null

closeChannelOutboundInvoker - whether ChannelOutboundInvoker.close(ChannelPromise) will be called on the supplied ChannelOutboundInvoker when close() is called

Throws:

NullPointerException - if channelOutboundInvoker is null

See Also:

AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean), ChannelOutboundInvoker, close()

AbstractChannelOutboundInvokingOutputStream

protected AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker channelOutboundInvoker,
                                                      int flushThreshold,
                                                      boolean closeChannelOutboundInvoker)

Creates a new AbstractChannelOutboundInvokingOutputStream.

Parameters:

channelOutboundInvoker - the ChannelOutboundInvoker to which operations are adapted; must not be null

flushThreshold - the minimum number of bytes that this instance has to write before an automatic flush will take place; if less than 0 0 will be used instead; if Integer#MAX_VALUE then no automatic flushing will occur

closeChannelOutboundInvoker - whether ChannelOutboundInvoker.close(ChannelPromise) will be called on the supplied ChannelOutboundInvoker when close() is called

Throws:

NullPointerException - if channelOutboundInvoker is null

See Also:

ChannelOutboundInvoker, getFlushThreshold(), close()

Method Detail

getFlushThreshold

public final int getFlushThreshold()

Returns the minimum number of bytes that this AbstractChannelOutboundInvokingOutputStream implementation has to write before an automatic flush will take place.

This method will always return 0 or a positive int.

If this method returns 0, then a call to flush() will be made at some point after every write(byte[], int, int) invocation.

If this method returns Integer.MAX_VALUE, then no automatic flushing will occur.

Returns:

the minimum number of bytes that this AbstractChannelOutboundInvokingOutputStream implementation has to write before an automatic flush will take place; always 0 or a positive int

See Also:

AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean), ChannelOutboundInvoker.flush()

write

public final void write(int singleByte)
                 throws IOException

Specified by:

write in class OutputStream

Throws:

IOException

write

public final void write(byte[] bytes)
                 throws IOException

Overrides:

write in class OutputStream

Throws:

IOException

write

public final void write(byte[] bytes,
                        int offset,
                        int length)
                 throws IOException

Overrides:

write in class OutputStream

Throws:

IOException

createMessage

protected T createMessage(int singleByte)
                   throws IOException

Returns a new message representing the single supplied byte to be written by this AbstractChannelOutboundInvokingOutputStream's various write methods.

This method never returns null.

Overrides of this method must not return null.

Note: The default implementation of this method is inefficient: it creates a new byte[] holding the sole byte represented by the singleByte parameter value and calls createMessage(byte[], int, int) and returns its result. Subclasses are encouraged, but not required, to override this method to be more efficient.

Overrides of this method should be stateless.

Parameters:

singleByte - an int whose low-order bits hold a byte to be written

Returns:

a new, non-null message to write

Throws:

IOException - if an error occurs

See Also:

createMessage(byte[], int, int), ChannelOutboundInvoker.write(Object, ChannelPromise)

createMessage

protected abstract T createMessage(byte[] bytes,
                                   int offset,
                                   int length)
                            throws IOException

Returns a new message representing a portion (or all) of the supplied byte array that will be written by this AbstractChannelOutboundInvokingOutputStream's various write methods.

Implementations of this method must not return null.

Implementations of this method should be stateless.

Parameters:

bytes - a byte array originating from, e.g., a write(byte[], int, int) method invocation; will never be null

offset - the (validated) offset within the supplied byte array from which to start reading; will always be 0 or a positive int less than length

length - the (validated) length of the portion to read; will always be 0 or a positive int less than or equal to the length of the supplied byte array

Returns:

a new, non-null message to write

Throws:

NullPointerException - if bytes is null

IndexOutOfBoundsException - if offset is negative, or length is negative, or offset + length is greater than the length of bytes

IOException - if an error occurs during the actual creation of the message

See Also:

write(byte[], int, int), OutputStream.write(byte[], int, int), ChannelOutboundInvoker.write(Object, ChannelPromise)

createLastMessage

protected T createLastMessage()
                       throws IOException

Returns a new, possibly null, message that should be written when close() is invoked.

This method and its overrides may return null to indicate that no such write is required.

The default implementation of this method returns null.

Overrides of this method should be stateless.

Returns:

a final message to write when close() is called, or null if no final message needs to be written

Throws:

IOException - if an error occurs

See Also:

close()

newPromise

protected ChannelPromise newPromise()

Creates and returns new ChannelPromises that will be used in many ChannelOutboundInvoker operations.

This method never returns null.

Overrides of this method must not return null.

The default implementation of this method returns the return value of invoking ChannelOutboundInvoker.newPromise().

Returns:

a new, non-null ChannelPromise that will be supplied to many ChannelOutboundInvoker operations

See Also:

ChannelPromise, ChannelOutboundInvoker.newPromise(), ChannelOutboundInvoker.voidPromise()

flush

public final void flush()

Calls the ChannelOutboundInvoker.flush() method on the ChannelOutboundInvoker supplied at construction time.

Specified by:

flush in interface Flushable

Overrides:

flush in class OutputStream

See Also:

ChannelOutboundInvoker.flush(), getFlushThreshold(), AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean)

close

public final void close()
                 throws IOException

Closes this AbstractChannelOutboundInvokingOutputStream, optionally writing and flushing a final message, or simply just flushing first, before possibly closing the underlying ChannelOutboundInvoker.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class OutputStream

Throws:

IOException - if the createLastMessage() method throws an IOException

See Also:

createLastMessage(), ChannelOutboundInvoker.close(ChannelPromise), AbstractChannelOutboundInvokingOutputStream(ChannelOutboundInvoker, int, boolean)