org.cojen.dirmi.io

Interface Channel

All Superinterfaces:

AutoCloseable, Closeable, Flushable, Link

All Known Subinterfaces:

InvocationChannel

public interface Channel
extends Flushable, Closeable, Link

Basic interface for a blocking bidirectional I/O channel.

Author:

Brian S O'Neill

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Channel.Listener
static interface	Channel.Recycler

Method Summary

Modifier and Type	Method and Description
void	close() Close channel, flushing any remaining output first.
void	disconnect() Forcibly close channel, potentially discarding unflushed output and any exceptions.
InputStream	getInputStream() Returns an input stream for the channel, which when closed, closes the channel.
OutputStream	getOutputStream() Returns an output stream for the channel, which when closed, closes the channel.
void	inputNotify(Channel.Listener listener) Register a listener which is asynchronously notified when a call to isInputReady will return true.
boolean	inputResume() Allows input to resume after reading a suspend marker.
Remote	installRecycler(Channel.Recycler recycler) Install a recycler which is called after this channel has been closed and a recyled channel has been created.
boolean	isClosed() Returns true if channel is absolutely closed or disconnected.
boolean	isInputReady() Returns true if bytes can read from channel without blocking.
boolean	isOutputReady() Returns true if bytes can written to channel without blocking.
boolean	isResumeSupported()
void	outputNotify(Channel.Listener listener) Register a listener which is asynchronously notified when a call to isOutputReady will return true.
boolean	outputSuspend() If supported, writes a suspend marker and flushes the output.
void	register(CloseableGroup<? super Channel> group) Register this channel with at least one group.
int	setInputBufferSize(int size) Sets the size of the input buffer, returning the actual size applied.
int	setOutputBufferSize(int size) Sets the size of the output buffer, returning the actual size applied.
void	setRecycleControl(Remote control) Set the recycling control object from the remote channel endpoint.
boolean	usesSelectNotification() Returns true to indicate that asynchronous notifications use channel selection instead of blocked threads.

Methods inherited from interface org.cojen.dirmi.Link

getLocalAddress, getRemoteAddress

Methods inherited from interface java.io.Flushable

flush

Method Detail

getInputStream

InputStream getInputStream()

Returns an input stream for the channel, which when closed, closes the channel. When a channel is closed, all read operations throw IOException.

getOutputStream

OutputStream getOutputStream()

Returns an output stream for the channel, which when closed, closes the channel. When a channel is closed, all write operations throw IOException.

isInputReady

boolean isInputReady()
              throws IOException

Returns true if bytes can read from channel without blocking.

Throws:

IOException - if channel is closed

isOutputReady

boolean isOutputReady()
               throws IOException

Returns true if bytes can written to channel without blocking.

Throws:

IOException - if channel is closed

setInputBufferSize

int setInputBufferSize(int size)

Sets the size of the input buffer, returning the actual size applied.

setOutputBufferSize

int setOutputBufferSize(int size)

Sets the size of the output buffer, returning the actual size applied.

inputNotify

void inputNotify(Channel.Listener listener)

Register a listener which is asynchronously notified when a call to isInputReady will return true. Listener is called at most once per registration.

outputNotify

void outputNotify(Channel.Listener listener)

Register a listener which is asynchronously notified when a call to isOutputReady will return true. Listener is called at most once per registration.

usesSelectNotification

boolean usesSelectNotification()

Returns true to indicate that asynchronous notifications use channel selection instead of blocked threads. For channels that aren't select-based, it can be more efficient to block on I/O streams directly rather than wait for notifications.

inputResume

boolean inputResume()

Allows input to resume after reading a suspend marker.

Returns:

false if not supported or if no suspend marker is present

isResumeSupported

boolean isResumeSupported()

outputSuspend

boolean outputSuspend()
               throws IOException

If supported, writes a suspend marker and flushes the output. Input side will read EOF until resumed. Input must be resumed for each suspend.

Returns:

false if not supported or stream is closed

Throws:

IOException

register

void register(CloseableGroup<? super Channel> group)

Register this channel with at least one group. When this channel is closed, it removes itself from all groups it has been registered with.

isClosed

boolean isClosed()

Returns true if channel is absolutely closed or disconnected. A return value of false doesn't imply that the next I/O operation will succeed.

close

void close()
    throws IOException

Close channel, flushing any remaining output first.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

disconnect

void disconnect()

Forcibly close channel, potentially discarding unflushed output and any exceptions.

installRecycler

Remote installRecycler(Channel.Recycler recycler)

Install a recycler which is called after this channel has been closed and a recyled channel has been created. Method returns an opaque remote object which allows remote channel endpoint to control this channel. Channels which don't use this feature return null.

Throws:

IllegalStateException - if a recycler is already installed

setRecycleControl

void setRecycleControl(Remote control)

Set the recycling control object from the remote channel endpoint. Method does nothing if channel doesn't use this feature.

Throws:

IllegalArgumentException - if channel uses control feature and instance is same as local control or is unsupported