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 onewrite(Object)
calls at the same time will cause theIoFilter.filterWrite(IoFilter.NextFilter,IoSession,WriteRequest)
to be executed simultaneously, and therefore you have to make sure theIoFilter
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.Object.equals(Object)
andObject.hashCode()
shall not be overriden to the default behavior that is defined inObject
.- Author:
- Apache MINA Project
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description CloseFuture
close()
Deprecated.usecloseNow()
CloseFuture
close(boolean immediately)
Deprecated.Use either thecloseNow()
or thecloseOnFlush()
methodsCloseFuture
closeNow()
Closes this session immediately.CloseFuture
closeOnFlush()
Closes this session after all queued write requests are flushed.boolean
containsAttribute(Object key)
Object
getAttachment()
Deprecated.UsegetAttribute(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()
int
getBothIdleCount()
CloseFuture
getCloseFuture()
IoSessionConfig
getConfig()
long
getCreationTime()
Object
getCurrentWriteMessage()
Returns the message which is being written byIoService
.WriteRequest
getCurrentWriteRequest()
Returns theWriteRequest
which is being processed byIoService
.IoFilterChain
getFilterChain()
IoHandler
getHandler()
long
getId()
int
getIdleCount(IdleStatus status)
long
getLastBothIdleTime()
long
getLastIdleTime(IdleStatus status)
long
getLastIoTime()
long
getLastReaderIdleTime()
long
getLastReadTime()
long
getLastWriterIdleTime()
long
getLastWriteTime()
SocketAddress
getLocalAddress()
long
getReadBytes()
double
getReadBytesThroughput()
int
getReaderIdleCount()
long
getReadMessages()
double
getReadMessagesThroughput()
SocketAddress
getRemoteAddress()
long
getScheduledWriteBytes()
int
getScheduledWriteMessages()
IoService
getService()
SocketAddress
getServiceAddress()
TransportMetadata
getTransportMetadata()
WriteRequestQueue
getWriteRequestQueue()
Get the queue that contains the message waiting for being written.int
getWriterIdleCount()
long
getWrittenBytes()
double
getWrittenBytesThroughput()
long
getWrittenMessages()
double
getWrittenMessagesThroughput()
boolean
isActive()
boolean
isBothIdle()
boolean
isClosing()
boolean
isConnected()
boolean
isIdle(IdleStatus status)
boolean
isReaderIdle()
boolean
isReadSuspended()
Is read operation is suspended for this session.boolean
isSecured()
boolean
isServer()
boolean
isWriterIdle()
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.UsesetAttribute(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)
Associate the current write request with the sessionvoid
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 specifiedmessage
to remote peer.WriteFuture
write(Object message, SocketAddress destination)
(Optional) Writes the specifiedmessage
to the specifieddestination
.
-
-
-
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.
-
getConfig
IoSessionConfig getConfig()
- Returns:
- the configuration of this session.
-
getFilterChain
IoFilterChain getFilterChain()
- Returns:
- the filter chain that only affects this session.
-
getWriteRequestQueue
WriteRequestQueue getWriteRequestQueue()
Get the queue that contains the message waiting for being written. As the reader might not be ready, it's frequent that the messages aren't written completely, or that some older messages are waiting to be written when a new message arrives. This queue is used to manage the backlog of messages.- Returns:
- The queue containing the pending messages.
-
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 throwIllegalStateException
because all received events must be queued somewhere to support this operation, possibly leading to memory leak. This means you have to keep callingread()
once you enabled this operation. To enable this operation, please callIoSessionConfig.setUseReadOperation(boolean)
withtrue
. - Throws:
IllegalStateException
- ifuseReadOperation
option has not been enabled.
-
write
WriteFuture write(Object message)
Writes the specifiedmessage
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 returnedWriteFuture
if you want to wait for the message actually written.- Parameters:
message
- The message to write- Returns:
- The associated WriteFuture
-
write
WriteFuture write(Object message, SocketAddress destination)
(Optional) Writes the specifiedmessage
to the specifieddestination
. 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 returnedWriteFuture
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:
message
- The message to writedestination
-null
if you want the message sent to the default remote address- Returns:
- The associated WriteFuture
-
close
@Deprecated CloseFuture close(boolean immediately)
Deprecated.Use either thecloseNow()
or thecloseOnFlush()
methodsCloses this session immediately or after all queued write requests are flushed. This operation is asynchronous. Wait for the returnedCloseFuture
if you want to wait for the session actually closed.- Parameters:
immediately
-true
to close this session immediately . The pending write requests will simply be discarded.false
to close this session after all queued write requests are flushed.- Returns:
- The associated CloseFuture
-
closeNow
CloseFuture closeNow()
Closes this session immediately. This operation is asynchronous, it returns aCloseFuture
.- Returns:
- The
CloseFuture
that can be use to wait for the completion of this operation
-
closeOnFlush
CloseFuture closeOnFlush()
Closes this session after all queued write requests are flushed. This operation is asynchronous. Wait for the returnedCloseFuture
if you want to wait for the session actually closed.- Returns:
- The associated CloseFuture
-
close
@Deprecated CloseFuture close()
Deprecated.usecloseNow()
Closes this session after all queued write requests are flushed. This operation is asynchronous. Wait for the returnedCloseFuture
if you want to wait for the session actually closed.- Returns:
- The associated CloseFuture
-
getAttachment
@Deprecated Object getAttachment()
Deprecated.UsegetAttribute(Object)
instead.Returns an attachment of this session. This method is identical withgetAttribute( "" )
.- Returns:
- The attachment
-
setAttachment
@Deprecated Object setAttachment(Object attachment)
Deprecated.UsesetAttribute(Object, Object)
instead.Sets an attachment of this session. This method is identical withsetAttribute( "", attachment )
.- Parameters:
attachment
- The 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; }
- Parameters:
key
- the key of the attribute we want to retreivedefaultValue
- the default value of the attribute- Returns:
- The retrieved attribute or
null
if not found
-
setAttribute
Object setAttribute(Object key, Object value)
Sets a user-defined attribute.- Parameters:
key
- the key of the attributevalue
- 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 toBoolean.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); }
- Parameters:
key
- The key of the attribute we want to setvalue
- The value we want to set- Returns:
- The old value of the attribute.
null
if not found.
-
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 toBoolean.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); }
- Parameters:
key
- The key of the attribute we want to set- Returns:
- The old value of the attribute.
null
if not found.
-
removeAttribute
Object removeAttribute(Object key)
Removes a user-defined attribute with the specified key.- Parameters:
key
- The key of the attribute we want to remove- 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; }
- Parameters:
key
- The key we want to removevalue
- The value we want to remove- Returns:
true
if the removal was successful
-
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; }
- Parameters:
key
- The key we want to replaceoldValue
- The previous valuenewValue
- The new value- Returns:
true
if the replacement was successful
-
containsAttribute
boolean containsAttribute(Object key)
- Parameters:
key
- The key of the attribute we are looking for in the session- Returns:
true
if this session contains the attribute with the specifiedkey
.
-
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.
-
isActive
boolean isActive()
- Returns:
true
if this session is active.
-
isClosing
boolean isClosing()
- Returns:
true
if and only if this session is being closed (but not disconnected yet) or is closed.
-
isSecured
boolean isSecured()
- Returns:
true
if the session has started and initialized a SSLEngine,false
if the session is not yet secured (the handshake is not completed) or if SSL is not set for this session, or if SSL is not even an option.
-
isServer
boolean isServer()
- Returns:
true
if the session was created by an acceptor.
-
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 byIoAcceptor
, it returns theSocketAddress
which is specified as a parameter ofIoAcceptor.bind()
. If this session is managed byIoConnector
, this method returns the same address with that ofgetRemoteAddress()
.
-
setCurrentWriteRequest
void setCurrentWriteRequest(WriteRequest currentWriteRequest)
Associate the current write request with the session- Parameters:
currentWriteRequest
- the current write request to associate
-
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 lastcalculation interval
. If, however,force
is specified astrue
, this method updates the throughput properties immediately.- Parameters:
currentTime
- the current time in millisecondsforce
- Force the update iftrue
-
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 byIoService
.- Returns:
null
if and if only no message is being written
-
getCurrentWriteRequest
WriteRequest getCurrentWriteRequest()
Returns theWriteRequest
which is being processed byIoService
.- 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)
- Parameters:
status
- The researched idle status- Returns:
true
if this session is idle for the specifiedIdleStatus
.
-
isReaderIdle
boolean isReaderIdle()
- Returns:
true
if this session isIdleStatus.READER_IDLE
.- See Also:
isIdle(IdleStatus)
-
isWriterIdle
boolean isWriterIdle()
- Returns:
true
if this session isIdleStatus.WRITER_IDLE
.- See Also:
isIdle(IdleStatus)
-
isBothIdle
boolean isBothIdle()
- Returns:
true
if this session isIdleStatus.BOTH_IDLE
.- See Also:
isIdle(IdleStatus)
-
getIdleCount
int getIdleCount(IdleStatus status)
- Parameters:
status
- The researched idle status- Returns:
- the number of the fired continuous
sessionIdle
events for the specifiedIdleStatus
.If
sessionIdle
event is fired first after some time after I/O,idleCount
becomes1
.idleCount
resets to0
if any I/O occurs again, otherwise it increases to2
and so on ifsessionIdle
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 forIdleStatus.READER_IDLE
. - See Also:
getIdleCount(IdleStatus)
-
getWriterIdleCount
int getWriterIdleCount()
- Returns:
- the number of the fired continuous
sessionIdle
events forIdleStatus.WRITER_IDLE
. - See Also:
getIdleCount(IdleStatus)
-
getBothIdleCount
int getBothIdleCount()
- Returns:
- the number of the fired continuous
sessionIdle
events forIdleStatus.BOTH_IDLE
. - See Also:
getIdleCount(IdleStatus)
-
getLastIdleTime
long getLastIdleTime(IdleStatus status)
- Parameters:
status
- The researched idle status- Returns:
- the time in milliseconds when the last
sessionIdle
event is fired for the specifiedIdleStatus
.
-
getLastReaderIdleTime
long getLastReaderIdleTime()
- Returns:
- the time in milliseconds when the last
sessionIdle
event is fired forIdleStatus.READER_IDLE
. - See Also:
getLastIdleTime(IdleStatus)
-
getLastWriterIdleTime
long getLastWriterIdleTime()
- Returns:
- the time in milliseconds when the last
sessionIdle
event is fired forIdleStatus.WRITER_IDLE
. - See Also:
getLastIdleTime(IdleStatus)
-
getLastBothIdleTime
long getLastBothIdleTime()
- Returns:
- the time in milliseconds when the last
sessionIdle
event is fired forIdleStatus.BOTH_IDLE
. - See Also:
getLastIdleTime(IdleStatus)
-
-