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.

Version:

$Rev: 677564 $, $Date: 2008-07-17 13:52:14 +0200 (jeu, 17 jui 2008) $

Author:

The Apache MINA Project (dev@mina.apache.org)

Method Summary

CloseFuture	close() Closes this session immediately.
CloseFuture	close(boolean immediately) Closes this session immediately or after all queued write requests are flushed.
CloseFuture	closeOnFlush() Closes this session 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.
TrafficMask	getTrafficMask() Returns the current TrafficMask of this session.
TransportMetadata	getTransportMetadata()
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	isWriterIdle() Returns true if this session is IdleStatus.WRITER_IDLE.
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() A shortcut method for setTrafficMask(TrafficMask) that resumes read operations for this session.
void	resumeWrite() A shortcut method for setTrafficMask(TrafficMask) that 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	setTrafficMask(TrafficMask trafficMask) Sets the TrafficMask of this session which will result the parent IoService to start to control the traffic of this session immediately.
void	suspendRead() A shortcut method for setTrafficMask(TrafficMask) that suspends read operations for this session.
void	suspendWrite() A shortcut method for setTrafficMask(TrafficMask) that suspends write operations for this session.
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.

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()

Closes this session immediately. This operation is asynchronous. Wait for the returned CloseFuture if you want to wait for the session actually closed.

closeOnFlush

CloseFuture closeOnFlush()

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.

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()). false to close this session after all queued write requests are flushed (i.e. closeOnFlush()).

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().

getTrafficMask

TrafficMask getTrafficMask()

Returns the current TrafficMask of this session.

setTrafficMask

void setTrafficMask(TrafficMask trafficMask)

Sets the TrafficMask of this session which will result the parent IoService to start to control the traffic of this session immediately.

suspendRead

void suspendRead()

A shortcut method for setTrafficMask(TrafficMask) that suspends read operations for this session.

suspendWrite

void suspendWrite()

A shortcut method for setTrafficMask(TrafficMask) that suspends write operations for this session.

resumeRead

void resumeRead()

A shortcut method for setTrafficMask(TrafficMask) that resumes read operations for this session.

resumeWrite

void resumeWrite()

A shortcut method for setTrafficMask(TrafficMask) that resumes write operations for this session.

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 nanoseconds

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)