org.eclipse.jetty.io

Interface EndPoint

All Superinterfaces:

AutoCloseable, Closeable

All Known Subinterfaces:

SelectorManager.SelectableEndPoint

All Known Implementing Classes:

AbstractEndPoint, ByteArrayEndPoint, ChannelEndPoint, LocalConnector.LocalEndPoint, NetworkTrafficSelectChannelEndPoint, SelectChannelEndPoint, SslConnection.DecryptedEndPoint

public interface EndPoint
extends Closeable

A transport EndPoint

Asynchronous Methods

The asynchronous scheduling methods of EndPoint has been influenced by NIO.2 Futures and Completion handlers, but does not use those actual interfaces because they have some inefficiencies.

This class will frequently be used in conjunction with some of the utility implementations of Callback, such as FutureCallback and ExecutorCallback. Examples are:

Blocking Read

A FutureCallback can be used to block until an endpoint is ready to be filled from:

 FutureCallback<String> future = new FutureCallback<>();
 endpoint.fillInterested("ContextObj",future);
 ...
 String context = future.get(); // This blocks
 int filled=endpoint.fill(mybuffer);
 

Dispatched Read

By using a different callback, the read can be done asynchronously in its own dispatched thread:

 endpoint.fillInterested("ContextObj",new ExecutorCallback<String>(executor)
 {
   public void onCompleted(String context)
   {
     int filled=endpoint.fill(mybuffer);
     ...
   }
   public void onFailed(String context,Throwable cause) {...}
 });
 

The executor callback can also be customized to not dispatch in some circumstances when it knows it can use the callback thread and does not need to dispatch.

Blocking Write

The write contract is that the callback complete is not called until all data has been written or there is a failure. For blocking this looks like:

 FutureCallback<String> future = new FutureCallback<>();
 endpoint.write("ContextObj",future,headerBuffer,contentBuffer);
 String context = future.get(); // This blocks
 

Dispatched Write

Note also that multiple buffers may be passed in write so that gather writes can be done:

 endpoint.write("ContextObj",new ExecutorCallback<String>(executor)
 {
   public void onCompleted(String context)
   {
     int filled=endpoint.fill(mybuffer);
     ...
   }
   public void onFailed(String context,Throwable cause) {...}
 },headerBuffer,contentBuffer);
 

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Close any backing stream associated with the endpoint
int	fill(ByteBuffer buffer) Fill the passed buffer with data from this endpoint.
void	fillInterested(Callback callback) Requests callback methods to be invoked when a call to fill(ByteBuffer) would return data or EOF.
boolean	flush(ByteBuffer... buffer) Flush data from the passed header/buffer to this endpoint.
Connection	getConnection()
long	getCreatedTimeStamp()
long	getIdleTimeout() Get the max idle time in ms.
InetSocketAddress	getLocalAddress()
InetSocketAddress	getRemoteAddress()
Object	getTransport()
boolean	isInputShutdown() Test if the input is shutdown.
boolean	isOpen()
boolean	isOutputShutdown() Test if output is shutdown.
void	onClose() Callback method invoked when this EndPoint is close.
void	onOpen() Callback method invoked when this EndPoint is opened.
void	setConnection(Connection connection)
void	setIdleTimeout(long idleTimeout) Set the idle timeout.
void	shutdownOutput() Shutdown the output.
void	write(Callback callback, ByteBuffer... buffers) Writes the given buffers via flush(ByteBuffer...) and invokes callback methods when either all the data has been flushed or an error occurs.

Method Detail

getLocalAddress

InetSocketAddress getLocalAddress()

Returns:

The local Inet address to which this EndPoint is bound, or null if this EndPoint does not represent a network connection.

getRemoteAddress

InetSocketAddress getRemoteAddress()

Returns:

The remote Inet address to which this EndPoint is bound, or null if this EndPoint does not represent a network connection.

isOpen

boolean isOpen()

getCreatedTimeStamp

long getCreatedTimeStamp()

shutdownOutput

void shutdownOutput()

Shutdown the output.

This call indicates that no more data will be sent on this endpoint that that the remote end should read an EOF once all previously sent data has been consumed. Shutdown may be done either at the TCP/IP level, as a protocol exchange (Eg TLS close handshake) or both.

If the endpoint has isInputShutdown() true, then this call has the same effect as close().

isOutputShutdown

boolean isOutputShutdown()

Test if output is shutdown. The output is shutdown by a call to shutdownOutput() or close().

Returns:

true if the output is shutdown or the endpoint is closed.

isInputShutdown

boolean isInputShutdown()

Test if the input is shutdown. The input is shutdown if an EOF has been read while doing a fill(ByteBuffer). Once the input is shutdown, all calls to fill(ByteBuffer) will return -1, until such time as the end point is close, when they will return EofException.

Returns:

True if the input is shutdown or the endpoint is closed.

close

void close()

Close any backing stream associated with the endpoint

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

fill

int fill(ByteBuffer buffer)
         throws IOException

Fill the passed buffer with data from this endpoint. The bytes are appended to any data already in the buffer by writing from the buffers limit up to it's capacity. The limit is updated to include the filled bytes.

Parameters:

buffer - The buffer to fill. The position and limit are modified during the fill. After the operation, the position is unchanged and the limit is increased to reflect the new data filled.

Returns:

an int value indicating the number of bytes filled or -1 if EOF is read or the input is shutdown.

Throws:

EofException - If the endpoint is closed.

IOException

flush

boolean flush(ByteBuffer... buffer)
              throws IOException

Flush data from the passed header/buffer to this endpoint. As many bytes as can be consumed are taken from the header/buffer position up until the buffer limit. The header/buffers position is updated to indicate how many bytes have been consumed.

Returns:

True IFF all the buffers have been consumed and the endpoint has flushed the data to its destination (ie is not buffering any data).

Throws:

EofException - If the endpoint is closed or output is shutdown.

IOException

getTransport

Object getTransport()

Returns:

The underlying transport object (socket, channel, etc.)

getIdleTimeout

long getIdleTimeout()

Get the max idle time in ms.

The max idle time is the time the endpoint can be idle before extraordinary handling takes place.

Returns:

the max idle time in ms or if ms <= 0 implies an infinite timeout

setIdleTimeout

void setIdleTimeout(long idleTimeout)

Set the idle timeout.

Parameters:

idleTimeout - the idle timeout in MS. Timeout <= 0 implies an infinite timeout

fillInterested

void fillInterested(Callback callback)
                    throws ReadPendingException

Requests callback methods to be invoked when a call to fill(ByteBuffer) would return data or EOF.

Parameters:

callback - the callback to call when an error occurs or we are readable.

Throws:

ReadPendingException - if another read operation is concurrent.

write

void write(Callback callback,
         ByteBuffer... buffers)
           throws WritePendingException

Writes the given buffers via flush(ByteBuffer...) and invokes callback methods when either all the data has been flushed or an error occurs.

Parameters:

callback - the callback to call when an error occurs or the write completed.

buffers - one or more ByteBuffers that will be flushed.

Throws:

WritePendingException - if another write operation is concurrent.

getConnection

Connection getConnection()

Returns:

the Connection associated with this EndPoint

See Also:

setConnection(Connection)

setConnection

void setConnection(Connection connection)

Parameters:

connection - the Connection associated with this EndPoint

See Also:

getConnection()

onOpen

void onOpen()

Callback method invoked when this EndPoint is opened.

See Also:

onClose()

onClose

void onClose()

Callback method invoked when this EndPoint is close.

See Also:

onOpen()