org.restlet.engine.http.connector

## Class Connection<T extends Connector>

- java.lang.Object
- - org.restlet.engine.http.connector.Connection<T>

Type Parameters:
  `T` - The parent connector type.

All Implemented Interfaces:
  Notifiable

Direct Known Subclasses:
  ClientConnection, ServerConnection

    public abstract class Connection<T extends Connector>
    extends java.lang.Object
    implements Notifiable

A network connection though which requests and responses are exchanged by connectors.

Author:
  Jerome Louvel

### Constructor Summary

Constructors
Constructor and Description
`Connection(BaseHelper<T> helper, java.net.Socket socket, java.nio.channels.SocketChannel socketChannel)` Constructor.

### Method Summary

Methods
`protected void` `addEntityHeaders(Representation entity, Series<Parameter> headers)` Adds the entity headers for the given response.
`protected void` `addGeneralHeaders(Message message, Series<Parameter> headers)` Adds the general headers from the `Message` to the `Series`.
`boolean` `canRead()` Indicates if the connection's socket can be read for inbound data.
`boolean` `canWrite()` Indicates if the connection's socket can be written for outbound data.
`void` `close()` Closes the connection.
`Representation` `createInboundEntity(Series<Parameter> headers)` Returns the inbound message entity if available.
`java.lang.String` `getAddress()` Returns the socket IP address.
`BaseHelper<T>` `getHelper()` Returns the parent connector helper.
`java.nio.channels.ReadableByteChannel` `getInboundEntityChannel(long size, boolean chunked)` Returns the inbound message entity channel if it exists.
`java.io.InputStream` `getInboundEntityStream(long size, boolean chunked)` Returns the inbound message entity stream if it exists.
`java.util.Queue<Response>` `getInboundMessages()` Returns the queue of inbound messages.
`java.io.InputStream` `getInboundStream()` Returns the inbound stream.
`java.util.logging.Logger` `getLogger()` Returns the logger.
`java.nio.channels.WritableByteChannel` `getOutboundEntityChannel(boolean chunked)` Returns the response channel if it exists.
`java.io.OutputStream` `getOutboundEntityStream(boolean chunked)` Returns the response entity stream if it exists.
`java.util.Queue<Response>` `getOutboundMessages()` Returns the queue of outbound messages.
`java.io.OutputStream` `getOutboundStream()` Returns the outbound stream.
`int` `getPort()` Returns the socket port.
`protected Representation` `getRepresentation(java.io.InputStream stream)` Returns the representation wrapping the given stream.
`protected Representation` `getRepresentation(java.nio.channels.ReadableByteChannel channel)` Returns the representation wrapping the given channel.
`java.net.Socket` `getSocket()` Returns the underlying socket.
`java.nio.channels.SocketChannel` `getSocketChannel()` Returns the underlying NIO socket channel.
`java.lang.String` `getSslCipherSuite()` Returns the SSL cipher suite.
`java.util.List<java.security.cert.Certificate>` `getSslClientCertificates()` Returns the list of client SSL certificates.
`java.lang.Integer` `getSslKeySize()` Returns the SSL key size, if available and accessible.
`ConnectionState` `getState()` Returns the state of the connection.
`boolean` `isBusy()` Indicates if the connection is busy.
`boolean` `isClientSide()` Indicates if it is a client-side connection.
`boolean` `isInboundBusy()` Indicates if the input of the socket is busy.
`boolean` `isOutboundBusy()` Indicates if the output of the socket is busy.
`boolean` `isPersistent()` Indicates if the connection should be persisted across calls.
`boolean` `isPipelining()` Indicates if idempotent sequences of requests can be pipelined.
`boolean` `isServerSide()` Indicates if it is a server-side connection.
`void` `onEndReached()` Set the inbound busy state to false.
`void` `onError()` Set the inbound busy state to false and the connection state to `ConnectionState.CLOSING`.
`void` `open()` Opens the connection.
`protected abstract void` `readMessage()` Reads the next message received via the inbound stream or channel.
`void` `readMessages()` Reads inbound messages from the socket.
`void` `setInboundBusy(boolean inboundBusy)` Indicates if the input of the socket is busy.
`void` `setOutboundBusy(boolean outboundBusy)` Indicates if the output of the socket is busy.
`void` `setPersistent(boolean persistent)` Indicates if the connection should be persisted across calls.
`void` `setPipelining(boolean pipelining)` Indicates if idempotent sequences of requests can be pipelined.
`void` `setState(ConnectionState state)` Sets the state of the connection.
`protected boolean` `shouldBeChunked(Representation entity)` Indicates if the entity should be chunked because its length is unknown.
`protected abstract void` `writeMessage(Response message)` Write the given message on the socket.
`protected void` `writeMessage(Response message, Series<Parameter> headers)` Writes the message and its headers.
`protected void` `writeMessageBody(Representation entity, java.nio.channels.WritableByteChannel entityChannel, java.io.OutputStream entityStream)` Effectively writes the message body.
`protected void` `writeMessageHead(Response message, java.io.OutputStream headStream, Series<Parameter> headers)` Writes the message head to the given output stream.
`protected void` `writeMessageHead(Response message, Series<Parameter> headers)` Writes the message head.
`protected abstract void` `writeMessageHeadLine(Response message, java.io.OutputStream headStream)` Writes the message head line to the given output stream.
`void` `writeMessages()` Writes outbound messages to the socket.

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### Connection

    public Connection(BaseHelper<T> helper,
              java.net.Socket socket,
              java.nio.channels.SocketChannel socketChannel)
               throws java.io.IOException

Constructor.

Parameters:
  `helper` - The parent connector helper.
  `socket` - The underlying BIO socket.
  `socketChannel` - The underlying NIO socket channel.
Throws:
  `java.io.IOException`

### Method Detail

#### addEntityHeaders

    protected void addEntityHeaders(Representation entity,
                        Series<Parameter> headers)

Adds the entity headers for the given response.

Parameters:
  `entity` - The entity to inspect.

#### addGeneralHeaders

    protected void addGeneralHeaders(Message message,
                         Series<Parameter> headers)

Adds the general headers from the `Message` to the `Series`.

Parameters:
  `message` - The source `Message`.
  `headers` - The target headers `Series`.

#### canRead

    public boolean canRead()

Indicates if the connection's socket can be read for inbound data.

Returns:
  True if the connection's socket can be read for inbound data.
Throws:
  `java.io.IOException`

#### canWrite

    public boolean canWrite()

Indicates if the connection's socket can be written for outbound data.

Returns:
  True if the connection's socket can be written for outbound data.
Throws:
  `java.io.IOException`

#### close

    public void close()

Closes the connection. By default, set the state to `ConnectionState.CLOSED`.

#### createInboundEntity

    public Representation createInboundEntity(Series<Parameter> headers)

Returns the inbound message entity if available.

Parameters:
  `headers` - The headers to use.
Returns:
  The inbound message if available.

#### getAddress

    public java.lang.String getAddress()

Returns the socket IP address.

Returns:
  The socket IP address.

#### getHelper

    public BaseHelper<T> getHelper()

Returns the parent connector helper.

Returns:
  The parent connector helper.

#### getInboundEntityChannel

    public java.nio.channels.ReadableByteChannel getInboundEntityChannel(long size,
                                                                boolean chunked)

Returns the inbound message entity channel if it exists.

Parameters:
  `size` - The expected entity size or -1 if unknown.
Returns:
  The inbound message entity channel if it exists.

#### getInboundEntityStream

    public java.io.InputStream getInboundEntityStream(long size,
                                             boolean chunked)

Returns the inbound message entity stream if it exists.

Parameters:
  `size` - The expected entity size or -1 if unknown.
Returns:
  The inbound message entity stream if it exists.

#### getInboundMessages

    public java.util.Queue<Response> getInboundMessages()

Returns the queue of inbound messages.

Returns:
  The queue of inbound messages.

#### getInboundStream

    public java.io.InputStream getInboundStream()

Returns the inbound stream.

Returns:
  The inbound stream.

#### getLogger

    public java.util.logging.Logger getLogger()

Returns the logger.

Returns:
  The logger.

#### getOutboundEntityChannel

    public java.nio.channels.WritableByteChannel getOutboundEntityChannel(boolean chunked)

Returns the response channel if it exists.

Returns:
  The response channel if it exists.

#### getOutboundEntityStream

    public java.io.OutputStream getOutboundEntityStream(boolean chunked)

Returns the response entity stream if it exists.

Returns:
  The response entity stream if it exists.

#### getOutboundMessages

    public java.util.Queue<Response> getOutboundMessages()

Returns the queue of outbound messages.

Returns:
  The queue of outbound messages.

#### getOutboundStream

    public java.io.OutputStream getOutboundStream()

Returns the outbound stream.

Returns:
  The outbound stream.

#### getPort

    public int getPort()

Returns the socket port.

Returns:
  The socket port.

#### getRepresentation

    protected Representation getRepresentation(java.io.InputStream stream)

Returns the representation wrapping the given stream.

Parameters:
  `stream` - The response input stream.
Returns:
  The wrapping representation.

#### getRepresentation

    protected Representation getRepresentation(java.nio.channels.ReadableByteChannel channel)

Returns the representation wrapping the given channel.

Parameters:
  `channel` - The response channel.
Returns:
  The wrapping representation.

#### getSocket

    public java.net.Socket getSocket()

Returns the underlying socket.

Returns:
  The underlying socket.

#### getSocketChannel

    public java.nio.channels.SocketChannel getSocketChannel()

Returns the underlying NIO socket channel.

Returns:
  The underlying NIO socket channel.

#### getSslCipherSuite

    public java.lang.String getSslCipherSuite()

Returns the SSL cipher suite.

Returns:
  The SSL cipher suite.

#### getSslClientCertificates

    public java.util.List<java.security.cert.Certificate> getSslClientCertificates()

Returns the list of client SSL certificates.

Returns:
  The list of client SSL certificates.

#### getSslKeySize

    public java.lang.Integer getSslKeySize()

Returns the SSL key size, if available and accessible.

Returns:
  The SSL key size, if available and accessible.

#### getState

    public ConnectionState getState()

Returns the state of the connection.

Returns:
  The state of the connection.

#### isBusy

    public boolean isBusy()

Indicates if the connection is busy.

Returns:
  True if the connection is busy.

#### isClientSide

    public boolean isClientSide()

Indicates if it is a client-side connection.

Returns:
  True if it is a client-side connection.

#### isInboundBusy

    public boolean isInboundBusy()

Indicates if the input of the socket is busy.

Returns:
  True if the input of the socket is busy.

#### isOutboundBusy

    public boolean isOutboundBusy()

Indicates if the output of the socket is busy.

Returns:
  True if the output of the socket is busy.

#### isPersistent

    public boolean isPersistent()

Indicates if the connection should be persisted across calls.

Returns:
  True if the connection should be persisted across calls.

#### isPipelining

    public boolean isPipelining()

Indicates if idempotent sequences of requests can be pipelined.

Returns:
  True requests pipelining is enabled.

#### isServerSide

    public boolean isServerSide()

Indicates if it is a server-side connection.

Returns:
  True if it is a server-side connection.

#### onEndReached

    public void onEndReached()

Set the inbound busy state to false.

Specified by:
  `onEndReached` in interface `Notifiable`

#### onError

    public void onError()

Set the inbound busy state to false and the connection state to `ConnectionState.CLOSING`.

Specified by:
  `onError` in interface `Notifiable`

#### open

    public void open()

Opens the connection. By default, set the state to `ConnectionState.OPEN`.

#### readMessage

    protected abstract void readMessage()
                                 throws java.io.IOException

Reads the next message received via the inbound stream or channel. Note that the optional entity is not fully read.

Throws:
  `java.io.IOException`

#### readMessages

    public void readMessages()

Reads inbound messages from the socket. Only one message at a time if pipelining isn't enabled.

#### setInboundBusy

    public void setInboundBusy(boolean inboundBusy)

Indicates if the input of the socket is busy.

Parameters:
  `inboundBusy` - True if the input of the socket is busy.

#### setOutboundBusy

    public void setOutboundBusy(boolean outboundBusy)

Indicates if the output of the socket is busy.

Parameters:
  `outboundBusy` - True if the output of the socket is busy.

#### setPersistent

    public void setPersistent(boolean persistent)

Indicates if the connection should be persisted across calls.

Parameters:
  `persistent` - True if the connection should be persisted across calls.

#### setPipelining

    public void setPipelining(boolean pipelining)

Indicates if idempotent sequences of requests can be pipelined.

Parameters:
  `pipelining` - True requests pipelining is enabled.

#### setState

    public void setState(ConnectionState state)

Sets the state of the connection.

Parameters:
  `state` - The state of the connection.

#### shouldBeChunked

    protected boolean shouldBeChunked(Representation entity)

Indicates if the entity should be chunked because its length is unknown.

Parameters:
  `entity` - The entity to analyze.
Returns:
  True if the entity should be chunked.

#### writeMessage

    protected abstract void writeMessage(Response message)

Write the given message on the socket.

Parameters:
  `message` - The message to write.

#### writeMessage

    protected void writeMessage(Response message,
                    Series<Parameter> headers)
                         throws java.io.IOException

Writes the message and its headers.

Parameters:
  `message` - The message to write.
Throws:
  `java.io.IOException` - if the Response could not be written to the network.

#### writeMessageBody

    protected void writeMessageBody(Representation entity,
                        java.nio.channels.WritableByteChannel entityChannel,
                        java.io.OutputStream entityStream)
                             throws java.io.IOException

Effectively writes the message body. The entity to write is guaranteed to be non null. Attempts to write the entity on the outbound channel or outbound stream by default.

Parameters:
  `entity` - The representation to write as entity of the body.
  `entityChannel` - The outbound entity channel or null if a stream is used.
  `entityStream` - The outbound entity stream or null if a channel is used.
Throws:
  `java.io.IOException`

#### writeMessageHead

    protected void writeMessageHead(Response message,
                        java.io.OutputStream headStream,
                        Series<Parameter> headers)
                             throws java.io.IOException

Writes the message head to the given output stream.

Parameters:
  `message` - The source message.
  `headStream` - The target stream.
Throws:
  `java.io.IOException`

#### writeMessageHead

    protected void writeMessageHead(Response message,
                        Series<Parameter> headers)
                             throws java.io.IOException

Writes the message head.

Parameters:
  `message` - The message.
  `headers` - The series of headers to write.
Throws:
  `java.io.IOException`

#### writeMessageHeadLine

    protected abstract void writeMessageHeadLine(Response message,
                            java.io.OutputStream headStream)
                                          throws java.io.IOException

Writes the message head line to the given output stream.

Parameters:
  `message` - The source message.
  `headStream` - The target stream.
Throws:
  `java.io.IOException`

#### writeMessages

    public void writeMessages()

Writes outbound messages to the socket. Only one response at a time if pipelining isn't enabled.