EndPoint (Jetty :: Project 9.2.10.v20150310 API)

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`	`upgrade(Connection newConnection)` Upgrade connections.
`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(), upgrade(Connection)
  - 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()
  - upgrade
```
void upgrade(Connection newConnection)
```
    Upgrade connections. Close the old connection, update the endpoint and open the new connection. If the oldConnection is an instance of Connection.UpgradeFrom then a prefilled buffer is requested and passed to the newConnection if it is an instance of Connection.UpgradeTo
    
    Parameters:
    newConnection - The connection to upgrade to

Interface EndPoint

Asynchronous Methods

Blocking Read

Dispatched Read

Blocking Write

Dispatched Write

Method Summary

Method Detail

getLocalAddress

getRemoteAddress

isOpen

getCreatedTimeStamp

shutdownOutput

isOutputShutdown

isInputShutdown

close

fill

flush

getTransport

getIdleTimeout

setIdleTimeout

fillInterested

write

getConnection

setConnection

onOpen

onClose

upgrade