org.apache.mina.api

## Interface IoSession

- All Known Implementing Classes:
    AbstractIoSession, AbstractNioSession, BioUdpSession, NioTcpSession, NioUdpSession

      public interface IoSession

  A handle which represents a connection between two end-points regardless of transport types.

  `IoSession` provides user-defined attributes. User-defined attributes are application-specific data which are associated with a session. It often contains objects that represents the state of a higher-level protocol and becomes a way to exchange data between filters and handlers.

  ### Adjusting Transport Type Specific Properties

  You can simply downcast the session to an appropriate subclass.

  ### Thread Safety

  `IoSession` is thread-safe. But please note that performing more than one `write(Object)` calls at the same time will cause the `IoFilter#filterWrite(IoFilter.NextFilter,IoSession,WriteRequest)` to be executed simultaneously, and therefore you have to make sure the `IoFilter` implementations you're using are thread-safe, too.
  Author:
    Apache MINA Project

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `IoSession.SessionState` State of a `IoSession`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static AttributeKey<SslHelper>` | `SSL_HELPER` The SslHelper instance name, stored in the session's attributes

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `changeState(IoSession.SessionState newState)` Changes the session's state from the current state to a new state.
    `IoFuture<Void>` | `close(boolean immediately)` Closes this session immediately or after all queued write requests are flushed.
    `WriteRequest` | `enqueueWriteRequest(WriteRequest writeRequest)` Internal method for enqueue write request after filter chain processing
    `<T> T` | `getAttribute(AttributeKey<T> key)` Returns the value of the user-defined attribute for the given `key`.If the there is no attribute with the specified key `null` will be returned.
    `<T> T` | `getAttribute(AttributeKey<T> key, T defaultValue)` Returns the value of the user-defined attribute for the given `key`.If the there is no attribute with the specified key the `defaultValue` will be returned.
    `Set<AttributeKey<?>>` | `getAttributeKeys()` Returns an unmodifiable `Set` of all Keys of this `IoSession`.
    `IoSessionConfig` | `getConfig()` Gets the session configuration, it where the idle timeout are set and other transport specific configuration.
    `long` | `getCreationTime()` The session's creation time.
    `long` | `getId()` The unique identifier of this session.
    `long` | `getLastIoTime()` Returns the time in millisecond when I/O occurred lastly (either read or write).
    `long` | `getLastReadTime()` Returns the time in millisecond when the last I/O read occurred.
    `long` | `getLastWriteTime()` Returns the time in millisecond when the last I/O write occurred.
    `SocketAddress` | `getLocalAddress()` Gets the local address of the local peer.
    `long` | `getReadBytes()` Gets the total number of bytes read for this session since it was created.
    `SocketAddress` | `getRemoteAddress()` Returns the socket address of remote peer.
    `IoService` | `getService()` Gets the service this session is attached to.
    `long` | `getWrittenBytes()` Gets the total number of bytes written for this session since it was created.
    `void` | `initSecure(SSLContext sslContext)` Initializes the SSL/TLS environment for this session.
    `boolean` | `isClosed()` Tells if the session is currently closed.
    `boolean` | `isClosing()` Tells if the session is being closed.
    `boolean` | `isConnected()` Tells if the session is currently connected and able to process incoming requests and to send outgoing responses.
    `boolean` | `isConnectedSecured()` Tells if the session is using SSL/TLS.
    `boolean` | `isCreated()` Tells if the session is created.
    `boolean` | `isReadSuspended()` Is read operation is suspended for this session.
    `boolean` | `isSecured()` Tells if the session is belonging to a secured connection.
    `boolean` | `isSecuring()` Tells if the session is processing a SSL/TLS handshake.
    `boolean` | `isWriteSuspended()` Is write operation is suspended for this session.
    `<T> T` | `removeAttribute(AttributeKey<T> key)` Removes the specified Attribute from this container.
    `void` | `resumeRead()` Resumes read operations for this session.
    `void` | `resumeWrite()` Resumes write operations for this session.
    `<T> T` | `setAttribute(AttributeKey<? extends T> key, T value)` Sets a user-defined attribute.
    `void` | `suspendRead()` Suspends read operations for this session.
    `void` | `suspendWrite()` Suspends write operations for this session.
    `void` | `write(Object message)` Enqueue a message for writing.
    `IoFuture<Void>` | `writeWithFuture(Object message)` Same as `write(Object)`, but provide a `IoFuture` for tracking the completion of this write.

- - ### Field Detail

    - #### SSL_HELPER

          static final AttributeKey<SslHelper> SSL_HELPER

      The SslHelper instance name, stored in the session's attributes

  - ### Method Detail

    - #### getId

          long getId()

      The unique identifier of this session.
      Returns:
        the session's unique identifier

    - #### getRemoteAddress

          SocketAddress getRemoteAddress()

      Returns the socket address of remote peer.
      Returns:
        the remote socket address

    - #### getLocalAddress

          SocketAddress getLocalAddress()

      Gets the local address of the local peer.
      Returns:
        the socket address of local machine which is associated with this session.

    - #### getService

          IoService getService()

      Gets the service this session is attached to.
      Returns:
        the `IoService` which provides `IoSession` to this session.

    - #### isClosed

          boolean isClosed()

      Tells if the session is currently closed.
      Returns:
        `true` if this session is disconnected with remote peer.

    - #### isClosing

          boolean isClosing()

      Tells if the session is being closed.
      Returns:
        `true` if this session is in the process of being closed.

    - #### isConnected

          boolean isConnected()

      Tells if the session is currently connected and able to process incoming requests and to send outgoing responses.
      Returns:
        `true` if this session is connected with remote peer.

    - #### isCreated

          boolean isCreated()

      Tells if the session is created.
      Returns:
        `true` if this session is created.

    - #### isSecuring

          boolean isSecuring()

      Tells if the session is processing a SSL/TLS handshake.
      Returns:
        `true if and only if this session is processing a SSL/TLS handshake.`

    - #### isSecured

          boolean isSecured()

      Tells if the session is belonging to a secured connection.
      Returns:
        `true if and only if this session is belonging a secured connection.`

    - #### changeState

          void changeState(IoSession.SessionState newState)

      Changes the session's state from the current state to a new state. Not all the transition are allowed. Here is the list of all the possible transitions :
      - CREATED -> CONNECTED
      - CREATED -> SECURING
      - CREATED -> CLOSING
      - CONNECTED -> SECURING
      - CONNECTED -> CLOSING
      - SECURING -> SECURED
      - SECURING -> CLOSING
      - SECURED -> CONNECTED
      - SECURED -> SECURING
      - SECURED -> CLOSING
      - CLOSING -> CLOSED
      Parameters:
        `newState` - The final SessionState

    - #### initSecure

          void initSecure(SSLContext sslContext)

      Initializes the SSL/TLS environment for this session.
      Parameters:
        `sslContext` - The SLLCOntext instance to use.

    - #### isConnectedSecured

          boolean isConnectedSecured()

      Tells if the session is using SSL/TLS.
      Returns:
        `true if and only if this session is exchanging data over a SSL/TLS connection`

    - #### close

          IoFuture<Void> close(boolean immediately)

      Closes this session immediately or after all queued write requests are flushed. This operation is asynchronous. Wait for the returned `IoFuture` if you want to wait for the session actually closed. Once this method has been called, no incoming request will be accepted.
      Parameters:
        `immediately` - `true` to close this session immediately. `false` to close this session after all queued write requests are flushed.
      Returns:
        A `IoFuture` that will contains the session's state

    - #### suspendRead

          void suspendRead()

      Suspends read operations for this session.

    - #### suspendWrite

          void suspendWrite()

      Suspends write operations for this session.

    - #### resumeRead

          void resumeRead()

      Resumes read operations for this session.

    - #### resumeWrite

          void resumeWrite()

      Resumes write operations for this session.

    - #### isReadSuspended

          boolean isReadSuspended()

      Is read operation is suspended for this session.
      Returns:
        `true` if suspended

    - #### isWriteSuspended

          boolean isWriteSuspended()

      Is write operation is suspended for this session.
      Returns:
        `true` if suspended

    - #### getReadBytes

          long getReadBytes()

      Gets the total number of bytes read for this session since it was created. Returns the total number of bytes which were read from this session.

    - #### getWrittenBytes

          long getWrittenBytes()

      Gets the total number of bytes written for this session since it was created.
      Returns:
        the total number of bytes which were written to this session.

    - #### getConfig

          IoSessionConfig getConfig()

      Gets the session configuration, it where the idle timeout are set and other transport specific configuration.
      Returns:
        the session's configuration

    - #### getCreationTime

          long getCreationTime()

      The session's creation time.
      Returns:
        the session's creation time in milliseconds

    - #### getLastIoTime

          long getLastIoTime()

      Returns the time in millisecond when I/O occurred lastly (either read or write).
      Returns:
        the time of the last read or write done for this session

    - #### getLastReadTime

          long getLastReadTime()

      Returns the time in millisecond when the last I/O read occurred. Returns the time in millisecond when read operation occurred lastly.

    - #### getLastWriteTime

          long getLastWriteTime()

      Returns the time in millisecond when the last I/O write occurred. Returns the time in millisecond when write operation occurred lastly.

    - #### getAttribute

          <T> T getAttribute(AttributeKey<T> key,
                           T defaultValue)

      Returns the value of the user-defined attribute for the given `key`.If the there is no attribute with the specified key the `defaultValue` will be returned.
      Parameters:
        `key` - the attribute's key, must not be `null`
      Returns:
        `defaultValue` if there is no attribute with the specified key
      Throws:
        `IllegalArgumentException` - if `key==null`
      See Also:
        `setAttribute(AttributeKey, Object)`

    - #### getAttribute

          <T> T getAttribute(AttributeKey<T> key)

      Returns the value of the user-defined attribute for the given `key`.If the there is no attribute with the specified key `null` will be returned.
      Parameters:
        `key` - the attribute's key, must not be `null`
      Returns:
        `null` if there is no attribute with the specified key
      Throws:
        `IllegalArgumentException` - if `key==null`
      See Also:
        `setAttribute(AttributeKey, Object)`

    - #### setAttribute

          <T> T setAttribute(AttributeKey<? extends T> key,
                           T value)

      Sets a user-defined attribute. If the `value` is `null` the attribute will be removed from this `IoSession`.
      Parameters:
        `key` - the attribute's key, must not be `null`
        `value` - the attribute's value, `null` to remove the attribute
      Returns:
        the old attribute's value or `null` if there is no previous value
      Throws:
        `IllegalArgumentException` -
        - if `key==null`
        - if `value` is not `null` and not an instance of type that is specified in by the given `key` (see `AttributeKey.getType()`)
      See Also:
        `getAttribute(AttributeKey)`

    - #### getAttributeKeys

          Set<AttributeKey<?>> getAttributeKeys()

      Returns an unmodifiable `Set` of all Keys of this `IoSession`. If this `IoSession` contains no attributes an empty `Set` will be returned.
      Returns:
        all Keys, never `null`
      See Also:
        `Collections.unmodifiableSet(Set)`

    - #### removeAttribute

          <T> T removeAttribute(AttributeKey<T> key)

      Removes the specified Attribute from this container. The old value will be returned, `null` will be rutrnen if there is no such attribute in this container.
      This method is equivalent to `setAttribute(key,null)`.
      Parameters:
        `key` - of the attribute to be removed,must not be `null`
      Returns:
        the removed value, `null` if this container doesn't contain the specified attribute
      Throws:
        `IllegalArgumentException` - if `key==null`

    - #### write

          void write(Object message)

      Enqueue a message for writing. This method wont block ! The message will by asynchronously processed by the filter chain and wrote to socket by the `SelectorLoop`

    - #### writeWithFuture

          IoFuture<Void> writeWithFuture(Object message)

      Same as `write(Object)`, but provide a `IoFuture` for tracking the completion of this write.
      Parameters:
        `message` - the message to be processed and written
      Returns:
        the `IoFuture` for tracking this asynchronous operation

    - #### enqueueWriteRequest

          WriteRequest enqueueWriteRequest(WriteRequest writeRequest)

      Internal method for enqueue write request after filter chain processing
      Parameters:
        `writeRequest` - the message to put in the write request
      Returns:
        the created write request

Copyright © 2009–2013 Apache MINA Project. All rights reserved.