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.
You can simply downcast the session to an appropriate subclass.
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.
Object.equals(Object)
and Object.hashCode()
shall not be overriden
to the default behavior that is defined in Object
.Modifier and Type | Method and Description |
---|---|
CloseFuture |
close()
Deprecated.
use
closeNow() |
CloseFuture |
close(boolean immediately)
Deprecated.
Use either the
closeNow() or the closeOnFlush() methods |
CloseFuture |
closeNow()
Closes this session immediately.
|
CloseFuture |
closeOnFlush()
Closes this session after all queued write requests are flushed.
|
boolean |
containsAttribute(Object 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() |
int |
getBothIdleCount() |
CloseFuture |
getCloseFuture() |
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) |
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.
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)
Associate the current write request with the session
|
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 . |
long getId()
IoService getService()
IoService
which provides I/O service to this session.IoSessionConfig getConfig()
IoFilterChain getFilterChain()
WriteRequestQueue getWriteRequestQueue()
TransportMetadata getTransportMetadata()
TransportMetadata
that this session runs on.ReadFuture read()
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
.IllegalStateException
- if
useReadOperation
option has not been enabled.WriteFuture write(Object message)
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.message
- The message to writeWriteFuture write(Object message, SocketAddress destination)
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.
message
- The message to writedestination
- null
if you want the message sent to the
default remote address@Deprecated CloseFuture close(boolean immediately)
closeNow()
or the closeOnFlush()
methodsCloseFuture
if you want to wait for the session actually closed.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.CloseFuture closeNow()
CloseFuture
.CloseFuture
that can be use to wait for the completion of this operationCloseFuture closeOnFlush()
CloseFuture
if you want to wait
for the session actually closed.@Deprecated CloseFuture close()
closeNow()
CloseFuture
if you want to wait for the session actually closed.@Deprecated Object getAttachment()
getAttribute(Object)
instead.getAttribute( "" )
.@Deprecated Object setAttachment(Object attachment)
setAttribute(Object, Object)
instead.setAttribute( "", attachment )
.attachment
- The attachmentnull
if it is new.Object getAttribute(Object key)
key
- the key of the attributenull
if there is no attribute with the specified keyObject getAttribute(Object key, Object defaultValue)
if (containsAttribute(key)) { return getAttribute(key); } else { setAttribute(key, defaultValue); return defaultValue; }
key
- the key of the attribute we want to retreivedefaultValue
- the default value of the attributenull
if not foundObject setAttribute(Object key, Object value)
key
- the key of the attributevalue
- the value of the attributenull
if it is new.Object setAttribute(Object key)
Boolean.TRUE
.key
- the key of the attributenull
if it is new.Object setAttributeIfAbsent(Object key, Object value)
if (containsAttribute(key)) { return getAttribute(key); } else { return setAttribute(key, value); }
key
- The key of the attribute we want to setvalue
- The value we want to setnull
if not found.Object setAttributeIfAbsent(Object key)
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); }
key
- The key of the attribute we want to setnull
if not found.Object removeAttribute(Object key)
key
- The key of the attribute we want to removenull
if not found.boolean removeAttribute(Object key, Object value)
if (containsAttribute(key) && getAttribute(key).equals(value)) { removeAttribute(key); return true; } else { return false; }
key
- The key we want to removevalue
- The value we want to removetrue
if the removal was successfulboolean replaceAttribute(Object key, Object oldValue, Object newValue)
if (containsAttribute(key) && getAttribute(key).equals(oldValue)) { setAttribute(key, newValue); return true; } else { return false; }
key
- The key we want to replaceoldValue
- The previous valuenewValue
- The new valuetrue
if the replacement was successfulboolean containsAttribute(Object key)
key
- The key of the attribute we are looking for in the sessiontrue
if this session contains the attribute with
the specified key
.Set<Object> getAttributeKeys()
boolean isConnected()
true
if this session is connected with remote peer.boolean isActive()
true
if this session is active.boolean isClosing()
true
if and only if this session is being closed
(but not disconnected yet) or is closed.boolean isSecured()
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.boolean isServer()
true
if the session was created by an acceptor.CloseFuture getCloseFuture()
CloseFuture
of this session. This method returns
the same instance whenever user calls it.SocketAddress getRemoteAddress()
SocketAddress getLocalAddress()
SocketAddress getServiceAddress()
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()
.void setCurrentWriteRequest(WriteRequest currentWriteRequest)
currentWriteRequest
- the current write request to associatevoid suspendRead()
void suspendWrite()
void resumeRead()
void resumeWrite()
boolean isReadSuspended()
true
if suspendedboolean isWriteSuspended()
true
if suspendedvoid updateThroughput(long currentTime, boolean force)
calculation interval
.
If, however, force
is specified as true
, this method
updates the throughput properties immediately.currentTime
- the current time in millisecondsforce
- Force the update if true
long getReadBytes()
long getWrittenBytes()
long getReadMessages()
long getWrittenMessages()
double getReadBytesThroughput()
double getWrittenBytesThroughput()
double getReadMessagesThroughput()
double getWrittenMessagesThroughput()
int getScheduledWriteMessages()
long getScheduledWriteBytes()
Object getCurrentWriteMessage()
IoService
.null
if and if only no message is being writtenWriteRequest getCurrentWriteRequest()
WriteRequest
which is being processed by
IoService
.null
if and if only no message is being writtenlong getCreationTime()
long getLastIoTime()
long getLastReadTime()
long getLastWriteTime()
boolean isIdle(IdleStatus status)
status
- The researched idle statustrue
if this session is idle for the specified
IdleStatus
.boolean isReaderIdle()
true
if this session is IdleStatus.READER_IDLE
.isIdle(IdleStatus)
boolean isWriterIdle()
true
if this session is IdleStatus.WRITER_IDLE
.isIdle(IdleStatus)
boolean isBothIdle()
true
if this session is IdleStatus.BOTH_IDLE
.isIdle(IdleStatus)
int getIdleCount(IdleStatus status)
status
- The researched idle statussessionIdle
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.
int getReaderIdleCount()
sessionIdle
events
for IdleStatus.READER_IDLE
.getIdleCount(IdleStatus)
int getWriterIdleCount()
sessionIdle
events
for IdleStatus.WRITER_IDLE
.getIdleCount(IdleStatus)
int getBothIdleCount()
sessionIdle
events
for IdleStatus.BOTH_IDLE
.getIdleCount(IdleStatus)
long getLastIdleTime(IdleStatus status)
status
- The researched idle statussessionIdle
event
is fired for the specified IdleStatus
.long getLastReaderIdleTime()
sessionIdle
event
is fired for IdleStatus.READER_IDLE
.getLastIdleTime(IdleStatus)
long getLastWriterIdleTime()
sessionIdle
event
is fired for IdleStatus.WRITER_IDLE
.getLastIdleTime(IdleStatus)
long getLastBothIdleTime()
sessionIdle
event
is fired for IdleStatus.BOTH_IDLE
.getLastIdleTime(IdleStatus)
Copyright © 2004–2023 Apache MINA Project. All rights reserved.