org.apache.http.nio.reactor.ssl

## Class SSLIOSession

- java.lang.Object
- - org.apache.http.nio.reactor.ssl.SSLIOSession

- All Implemented Interfaces:
    IOSession, SessionBufferStatus, SocketAccessor
  Direct Known Subclasses:
    SSLIOSession

      @ThreadSafe
      public class SSLIOSession
      extends Object
      implements IOSession, SessionBufferStatus, SocketAccessor

  `SSLIOSession` is a decorator class intended to transparently extend an `IOSession` with transport layer security capabilities based on the SSL/TLS protocol.

  The resultant instance of `SSLIOSession` must be added to the original I/O session as an attribute with the `SESSION_KEY` key.

        SSLContext sslcontext = SSLContext.getInstance("SSL");
        sslcontext.init(null, null, null);
        SSLIOSession sslsession = new SSLIOSession(
            iosession, SSLMode.CLIENT, sslcontext, null);
        iosession.setAttribute(SSLIOSession.SESSION_KEY, sslsession);

  Since:
    4.2

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `SESSION_KEY` Name of the context attribute key, which can be used to obtain the SSL session.

    - ### Fields inherited from interface org.apache.http.nio.reactor.IOSession

      `ACTIVE, ATTACHMENT_KEY, CLOSED, CLOSING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SSLIOSession(IOSession session, SSLMode defaultMode, SSLContext sslContext, SSLSetupHandler handler)` Creates new instance of `SSLIOSession` class.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ByteChannel` | `channel()` Returns the underlying I/O channel associated with this session.
    `void` | `clearEvent(int op)` Clears interest in a particular I/O event type by updating the event mask associated with the session.
    `void` | `close()` Terminates the session gracefully and closes the underlying I/O channel.
    `Object` | `getAttribute(String name)` Returns the value of the attribute with the given name.
    `int` | `getEventMask()` Returns mask of I/O evens this session declared interest in.
    `SocketAddress` | `getLocalAddress()` Returns local address.
    `SocketAddress` | `getRemoteAddress()` Returns address of the remote peer.
    `Socket` | `getSocket()` Return the underlying socket
    `int` | `getSocketTimeout()` Returns value of the socket timeout in milliseconds.
    `SSLSession` | `getSSLSession()`
    `protected SSLSetupHandler` | `getSSLSetupHandler()`
    `int` | `getStatus()` Returns status of the session:
    `boolean` | `hasBufferedInput()` Determines if the input buffer associated with the session contains data.
    `boolean` | `hasBufferedOutput()` Determines if the output buffer associated with the session contains data.
    `void` | `inboundTransport()` Executes inbound SSL transport operations.
    `void` | `initialize()` Initializes the session in the default operation mode.
    `void` | `initialize(SSLMode mode)` Initializes the session in the given `SSLMode`.
    `boolean` | `isAppInputReady()` Reads encrypted data and returns whether the channel associated with this session has any decrypted inbound data available for reading.
    `boolean` | `isAppOutputReady()` Returns whether the channel associated with this session is ready to accept outbound unecrypted data for writing.
    `boolean` | `isClosed()` Determines if the session has been terminated.
    `boolean` | `isInboundDone()` Returns whether the session will produce any more inbound data.
    `boolean` | `isInitialized()` Returns `true` is the session has been fully initialized, `false` otherwise.
    `boolean` | `isOutboundDone()` Returns whether the session will accept any more outbound data.
    `void` | `outboundTransport()` Sends encrypted data and executes outbound SSL transport operations.
    `Object` | `removeAttribute(String name)` Removes attribute with the given name.
    `void` | `setAttribute(String name, Object obj)` This method can be used to associate a particular object with the session by the given attribute name.
    `void` | `setBufferStatus(SessionBufferStatus status)` Quite often I/O sessions need to maintain internal I/O buffers in order to transform input / output data prior to returning it to the consumer or writing it to the underlying channel.
    `void` | `setEvent(int op)` Declares interest in a particular I/O event type by updating the event mask associated with the session.
    `void` | `setEventMask(int ops)` Declares interest in I/O event notifications by setting the event mask associated with the session
    `void` | `setSocketTimeout(int timeout)` Sets value of the socket timeout in milliseconds.
    `void` | `shutdown()` Terminates the session by shutting down the underlying I/O channel.
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### SESSION_KEY

          public static final String SESSION_KEY

      Name of the context attribute key, which can be used to obtain the SSL session.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SSLIOSession

          public SSLIOSession(IOSession session,
                      SSLMode defaultMode,
                      SSLContext sslContext,
                      SSLSetupHandler handler)

      Creates new instance of `SSLIOSession` class.
      Parameters:
        `session` - I/O session to be decorated with the TLS/SSL capabilities.
        `defaultMode` - default mode (client or server)
        `sslContext` - SSL context to use for this I/O session.
        `handler` - optional SSL setup handler. May be `null`.

  - ### Method Detail

    - #### getSSLSetupHandler

          protected SSLSetupHandler getSSLSetupHandler()

    - #### isInitialized

          public boolean isInitialized()

      Returns `true` is the session has been fully initialized, `false` otherwise.

    - #### initialize

          public void initialize(SSLMode mode)
                          throws SSLException

      Initializes the session in the given `SSLMode`. This method invokes the `SSLSetupHandler.initalize(SSLEngine)` callback if an instance of `SSLSetupHandler` was specified at the construction time.
      Parameters:
        `mode` - mode of operation (client or server).
      Throws:
        `SSLException` - in case of a SSL protocol exception.
        `IllegalStateException` - if the session has already been initialized.

    - #### initialize

          public void initialize()
                          throws SSLException

      Initializes the session in the default operation mode. This method invokes the `SSLSetupHandler.initalize(SSLEngine)` callback if an instance of `SSLSetupHandler` was specified at the construction time.
      Throws:
        `SSLException` - in case of a SSL protocol exception.
        `IllegalStateException` - if the session has already been initialized.

    - #### getSSLSession

          public SSLSession getSSLSession()

    - #### isAppInputReady

          public boolean isAppInputReady()
                                  throws IOException

      Reads encrypted data and returns whether the channel associated with this session has any decrypted inbound data available for reading.
      Throws:
        `IOException` - in case of an I/O error.

    - #### isAppOutputReady

          public boolean isAppOutputReady()
                                   throws IOException

      Returns whether the channel associated with this session is ready to accept outbound unecrypted data for writing.
      Throws:
        `IOException` - - not thrown currently

    - #### inboundTransport

          public void inboundTransport()
                                throws IOException

      Executes inbound SSL transport operations.
      Throws:
        `IOException` - - not thrown currently

    - #### outboundTransport

          public void outboundTransport()
                                 throws IOException

      Sends encrypted data and executes outbound SSL transport operations.
      Throws:
        `IOException` - in case of an I/O error.

    - #### isInboundDone

          public boolean isInboundDone()

      Returns whether the session will produce any more inbound data.

    - #### isOutboundDone

          public boolean isOutboundDone()

      Returns whether the session will accept any more outbound data.

    - #### close

          public void close()

      Description copied from interface: `IOSession`
      Terminates the session gracefully and closes the underlying I/O channel. This method ensures that session termination handshake, such as the one used by the SSL/TLS protocol, is correctly carried out.
      Specified by:
        `close` in interface `IOSession`

    - #### shutdown

          public void shutdown()

      Description copied from interface: `IOSession`
      Terminates the session by shutting down the underlying I/O channel.
      Specified by:
        `shutdown` in interface `IOSession`

    - #### getStatus

          public int getStatus()

      Description copied from interface: `IOSession`
      Returns status of the session:

      `IOSession.ACTIVE`: session is active.

      `IOSession.CLOSING`: session is being closed.

      `IOSession.CLOSED`: session has been terminated.

      Specified by:
        `getStatus` in interface `IOSession`
      Returns:
        session status.

    - #### isClosed

          public boolean isClosed()

      Description copied from interface: `IOSession`
      Determines if the session has been terminated.
      Specified by:
        `isClosed` in interface `IOSession`
      Returns:
        `true` if the session has been terminated, `false` otherwise.

    - #### channel

          public ByteChannel channel()

      Description copied from interface: `IOSession`
      Returns the underlying I/O channel associated with this session.
      Specified by:
        `channel` in interface `IOSession`
      Returns:
        the I/O channel.

    - #### getLocalAddress

          public SocketAddress getLocalAddress()

      Description copied from interface: `IOSession`
      Returns local address.
      Specified by:
        `getLocalAddress` in interface `IOSession`
      Returns:
        socket address.

    - #### getRemoteAddress

          public SocketAddress getRemoteAddress()

      Description copied from interface: `IOSession`
      Returns address of the remote peer.
      Specified by:
        `getRemoteAddress` in interface `IOSession`
      Returns:
        socket address.

    - #### getEventMask

          public int getEventMask()

      Description copied from interface: `IOSession`
      Returns mask of I/O evens this session declared interest in.
      Specified by:
        `getEventMask` in interface `IOSession`
      Returns:
        I/O event mask.

    - #### setEventMask

          public void setEventMask(int ops)

      Description copied from interface: `IOSession`
      Declares interest in I/O event notifications by setting the event mask associated with the session
      Specified by:
        `setEventMask` in interface `IOSession`
      Parameters:
        `ops` - new I/O event mask.

    - #### setEvent

          public void setEvent(int op)

      Description copied from interface: `IOSession`
      Declares interest in a particular I/O event type by updating the event mask associated with the session.
      Specified by:
        `setEvent` in interface `IOSession`
      Parameters:
        `op` - I/O event type.

    - #### clearEvent

          public void clearEvent(int op)

      Description copied from interface: `IOSession`
      Clears interest in a particular I/O event type by updating the event mask associated with the session.
      Specified by:
        `clearEvent` in interface `IOSession`
      Parameters:
        `op` - I/O event type.

    - #### getSocketTimeout

          public int getSocketTimeout()

      Description copied from interface: `IOSession`
      Returns value of the socket timeout in milliseconds. The value of `0` signifies the session cannot time out.
      Specified by:
        `getSocketTimeout` in interface `IOSession`
      Returns:
        socket timeout.

    - #### setSocketTimeout

          public void setSocketTimeout(int timeout)

      Description copied from interface: `IOSession`
      Sets value of the socket timeout in milliseconds. The value of `0` signifies the session cannot time out.
      Specified by:
        `setSocketTimeout` in interface `IOSession`
      Parameters:
        `timeout` - socket timeout.

    - #### hasBufferedInput

          public boolean hasBufferedInput()

      Description copied from interface: `IOSession`
      Determines if the input buffer associated with the session contains data.
      Specified by:
        `hasBufferedInput` in interface `IOSession`
      Specified by:
        `hasBufferedInput` in interface `SessionBufferStatus`
      Returns:
        `true` if the session input buffer contains data, `false` otherwise.

    - #### hasBufferedOutput

          public boolean hasBufferedOutput()

      Description copied from interface: `IOSession`
      Determines if the output buffer associated with the session contains data.
      Specified by:
        `hasBufferedOutput` in interface `IOSession`
      Specified by:
        `hasBufferedOutput` in interface `SessionBufferStatus`
      Returns:
        `true` if the session output buffer contains data, `false` otherwise.

    - #### setBufferStatus

          public void setBufferStatus(SessionBufferStatus status)

      Description copied from interface: `IOSession`
      Quite often I/O sessions need to maintain internal I/O buffers in order to transform input / output data prior to returning it to the consumer or writing it to the underlying channel. Memory management in HttpCore NIO is based on the fundamental principle that the data consumer can read only as much input data as it can process without having to allocate more memory. That means, quite often some input data may remain unread in one of the internal or external session buffers. The I/O reactor can query the status of these session buffers, and make sure the consumer gets notified correctly as more data gets stored in one of the session buffers, thus allowing the consumer to read the remaining data once it is able to process it

      I/O sessions can be made aware of the status of external session buffers using the `SessionBufferStatus` interface.

      Specified by:
        `setBufferStatus` in interface `IOSession`

    - #### getAttribute

          public Object getAttribute(String name)

      Description copied from interface: `IOSession`
      Returns the value of the attribute with the given name. The value can be `null` if not set.

      The value of the session attachment object can be obtained using `IOSession.ATTACHMENT_KEY` name.

      Specified by:
        `getAttribute` in interface `IOSession`
      Parameters:
        `name` - name of the attribute.
      Returns:
        value of the attribute.
      See Also:
        `IOSession.setAttribute(String, Object)`

    - #### removeAttribute

          public Object removeAttribute(String name)

      Description copied from interface: `IOSession`
      Removes attribute with the given name.
      Specified by:
        `removeAttribute` in interface `IOSession`
      Parameters:
        `name` - name of the attribute to be removed.
      Returns:
        value of the removed attribute.
      See Also:
        `IOSession.setAttribute(String, Object)`

    - #### setAttribute

          public void setAttribute(String name,
                          Object obj)

      Description copied from interface: `IOSession`
      This method can be used to associate a particular object with the session by the given attribute name.

      I/O sessions are not bound to an execution thread, therefore one cannot use the context of the thread to store a session's state. All details about a particular session must be stored within the session itself.

      Specified by:
        `setAttribute` in interface `IOSession`
      Parameters:
        `name` - name of the attribute.
        `obj` - value of the attribute.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getSocket

          public Socket getSocket()

      Description copied from interface: `SocketAccessor`
      Return the underlying socket
      Specified by:
        `getSocket` in interface `SocketAccessor`
      Returns:
        - the underlying Socket, may be `null`.

Copyright © 2005–2013 The Apache Software Foundation. All rights reserved.