org.apache.mina.core.session

## Interface IoSession

- All Known Subinterfaces:
    SerialSession
  All Known Implementing Classes:
    AbstractIoSession, AprSession, DummySession, NioSession, ProtocolCodecSession

      public interface IoSession

  A handle which represents 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.

  ### Equality of Sessions

  TODO : The getId() method is totally wrong. We can't base a method which is designed to create a unique ID on the hashCode method. `#equals(Object)` and `#hashCode()` shall not be overriden to the default behavior that is defined in `Object`.
  Author:
    Apache MINA Project

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `CloseFuture` | `close()` Deprecated. use `close(boolean)`
    `CloseFuture` | `close(boolean immediately)` Closes this session immediately or after all queued write requests are flushed.
    `boolean` | `containsAttribute(Object key)` Returns `true` if this session contains the attribute with the specified `key`.
    `Object` | `getAttachment()` Deprecated. Use `getAttribute(Object)` instead.
    `Object` | `getAttribute(Object key)` Returns the value of the user-defined attribute of this session.
    `Object` | `getAttribute(Object key, Object defaultValue)` Returns the value of user defined attribute associated with the specified key.
    `Set<Object>` | `getAttributeKeys()` Returns the set of keys of all user-defined attributes.
    `int` | `getBothIdleCount()` Returns the number of the fired continuous `sessionIdle` events for `IdleStatus.BOTH_IDLE`.
    `CloseFuture` | `getCloseFuture()` Returns the `CloseFuture` of this session.
    `IoSessionConfig` | `getConfig()`
    `long` | `getCreationTime()`
    `Object` | `getCurrentWriteMessage()` Returns the message which is being written by `IoService`.
    `WriteRequest` | `getCurrentWriteRequest()` Returns the `WriteRequest` which is being processed by `IoService`.
    `IoFilterChain` | `getFilterChain()`
    `IoHandler` | `getHandler()`
    `long` | `getId()`
    `int` | `getIdleCount(IdleStatus status)` Returns the number of the fired continuous `sessionIdle` events for the specified `IdleStatus`.
    `long` | `getLastBothIdleTime()` Returns the time in milliseconds when the last `sessionIdle` event is fired for `IdleStatus.BOTH_IDLE`.
    `long` | `getLastIdleTime(IdleStatus status)` Returns the time in milliseconds when the last `sessionIdle` event is fired for the specified `IdleStatus`.
    `long` | `getLastIoTime()` Returns the time in millis when I/O occurred lastly.
    `long` | `getLastReaderIdleTime()` Returns the time in milliseconds when the last `sessionIdle` event is fired for `IdleStatus.READER_IDLE`.
    `long` | `getLastReadTime()` Returns the time in millis when read operation occurred lastly.
    `long` | `getLastWriterIdleTime()` Returns the time in milliseconds when the last `sessionIdle` event is fired for `IdleStatus.WRITER_IDLE`.
    `long` | `getLastWriteTime()` Returns the time in millis when write operation occurred lastly.
    `SocketAddress` | `getLocalAddress()` Returns the socket address of local machine which is associated with this session.
    `long` | `getReadBytes()` Returns the total number of bytes which were read from this session.
    `double` | `getReadBytesThroughput()` Returns the number of read bytes per second.
    `int` | `getReaderIdleCount()` Returns the number of the fired continuous `sessionIdle` events for `IdleStatus.READER_IDLE`.
    `long` | `getReadMessages()` Returns the total number of messages which were read and decoded from this session.
    `double` | `getReadMessagesThroughput()` Returns the number of read messages per second.
    `SocketAddress` | `getRemoteAddress()` Returns the socket address of remote peer.
    `long` | `getScheduledWriteBytes()` Returns the number of bytes which are scheduled to be written to this session.
    `int` | `getScheduledWriteMessages()` Returns the number of messages which are scheduled to be written to this session.
    `IoService` | `getService()`
    `SocketAddress` | `getServiceAddress()` Returns the socket address of the `IoService` listens to to manage this session.
    `TransportMetadata` | `getTransportMetadata()`
    `WriteRequestQueue` | `getWriteRequestQueue()` TODO Add method documentation
    `int` | `getWriterIdleCount()` Returns the number of the fired continuous `sessionIdle` events for `IdleStatus.WRITER_IDLE`.
    `long` | `getWrittenBytes()` Returns the total number of bytes which were written to this session.
    `double` | `getWrittenBytesThroughput()` Returns the number of written bytes per second.
    `long` | `getWrittenMessages()` Returns the total number of messages which were written and encoded by this session.
    `double` | `getWrittenMessagesThroughput()` Returns the number of written messages per second.
    `boolean` | `isBothIdle()` Returns `true` if this session is `IdleStatus.BOTH_IDLE`.
    `boolean` | `isClosing()` Returns `true if and only if this session is being closed (but not disconnected yet) or is closed.`
    `boolean` | `isConnected()` Returns `true` if this session is connected with remote peer.
    `boolean` | `isIdle(IdleStatus status)` Returns `true` if this session is idle for the specified `IdleStatus`.
    `boolean` | `isReaderIdle()` Returns `true` if this session is `IdleStatus.READER_IDLE`.
    `boolean` | `isReadSuspended()` Is read operation is suspended for this session.
    `boolean` | `isWriterIdle()` Returns `true` if this session is `IdleStatus.WRITER_IDLE`.
    `boolean` | `isWriteSuspended()` Is write operation is suspended for this session.
    `ReadFuture` | `read()` TODO This javadoc is wrong.
    `Object` | `removeAttribute(Object key)` Removes a user-defined attribute with the specified key.
    `boolean` | `removeAttribute(Object key, Object value)` Removes a user defined attribute with the specified key if the current attribute value is equal to the specified value.
    `boolean` | `replaceAttribute(Object key, Object oldValue, Object newValue)` Replaces a user defined attribute with the specified key if the value of the attribute is equals to the specified old value.
    `void` | `resumeRead()` Resumes read operations for this session.
    `void` | `resumeWrite()` Resumes write operations for this session.
    `Object` | `setAttachment(Object attachment)` Deprecated. Use `setAttribute(Object, Object)` instead.
    `Object` | `setAttribute(Object key)` Sets a user defined attribute without a value.
    `Object` | `setAttribute(Object key, Object value)` Sets a user-defined attribute.
    `Object` | `setAttributeIfAbsent(Object key)` Sets a user defined attribute without a value if the attribute with the specified key is not set yet.
    `Object` | `setAttributeIfAbsent(Object key, Object value)` Sets a user defined attribute if the attribute with the specified key is not set yet.
    `void` | `setCurrentWriteRequest(WriteRequest currentWriteRequest)` TODO setWriteRequestQueue.
    `void` | `suspendRead()` Suspends read operations for this session.
    `void` | `suspendWrite()` Suspends write operations for this session.
    `void` | `updateThroughput(long currentTime, boolean force)` Update all statistical properties related with throughput assuming the specified time is the current time.
    `WriteFuture` | `write(Object message)` Writes the specified `message` to remote peer.
    `WriteFuture` | `write(Object message, SocketAddress destination)` (Optional) Writes the specified `message` to the specified `destination`.

- - ### Method Detail

    - #### getId

          long getId()

      Returns:
        a unique identifier for this session. Every session has its own ID which is different from each other. TODO : The way it's implemented does not guarantee that the contract is respected. It uses the HashCode() method which don't guarantee the key unicity.

    - #### getService

          IoService getService()

      Returns:
        the `IoService` which provides I/O service to this session.

    - #### getHandler

          IoHandler getHandler()

      Returns:
        the `IoHandler` which handles this session.

    - #### getConfig

          IoSessionConfig getConfig()

      Returns:
        the configuration of this session.

    - #### getFilterChain

          IoFilterChain getFilterChain()

      Returns:
        the filter chain that only affects this session.

    - #### getWriteRequestQueue

          WriteRequestQueue getWriteRequestQueue()

      TODO Add method documentation

    - #### getTransportMetadata

          TransportMetadata getTransportMetadata()

      Returns:
        the `TransportMetadata` that this session runs on.

    - #### read

          ReadFuture read()

      TODO This javadoc is wrong. The return tag should be short.
      Returns:
        a `ReadFuture` which is notified when a new message is received, the connection is closed or an exception is caught. This operation is especially useful when you implement a client application. TODO : Describe here how we enable this feature. However, please note that this operation is disabled by default and throw `IllegalStateException` because all received events must be queued somewhere to support this operation, possibly leading to memory leak. This means you have to keep calling `read()` once you enabled this operation. To enable this operation, please call `IoSessionConfig.setUseReadOperation(boolean)` with `true`.
      Throws:
        `IllegalStateException` - if `useReadOperation` option has not been enabled.

    - #### write

          WriteFuture write(Object message)

      Writes the specified `message` to remote peer. This operation is asynchronous; `IoHandler.messageSent(IoSession,Object)` will be invoked when the message is actually sent to remote peer. You can also wait for the returned `WriteFuture` if you want to wait for the message actually written.

    - #### write

          WriteFuture write(Object message,
                          SocketAddress destination)

      (Optional) Writes the specified `message` to the specified `destination`. This operation is asynchronous; `IoHandler.messageSent(IoSession, Object)` will be invoked when the message is actually sent to remote peer. You can also wait for the returned `WriteFuture` if you want to wait for the message actually written.

      When you implement a client that receives a broadcast message from a server such as DHCP server, the client might need to send a response message for the broadcast message the server sent. Because the remote address of the session is not the address of the server in case of broadcasting, there should be a way to specify the destination when you write the response message. This interface provides `write(Object, SocketAddress)` method so you can specify the destination.

      Parameters:
        `destination` - `null` if you want the message sent to the default remote address
      Throws:
        `UnsupportedOperationException` - if this operation is not supported

    - #### close

          CloseFuture close(boolean immediately)

      Closes this session immediately or after all queued write requests are flushed. This operation is asynchronous. Wait for the returned `CloseFuture` if you want to wait for the session actually closed.
      Parameters:
        `immediately` - `true` to close this session immediately (i.e. `close()`). The pending write requests will simply be discarded. `false` to close this session after all queued write requests are flushed (i.e. `#closeOnFlush()`).

    - #### close

          @Deprecated
          CloseFuture close()

      Deprecated. use `close(boolean)`
      Closes this session after all queued write requests are flushed. This operation is asynchronous. Wait for the returned `CloseFuture` if you want to wait for the session actually closed.

    - #### getAttachment

          @Deprecated
          Object getAttachment()

      Deprecated. Use `getAttribute(Object)` instead.
      Returns an attachment of this session. This method is identical with `getAttribute( "" )`.

    - #### setAttachment

          @Deprecated
          Object setAttachment(Object attachment)

      Deprecated. Use `setAttribute(Object, Object)` instead.
      Sets an attachment of this session. This method is identical with `setAttribute( "", attachment )`.
      Returns:
        Old attachment. `null` if it is new.

    - #### getAttribute

          Object getAttribute(Object key)

      Returns the value of the user-defined attribute of this session.
      Parameters:
        `key` - the key of the attribute
      Returns:
        `null` if there is no attribute with the specified key

    - #### getAttribute

          Object getAttribute(Object key,
                            Object defaultValue)

      Returns the value of user defined attribute associated with the specified key. If there's no such attribute, the specified default value is associated with the specified key, and the default value is returned. This method is same with the following code except that the operation is performed atomically.

           if (containsAttribute(key)) {
               return getAttribute(key);
           } else {
               setAttribute(key, defaultValue);
               return defaultValue;
           }

    - #### setAttribute

          Object setAttribute(Object key,
                            Object value)

      Sets a user-defined attribute.
      Parameters:
        `key` - the key of the attribute
        `value` - the value of the attribute
      Returns:
        The old value of the attribute. `null` if it is new.

    - #### setAttribute

          Object setAttribute(Object key)

      Sets a user defined attribute without a value. This is useful when you just want to put a 'mark' attribute. Its value is set to `Boolean.TRUE`.
      Parameters:
        `key` - the key of the attribute
      Returns:
        The old value of the attribute. `null` if it is new.

    - #### setAttributeIfAbsent

          Object setAttributeIfAbsent(Object key,
                                    Object value)

      Sets a user defined attribute if the attribute with the specified key is not set yet. This method is same with the following code except that the operation is performed atomically.

           if (containsAttribute(key)) {
               return getAttribute(key);
           } else {
               return setAttribute(key, value);
           }

    - #### setAttributeIfAbsent

          Object setAttributeIfAbsent(Object key)

      Sets a user defined attribute without a value if the attribute with the specified key is not set yet. This is useful when you just want to put a 'mark' attribute. Its value is set to `Boolean.TRUE`. This method is same with the following code except that the operation is performed atomically.

           if (containsAttribute(key)) {
               return getAttribute(key);  // might not always be Boolean.TRUE.
           } else {
               return setAttribute(key);
           }

    - #### removeAttribute

          Object removeAttribute(Object key)

      Removes a user-defined attribute with the specified key.
      Returns:
        The old value of the attribute. `null` if not found.

    - #### removeAttribute

          boolean removeAttribute(Object key,
                                Object value)

      Removes a user defined attribute with the specified key if the current attribute value is equal to the specified value. This method is same with the following code except that the operation is performed atomically.

           if (containsAttribute(key) && getAttribute(key).equals(value)) {
               removeAttribute(key);
               return true;
           } else {
               return false;
           }

    - #### replaceAttribute

          boolean replaceAttribute(Object key,
                                 Object oldValue,
                                 Object newValue)

      Replaces a user defined attribute with the specified key if the value of the attribute is equals to the specified old value. This method is same with the following code except that the operation is performed atomically.

           if (containsAttribute(key) && getAttribute(key).equals(oldValue)) {
               setAttribute(key, newValue);
               return true;
           } else {
               return false;
           }

    - #### containsAttribute

          boolean containsAttribute(Object key)

      Returns `true` if this session contains the attribute with the specified `key`.

    - #### getAttributeKeys

          Set<Object> getAttributeKeys()

      Returns the set of keys of all user-defined attributes.

    - #### isConnected

          boolean isConnected()

      Returns `true` if this session is connected with remote peer.

    - #### isClosing

          boolean isClosing()

      Returns `true if and only if this session is being closed (but not disconnected yet) or is closed.`

    - #### getCloseFuture

          CloseFuture getCloseFuture()

      Returns the `CloseFuture` of this session. This method returns the same instance whenever user calls it.

    - #### getRemoteAddress

          SocketAddress getRemoteAddress()

      Returns the socket address of remote peer.

    - #### getLocalAddress

          SocketAddress getLocalAddress()

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

    - #### getServiceAddress

          SocketAddress getServiceAddress()

      Returns the socket address of the `IoService` listens to to manage this session. If this session is managed by `IoAcceptor`, it returns the `SocketAddress` which is specified as a parameter of `IoAcceptor.bind()`. If this session is managed by `IoConnector`, this method returns the same address with that of `getRemoteAddress()`.

    - #### setCurrentWriteRequest

          void setCurrentWriteRequest(WriteRequest currentWriteRequest)

      TODO setWriteRequestQueue.
      Parameters:
        `writeRequestQueue` -

    - #### 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

    - #### updateThroughput

          void updateThroughput(long currentTime,
                              boolean force)

      Update all statistical properties related with throughput assuming the specified time is the current time. By default this method returns silently without updating the throughput properties if they were calculated already within last `calculation interval`. If, however, `force` is specified as `true`, this method updates the throughput properties immediately.
      Parameters:
        `currentTime` - the current time in milliseconds

    - #### getReadBytes

          long getReadBytes()

      Returns the total number of bytes which were read from this session.

    - #### getWrittenBytes

          long getWrittenBytes()

      Returns the total number of bytes which were written to this session.

    - #### getReadMessages

          long getReadMessages()

      Returns the total number of messages which were read and decoded from this session.

    - #### getWrittenMessages

          long getWrittenMessages()

      Returns the total number of messages which were written and encoded by this session.

    - #### getReadBytesThroughput

          double getReadBytesThroughput()

      Returns the number of read bytes per second.

    - #### getWrittenBytesThroughput

          double getWrittenBytesThroughput()

      Returns the number of written bytes per second.

    - #### getReadMessagesThroughput

          double getReadMessagesThroughput()

      Returns the number of read messages per second.

    - #### getWrittenMessagesThroughput

          double getWrittenMessagesThroughput()

      Returns the number of written messages per second.

    - #### getScheduledWriteMessages

          int getScheduledWriteMessages()

      Returns the number of messages which are scheduled to be written to this session.

    - #### getScheduledWriteBytes

          long getScheduledWriteBytes()

      Returns the number of bytes which are scheduled to be written to this session.

    - #### getCurrentWriteMessage

          Object getCurrentWriteMessage()

      Returns the message which is being written by `IoService`.
      Returns:
        `null` if and if only no message is being written

    - #### getCurrentWriteRequest

          WriteRequest getCurrentWriteRequest()

      Returns the `WriteRequest` which is being processed by `IoService`.
      Returns:
        `null` if and if only no message is being written

    - #### getCreationTime

          long getCreationTime()

      Returns:
        the session's creation time in milliseconds

    - #### getLastIoTime

          long getLastIoTime()

      Returns the time in millis when I/O occurred lastly.

    - #### getLastReadTime

          long getLastReadTime()

      Returns the time in millis when read operation occurred lastly.

    - #### getLastWriteTime

          long getLastWriteTime()

      Returns the time in millis when write operation occurred lastly.

    - #### isIdle

          boolean isIdle(IdleStatus status)

      Returns `true` if this session is idle for the specified `IdleStatus`.

    - #### isReaderIdle

          boolean isReaderIdle()

      Returns `true` if this session is `IdleStatus.READER_IDLE`.
      See Also:
        `isIdle(IdleStatus)`

    - #### isWriterIdle

          boolean isWriterIdle()

      Returns `true` if this session is `IdleStatus.WRITER_IDLE`.
      See Also:
        `isIdle(IdleStatus)`

    - #### isBothIdle

          boolean isBothIdle()

      Returns `true` if this session is `IdleStatus.BOTH_IDLE`.
      See Also:
        `isIdle(IdleStatus)`

    - #### getIdleCount

          int getIdleCount(IdleStatus status)

      Returns the number of the fired continuous `sessionIdle` events for the specified `IdleStatus`.

      If `sessionIdle` event is fired first after some time after I/O, `idleCount` becomes `1`. `idleCount` resets to `0` if any I/O occurs again, otherwise it increases to `2` and so on if `sessionIdle` event is fired again without any I/O between two (or more) `sessionIdle` events.

    - #### getReaderIdleCount

          int getReaderIdleCount()

      Returns the number of the fired continuous `sessionIdle` events for `IdleStatus.READER_IDLE`.
      See Also:
        `getIdleCount(IdleStatus)`

    - #### getWriterIdleCount

          int getWriterIdleCount()

      Returns the number of the fired continuous `sessionIdle` events for `IdleStatus.WRITER_IDLE`.
      See Also:
        `getIdleCount(IdleStatus)`

    - #### getBothIdleCount

          int getBothIdleCount()

      Returns the number of the fired continuous `sessionIdle` events for `IdleStatus.BOTH_IDLE`.
      See Also:
        `getIdleCount(IdleStatus)`

    - #### getLastIdleTime

          long getLastIdleTime(IdleStatus status)

      Returns the time in milliseconds when the last `sessionIdle` event is fired for the specified `IdleStatus`.

    - #### getLastReaderIdleTime

          long getLastReaderIdleTime()

      Returns the time in milliseconds when the last `sessionIdle` event is fired for `IdleStatus.READER_IDLE`.
      See Also:
        `getLastIdleTime(IdleStatus)`

    - #### getLastWriterIdleTime

          long getLastWriterIdleTime()

      Returns the time in milliseconds when the last `sessionIdle` event is fired for `IdleStatus.WRITER_IDLE`.
      See Also:
        `getLastIdleTime(IdleStatus)`

    - #### getLastBothIdleTime

          long getLastBothIdleTime()

      Returns the time in milliseconds when the last `sessionIdle` event is fired for `IdleStatus.BOTH_IDLE`.
      See Also:
        `getLastIdleTime(IdleStatus)`

Copyright © 2004-2012 Apache MINA Project. All Rights Reserved.