Author: elecharny
Date: Tue Sep 20 09:16:40 2016
New Revision: 1761541
URL: http://svn.apache.org/viewvc?rev=1761541&view=rev
Log:
Added some pages related to session
Added:
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.1-session-configuration.mdtext
(with props)
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.2-session-statistics.mdtext
(with props)
Modified:
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4-session.mdtext
mina/site/trunk/content/mina-project/userguide/user-guide-toc.mdtext
Modified:
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4-session.mdtext
URL:
http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch4-session/ch4-session.mdtext?rev=1761541&r1=1761540&r2=1761541&view=diff
==============================================================================
---
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4-session.mdtext
(original)
+++
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4-session.mdtext
Tue Sep 20 09:16:40 2016
@@ -24,9 +24,22 @@ Notice: Licensed to the Apache Softwa
# Chapter 4 - Session
-The Session is at the heart of MINA : every time a client connects to the
server, a new session is created, and will be kept in memory until the client
is disconnected.
+## Content
-A session is used to store persistent informations about the connection, plus
any kind of information the server might need to use during the request
processing, and eventually during the whole session life.
+1. [Chapter 4.1 - Session Configuration](ch4.1-session-configuration.html)
+1. [Chapter 4.2 - Session Statistics](ch4.2-session-statistics.html)
+
+The Session is at the heart of MINA : every time a client connects to the
server, a new session is created on the server, and will be kept in memory
until the client is disconnected. If you are using MINA on the client side,
everytime you conect to a server, a session will be created on the client too.
+
+A session is used to store persistent informations about the connection, plus
any kind of information the client or the server might need to use during the
request processing, and eventually during the whole session life.
+
+This is also your access point for any operation you need to do on a session :
sending messages, closing the session, etc...
+
+<DIV class="note" markdown="1">
+It is critical to understand that due to the asynchrnous very nature of NIO,
reading from a session does not make a lot of sense. Actually, your application
get signalled whe some incoming message has arrived, and this is the IoHandler
which is responsible for handling such event.
+
+In other words, don't call session.read(). Never.
+</DIV>
## Session state
@@ -38,12 +51,84 @@ A session has a state, which will evolve
* Idle for write : no write has actually been made for a period of time
* Idle for both : no read nor write for a period of time
* Closing : the session is being closed (the remaining messages are being
flushed, cleaning up is not terminated)
-* Closed : The session is now closed, nothing else can be done to revive it.
+* Closed : The session is now closed, nothing else can be done to revive it.
This is actually not a real state : when teh session is closed, it's removed.
The following state diagram exposes all the possible states and transitions :
+We have a set of methods to get some information about the session status.
+
+Session status :
+
+* isActive() : tells if the session is valid (it might mean different things
depending on the implementation)
+* isClosing() : tells if the session is already being closed
+* isConnected() : tells if the session is active (ie, not in the closing mode)
+
+## Opening a session
+
+Actually, there is nothing you have to do : it's automatic ! Everytime a
remote peer connect to a server, the server will create a new connection. On
the client side, everytime you connect to a server, a session will be created.
+
+This session is passed as an argument to your handler, so that you can do
something with it in your application. On the client side, when you do connect
to a server, you can get back the created session this way :
+
+ :::java
+ ...
+ ConnectFuture connectionFuture = connector.connect(address);
+ connectionFuture.awaitUninterruptibly();
+
+ if (!connectionFuture.isConnected()) {
+ return false;
+ }
+
+ session = connectionFuture.getSession();
+ ...
+
+You can also do it in a shortest way :
+
+ :::java
+ ...
+ session = connector.connect(address).getSession();
+ ...
+
+## Initialization
+
+When a new session is created, it has to be initialized. This is done using
the default IoService configuration, bt you can update this configuration later
on. Actually, when the session is created, we internally create a copy of the
default IoService configuration that is stored within the session, and this is
this configuration instance that will be used (and that can be modified).
+
+This initialization will also starts the statistics counters, create the
Attributes container, associate a write queue to to the session (this is where
the messages will be enqueued until they have been sent), and ultimately, would
you have provided a specific task to do during this phase, it will call it.
+
+## Closing a session
+
+A session can be closed in 4 ways, two of which are explicit :
+* calling the _closeNow()_ method (explicit)
+* calling the _closeOnFlush()_ method (explicit)
+* when the remote peer has nicely closed the connection
+* if an exception occurs
+
+(note there are two deprecated methods that should not anymore be used :
_close(boolean)_ and _close()_)
+
+
+### Explicit closure
+
+The first two methods can be called anywhere in your application, the big
difference is one (_closeNow()_) will simply close the session, discarding any
message waiting to be transmitted to the peer, while the _closeOnFlush()_ will
wait until any pending message has been transmitted to the peer.
+
+<DIV class="note" markdown="1">
+Be aware that if the remote peer is not anymore connected, the session that
you are closing using a _closeOnFlush()_ call will never be destroyed, unless
you also handle its idleness, or before the system TCP timeout has closed the
socket - which might take hours -. Always manage idleness in your applications.
+</DIV>
+
+### Remote peer closing
+
+When the remote peer closes the session properly, the session will be closed,
and all the pending messages will be discarded. This is usually the way it
works.
+
+However, sometime, the remote peer does not properly close the connection
(this could happen when the cable is brutally unplugged). In this case, the
session never get informed about the disconnection. The only way to know about
it is to regularly check for the session state : if it's idle for more than a
specific amount of time - it has to be configured -, then the application can
decide to close the session. Otherwise, the session will be closed eventually
when the TCP timeout will be reached (it can take hours...).
+
+### Exception
+
+In some case, an excepion will occur that will cause the session to be closed.
Typically, when a session is being created, we may face an issue, and the
session will be immediately closed. One other possibility is that we can't
write some message, for instance because the channel has been closed : we then
close the session.
+
+All in all, everytime we met an exception while processing a session, this
session will be closed.
+
+Of course, your application will be informed through the _ExeptionCaught_
event.
+
## Configuration
Many different parameters can be set for a specific session :
@@ -52,12 +137,17 @@ Many different parameters can be set for
* sending buffer size
* Idle time
* Write timeOut
+* ...
+
+plus other configuration, depending on the transport type used (see Chapter 6
- Transports).
-plus other configuration, depending on the transport type used (see Chapter 6
- Transports)
+All those configuration parameters are stored into the _IoSessionConfig_
object, which can be get from the session using the _session.getConfig()_
method.
+
+For further informations about the session configuration, see [Chapter 4.1 -
Session Configuration](ch4-session/ch4.1-session-configuration.html)
## Managing user-defined attributes
-It might be necessary to store some data which may be used later. This is done
using the dedicated data structure associated which each session. This is a
key-value association, which can store any type of data the developer might
want to keep remanent.
+It might be necessary to store some data which may be used later. This is done
using the dedicated data structure associated which each session. This is a
key-value association, which can store any type of data the developer might
want to keep remanent along the session's life.
For instance, if you want to track the number of request a user has sent since
the session has been created, it's easy to store it into this map: just create
a key that will be associated with this value.
@@ -71,7 +161,8 @@ We have a way to handle stored Attribute
This container is created automatically when the session is created, and will
be disposed when the session is terminated.
-## Defining the container
+
+### The session container
As we said, this container is a key/value container, which default to a Map,
but it's also possible to define another data structure if one want to handle
long lived data, or to avoid storing all those data in memory if they are large
: we can implement an interface and a factory that will be used to create this
container when the session is created.
@@ -103,6 +194,24 @@ and here is the factory interface we can
IoSessionAttributeMap getAttributeMap(IoSession session)
throws Exception;
}
+### The session attributes access
+
+There are many methods available to manipulate the session's attributes :
+
+* boolean containsAttribute(Object key) : tells if a given attribute is present
+* Object getAttribute(Object key) : gets the value for a given attribute
+* Object getAttribute(Object key, Object defaultValue) : gets the value for a
given attribute, or a default value if absent
+* Set<Object> getAttributeKeys() : gets the set of all the stored attributes
+* Object removeAttribute(Object key) : remove a given attribute
+* boolean removeAttribute(Object key, Object value) : remove a given
attribute/value pair
+* boolean replaceAttribute(Object key, Object oldValue, Object newValue) :
replace a give attribute/value pair
+* Object setAttribute(Object key) : adds a new attribute with no value
+* Object setAttribute(Object key, Object value) : adds a new attribute/value
pair
+* Object setAttributeIfAbsent(Object key) : adds a new attribute with no
value, if it does not already exist
+* Object setAttributeIfAbsent(Object key, Object value) : adds a new
attribute/value pair, if it does not already exist
+
+All those methods allows your application to store, remove, get or update the
attributes stored into your session. Also note that some attributes are used
internally by MINA : don't lightly modify those you didn't create !
+
## Filter chain
Each session is associated with a chain of filters, which will be processed
when an incoming request or an outgoing message is received or emitted. Those
filters are specific for each session individually, even if most of the cases,
we will use the very same chain of filters for all the existing sessions.
@@ -120,9 +229,12 @@ Each session also keep a track of record
and many other useful informations.
+For further informations about the session statistics, see [Chapter 4.2 -
Session Statistics](ch4-session/ch4.2-session-statistics.html)
+
+
## Handler
-Last, not least, a session is attached to a Handler, in charge of dispatching
the messages to your application. This handler will also send pack response by
using the session, simply by calling the write() method :
+Last, not least, a session is attached to a Handler, in charge of dispatching
the messages to your application. This handler will also send back response by
using the session, simply by calling the write() method :
:::java
...
Added:
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.1-session-configuration.mdtext
URL:
http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.1-session-configuration.mdtext?rev=1761541&view=auto
==============================================================================
---
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.1-session-configuration.mdtext
(added)
+++
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.1-session-configuration.mdtext
Tue Sep 20 09:16:40 2016
@@ -0,0 +1,84 @@
+Title: Chapter 4.1 - Session Configuration
+NavUp: ch4-session.html
+NavUpText: Chapter 4 - Session
+NavPrev: ch4-session.html
+NavPrevText: Chapter 4 - Session
+NavNext: ch4.2-session-statistics.html
+NavNextText: Chapter 4.2 - Session Statistics
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Chapter 4.1 - Session Configuration
+
+Depending on the Session's type, we can configure various elements. Some of
those elements are shared across all the session's type, some other are
specific.
+
+We currently support 4 session flavors :
+
+* Socket : support for the TCP transport
+* Datagram : support for the UDP transport
+* Serial : support for the RS232 transport
+* VmPipe : support for the IPC transport
+
+
+## General parameters
+
+Here is the list of all the global parameters (they can be set fo any of the
Session flavors) :
+
+|| Parameter || type || Description || Default value ||
+| idleTimeForBoth | int | The number of seconds to wait before notify a
session that is idle on reads and writes | Infinite |
+| idleTimeForRead | int | The number of seconds to wait before notify a
session that is idle on reads | Infinite |
+| idleTimeForWrite | int | The number of seconds to wait before notify a
session that is idle on writes | Infinite |
+| maxReadBufferSize | int | The maximum size of the buffer used to read
incomming data | 65536 bytes |
+| minReadBufferSize | int | The minimal size of the buffer used to read
incomming data | 64 bytes |
+| readBufferSize | int | The default size of the buffer used to read incomming
data | 2048 bytes |
+| throughputCalculationInterval | int | The interval (seconds) between each
throughput calculation. | 3s |
+| useReadOperation | boolean | A flag set to TRUE when we allow an application
to do a __session.read()_ | FALSE |
+| writeTimeout | int | Delay to wait for completion before bailing out a write
operation | 60s |
+
+All those parameters can be accessed through the use of getters and setters
(the _useReadOperation_ parameter getter is using the _isUseReadOperation()_
method).
+
+## Socket specific parameters
+
+|| Parameter || type || Description || Default value ||
+| defaultReuseAddress | boolean | The value for the SO_REUSEADDR flag | true |
+| keepAlive | boolean | The value for the SO_KEEPALIVE flag | false |
+| oobInline | boolean | The value for the SO_OOBINLINE flag | false |
+| receiveBufferSize | int | The value for the SO_RCVBUF parameter | -1 |
+| reuseAddress | boolean | The value for the SO_REUSEADDR flag | false |
+| sendBufferSize | int | The value for the SO_SNDBUF parameter | -1 |
+| soLinger | int | The value for the SO_LINGER parameter | -1 |
+| tcpNoDelay | boolean | The value for the TCP_NODELAY flag | false |
+| trafficClass | int | The value for the IP_TOS parameter. One of
IPTOS_LOWCOST(0x02), IPTOS_RELIABILITY(0x04), IPTOS_THROUGHPUT (0x08) or
IPTOS_LOWDELAY (0x10) | 0 |
+
+## Datagram specific parameters
+
+|| Parameter || type || Description || Default value ||
+| broadcast | boolean | The value for the SO_BROADCAST flag | false |
+| closeOnPortUnreachable | boolean | Tells if we should close the session if
the port is unreachable | true |
+| receiveBufferSize | int | The value for the SO_RCVBUF parameter | -1 |
+| reuseAddress | boolean | The value for the SO_REUSEADDR flag | false |
+| sendBufferSize | int | The value for the SO_SNDBUF parameter | -1 |
+| trafficClass | int | The value for the IP_TOS parameter. One of
IPTOS_LOWCOST(0x02), IPTOS_RELIABILITY(0x04), IPTOS_THROUGHPUT (0x08) or
IPTOS_LOWDELAY (0x10) | 0 |
+
+## Serial specific parameters
+
+|| Parameter || type || Description || Default value ||
+| inputBufferSize | int | The input buffer size to use | 8 |
+| lowLatency | boolean | Set the Low Latency mode | false |
+| outputBufferSize | int | The ouput buffer size to use | 8 |
+| receiveThreshold | int | Set the receive threshold in byte (set it to -1 for
disable) | -1 |
+
Propchange:
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.1-session-configuration.mdtext
------------------------------------------------------------------------------
svn:executable = *
Added:
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.2-session-statistics.mdtext
URL:
http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.2-session-statistics.mdtext?rev=1761541&view=auto
==============================================================================
---
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.2-session-statistics.mdtext
(added)
+++
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.2-session-statistics.mdtext
Tue Sep 20 09:16:40 2016
@@ -0,0 +1,41 @@
+Title: Chapter 4.2 - Session Statistics
+NavUp: ch4-session.html
+NavUpText: Chapter 4 - Session
+NavPrev: ch4.1-session-configuration.html
+NavPrevText: Chapter 4.1 - Session Configuration
+NavNext: ../ch5-filters/ch5-filters.html
+NavNextText: Chapter 5 - Filters
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Chapter 4.2 - Session Statistics
+
+We keep some statistics in each sessions about what's going on. Not all those
statistics are computed fr every message though : some of them are computed on
demand.
+
+|| Parameter || Type || Description || automatic ||
+| readBytes | long | The total number of bytes read since the session was
created | yes |
+| readBytesThroughput | double | The number of bytes read per second in the
last interval | no |
+| readMessages | long | The total number of messages read since the session
was created | yes |
+| readMessagesThroughput | double | The number of messages read per second in
the last interval | no |
+| scheduledWriteBytes | AtomicInteger | The number of bytes waiting to be
written | yes |
+| scheduledWriteMessages | AtomicInteger | The number of messages waiting to
be written | yes |
+| writtenBytes | long | The total number of bytes written since the session
was created | yes |
+| writtenBytesThroughput | double | The number of bytes written per second in
the last interval | no |
+| writtenMessages | long | The total number of messages written since the
session was created | yes |
+| writtenMessagesThroughput | double | The number of messages written per
second in the last interval | no |
+
+All those parameters can be read using getters.
\ No newline at end of file
Propchange:
mina/site/trunk/content/mina-project/userguide/ch4-session/ch4.2-session-statistics.mdtext
------------------------------------------------------------------------------
svn:executable = *
Modified: mina/site/trunk/content/mina-project/userguide/user-guide-toc.mdtext
URL:
http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/user-guide-toc.mdtext?rev=1761541&r1=1761540&r2=1761541&view=diff
==============================================================================
--- mina/site/trunk/content/mina-project/userguide/user-guide-toc.mdtext
(original)
+++ mina/site/trunk/content/mina-project/userguide/user-guide-toc.mdtext Tue
Sep 20 09:16:40 2016
@@ -24,6 +24,8 @@ Part I - Basics
* [Chapter 2 - Basics](ch2-basics/ch2-basics.html)
* [Chapter 3 - Service](ch3-service/ch3-service.html)
* [Chapter 4 - Session](ch4-session/ch4-session.html)
+ * [Chapter 4.1 - Session
Configuration](ch4-session/ch4.1-session-configuration.html)
+ * [Chapter 4.2 - Session
Statistics](ch4-session/ch4.2-session-statistics.html)
* [Chapter 5 - Filters](ch5-filters/ch5-filters.html)
* [Chapter 6 - Transports](ch6-transports/ch6-transports.html)
* [Chapter 7 - Handler](ch7-handler/ch7-handler.html)
