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
`static class` `IoSession.SessionState` State of a `IoSession`

### Field Summary

Fields
`static AttributeKey<SslHelper>` `SSL_HELPER` The SslHelper instance name, stored in the session's attributes

### Method Summary

Methods
`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