You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by ap...@apache.org on 2012/10/11 14:35:57 UTC
svn commit: r1397022 - in /mina/site/trunk/content: mina/userguide/ch4/
mina/userguide/ch4/ch4.mdtext staticresources/images/mina/session-state.png
Author: apaliwal
Date: Thu Oct 11 12:35:57 2012
New Revision: 1397022
URL: http://svn.apache.org/viewvc?rev=1397022&view=rev
Log:
moved chapter 2
Added:
mina/site/trunk/content/mina/userguide/ch4/
mina/site/trunk/content/mina/userguide/ch4/ch4.mdtext
mina/site/trunk/content/staticresources/images/mina/session-state.png (with props)
Added: mina/site/trunk/content/mina/userguide/ch4/ch4.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina/userguide/ch4/ch4.mdtext?rev=1397022&view=auto
==============================================================================
--- mina/site/trunk/content/mina/userguide/ch4/ch4.mdtext (added)
+++ mina/site/trunk/content/mina/userguide/ch4/ch4.mdtext Thu Oct 11 12:35:57 2012
@@ -0,0 +1,137 @@
+Title: Chapter 4
+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.
+
+# Introduction
+
+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.
+
+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.
+
+## Session state
+
+A session has a state, which will evolve during time.
+
+* Connected : the session has been created and is available
+* Idle : the session hasn't processed any request for at least a period of time (this period is configurable)
+ * Idle for read : no read has actually been made for a period of time
+ * 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.
+
+The following state diagram exposes all the possible states and transitions :
+
+
+
+## Configuration
+
+Many different parameters can be set for a specific session :
+
+* receive buffer size
+* sending buffer size
+* Idle time
+* Write timeOut
+
+plus other configuration, depending on the transport type used (see Chapter 6 - Transports)
+
+## 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.
+
+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.
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ ...
+ <SPAN class="code-object">int</SPAN> counterValue = session.getAttribute( <SPAN class="code-quote">"counter"</SPAN> );
+ session.setAttribute( <SPAN class="code-quote">"counter"</SPAN>, counterValue + 1 );
+ ...
+</PRE>
+</DIV></DIV>
+
+We have a way to handle stored Attributes into the session : an Attribute is a key/value pair, which can be added, removed and read from the session's container.
+
+This container is created automatically when the session is created, and will be disposed when the session is terminated.
+
+## Defining the 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.
+
+This snippet of code shows how the container is created during the session initialization :
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+protected final void initSession(IoSession session,
+ IoFuture future, IoSessionInitializer sessionInitializer) {
+ ...
+ try {
+ ((AbstractIoSession) session).setAttributeMap(session.getService()
+ .getSessionDataStructureFactory().getAttributeMap(session));
+ } catch (IoSessionInitializationException e) {
+ throw e;
+ } catch (Exception e) {
+ throw new IoSessionInitializationException(
+ "Failed to initialize an attributeMap.", e);
+ }
+ ...
+</PRE>
+</DIV></DIV>
+
+and here is the factory interface we can implement if we want to define another kind of container :
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+public interface IoSessionDataStructureFactory {
+ /**
+ * Returns an {@link IoSessionAttributeMap} which is going to be associated
+ * with the specified <tt>session</tt>. Please note that the returned
+ * implementation must be thread-safe.
+ */
+ IoSessionAttributeMap getAttributeMap(IoSession session) throws Exception;
+}
+</PRE>
+</DIV></DIV>
+
+## 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.
+
+However, it's possible to dynamically modify the chain for a single session, for instance by adding a Logger Filter in the chain for a specific session.
+
+## Statistics
+
+Each session also keep a track of records about what has been done for the session :
+
+* number of bytes received/sent
+* number of messages received/sent
+* Idle status
+* throughput
+
+and many other useful informations.
+
+## 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 :
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+...
+ session.write( <your message> );
+ ...
+</PRE>
+</DIV></DIV>
Added: mina/site/trunk/content/staticresources/images/mina/session-state.png
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/staticresources/images/mina/session-state.png?rev=1397022&view=auto
==============================================================================
Binary file - no diff available.
Propchange: mina/site/trunk/content/staticresources/images/mina/session-state.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream