[prev in list] [next in list] [prev in thread] [next in thread]
List: mina-commits
Subject: [CONF] Apache MINA > FAQ
From: confluence () apache ! org
Date: 2010-01-15 17:44:00
Message-ID: 976489502.642.1263577440155.JavaMail.www-data () brutus ! apache ! org
[Download RAW message or body]
<html>
<head>
<base href="http://cwiki.apache.org/confluence">
<link rel="stylesheet" \
href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=MINA&forWysiwyg=true" \
type="text/css"> </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="http://cwiki.apache.org/confluence/display/MINA/FAQ">FAQ</a></h2>
<h4>Page <b>edited</b> by <a \
href="http://cwiki.apache.org/confluence/display/~elecharny">Emmanuel LÃ �charny</a> \
</h4>
Added some direction on how to close a session and dispose the connector
<div id="versionComment" class="noteMacro" style="display:none; padding: \
5px;">
Added some direction on how to close a session and dispose the connector<br />
</div>
<br/>
<div class="notificationGreySide">
<h2><a name="FAQ-TableofContents"></a>Table of Contents</h2>
<div>
<ul>
<li><a href='#FAQ-TableofContents'>Table of Contents</a></li>
<li><a href='#FAQ-General'>General</a></li>
<ul>
<li><a href='#FAQ-WhatdoesMINAmean%3F'>What does MINA mean?</a></li>
<li><a href='#FAQ-WhattransportdoesMINAsupport%3F'>What transport does MINA \
support?</a></li> <li><a href='#FAQ-HowdoesMINAperform%3F'>How does MINA \
perform?</a></li> <li><a href='#FAQ-WhichversionofMINAshouldIuse%3F'>Which version \
of MINA should I use?</a></li> <li><a \
href='#FAQ-Whatisrequiredtobuild%2FrunMINA%3F'>What is required to build/run \
MINA?</a></li> <li><a href='#FAQ-HowcanIgethelp%3F'>How can I get help?</a></li>
<li><a href='#FAQ-How%2FWhatcanIcontribute%3F'>How / What can I \
contribute?</a></li> </ul>
<li><a href='#FAQ-CanMINA...%3F'>Can MINA...?</a></li>
<ul>
<li><a href='#FAQ-CanIuseMINAtocreateclient%28orserver%29applications%3F'>Can I \
use MINA to create client (or server) applications?</a></li> <li><a \
href='#FAQ-CanMINAhandletextprotocolssuchasHTTP%3F'>Can MINA handle text protocols \
such as HTTP?</a></li> <li><a \
href='#FAQ-CanMINAhandlecomplexbinaryprotocolssuchasLDAP%3F'>Can MINA handle complex \
binary protocols such as LDAP?</a></li> <li><a \
href='#FAQ-CanIimplementprotocolsthatkeepsconnectionalivewithMINA%3F'>Can I implement \
protocols that keeps connection alive with MINA?</a></li> <li><a \
href='#FAQ-DoesMINAsupportSSL%2FTLSandSASLoutofthebox%3F'>Does MINA support SSL/TLS \
and SASL out-of-the-box?</a></li> <li><a \
href='#FAQ-DoIneedtomakemyIoHandlerthreadsafe%3F'>Do I need to make my IoHandler \
thread-safe?</a></li> <li><a \
href='#FAQ-WhattransporttypescanMINAsupportexceptTCP%2FIPandUDP%2FIP%3F'>What \
transport types can MINA support except TCP/IP and UDP/IP?</a></li> <li><a \
href='#FAQ-DoesMINAsupportmulticast%3F'>Does MINA support multicast?</a></li> </ul>
<li><a href='#FAQ-HowdoI...%3F'>How do I...?</a></li>
<ul>
<li><a href='#FAQ-HowcanIstoresessionspecificinformation%3F'>How can I store \
session-specific information?</a></li> <li><a \
href='#FAQ-HowcanIseparateaneventhandlerintomultiplehandlerswhenIimplementcomplexbusinesslogic%3F'>How \
can I separate an event handler into multiple handlers when I implement complex \
business logic?</a></li> <li><a \
href='#FAQ-HowdoIclosemysessionsanddisposemyConnector%3F'>How do I close my sessions \
and dispose my Connector ?</a></li> <li><a \
href='#FAQ-WhenshouldIimplementmyprotocolhandlerusingfilters%3F'>When should I \
implement my protocol handler using filters?</a></li> <li><a \
href='#FAQ-HowcanIdetectwhentheremotepeerdoesn%27tsendaresponsemessageformyrequestmessage%3F'>How \
can I detect when the remote peer doesn't send a response message for my request \
message?</a></li> <li><a \
href='#FAQ-HowcanIletMINAlogmessagesusingmyfavoriteloggingframework%28i.e.Log4J%29%3F'>How \
can I let MINA log messages using my favorite logging framework (i.e. \
Log4J)?</a></li> </ul>
<li><a href='#FAQ-Troubleshooting'>Troubleshooting</a></li>
<ul>
<li><a href='#FAQ-Iget%7B%7BOutOfMemoryError%7D%7Dorresponsetimeoutandconnectionresetunderheavyload.'>I \
get <tt>OutOfMemoryError</tt> or response timeout and connection reset under heavy \
load.</a></li> <li><a \
href='#FAQ-Nodataiswrittinouttothesessionevenifthebufferisnotempty.'>No data is \
writtin out to the session even if the buffer is not empty.</a></li> <li><a \
href='#FAQ-IcreatedanSSLclientwithMINA%2Cbutitdoesn%27tinitiateanyhandshakeafterthesessionisopen.'>I \
created an SSL client with MINA, but it doesn't initiate any handshake after the \
session is open.</a></li> <li><a \
href='#FAQ-WhydoesSocketConnectorsendseveralmessagesasonemessage%3F'>Why does \
SocketConnector send several messages as one message?</a></li> <li><a \
href='#FAQ-Iget%7B%7BInvalidClassChangeError%7D%7D.'>I get \
<tt>InvalidClassChangeError</tt>.</a></li> <li><a \
href='#FAQ-Myserverfailswithjava.net.SocketException%3AToomanyfilesopen'>My server \
fails with java.net.SocketException: Too many files open</a></li> <ul>
<li><a href='#FAQ-ChangethetimeoutinWindows'>Change the timeout in \
Windows</a></li> <li><a href='#FAQ-ChangethetimeoutinLinux'>Change the timeout in \
Linux</a></li> </ul>
</ul>
</ul></div>
<h2><a name="FAQ-General"></a>General</h2>
<h3><a name="FAQ-WhatdoesMINAmean%3F"></a>What does MINA mean?</h3>
<p>MINA is:</p>
<ul>
<li>an acronym for 'Multipurpose Infrastructure for Network Applications'</li>
<li>A girl's name</li>
<li>'South' in Japanese</li>
<li>'Mine' (as in mineshaft) in Spanish and Portuguese</li>
<li>Look at <a href="http://en.wikipedia.org/wiki/Mina" rel="nofollow">here</a> for \
more meanings.</li> </ul>
<h3><a name="FAQ-WhattransportdoesMINAsupport%3F"></a>What transport does MINA \
support?</h3>
<p>MINA currently supports TCP and UDP based on Java NIO API, provides support for \
serial port communication, and transports based on <a href="http://apr.apache.org/" \
rel="nofollow">Apache Portable Runtime</a>.</p>
<h3><a name="FAQ-HowdoesMINAperform%3F"></a>How does MINA perform?</h3>
<p>It is known to perform as good as C/C++ servers. Please refer to the <a \
href="/confluence/display/MINA/Performance+Test+Reports" title="Performance Test \
Reports">Performance Test Reports</a> or the <a \
href="/confluence/display/MINA/Testimonials" \
title="Testimonials">Testimonials</a>.</p>
<h3><a name="FAQ-WhichversionofMINAshouldIuse%3F"></a>Which version of MINA should I \
use?</h3>
<p>Use the latest point-release of 1.0 (for Java 1.4) or 2.0 (for Java 5 or above). \
1.0 and 1.1 aren't maintained anymore, unless someone propose some patches.</p>
<h3><a name="FAQ-Whatisrequiredtobuild%2FrunMINA%3F"></a>What is required to \
build/run MINA?</h3>
<p>JDK 1.5 or above is required to build MINA. But MINA runs perfect with JDK 1.4 \
only if you don't use SSLFilter which uses Java 5 SSLEngine. This means JDK 1.5 or \
above is required for you to use SSL with MINA.</p>
<p>MINA core module depends on two libraries, SLF4J and backport-util-concurrent (for \
1.0):</p>
<p><a href="http://www.slf4j.org/" rel="nofollow">SLF4J (Simple Logging Facade for \
Java)</a>, a logging framework from the author of <a \
href="http://logging.apache.org/log4j/docs/index.html" rel="nofollow">Log4J</a>. \
SLF4J is very similar to <a href="http://jakarta.apache.org/commons/logging/" \
rel="nofollow">Commons-Logging</a>, but it doesn't cause any class loader issues at \
all. SLF4J provides bindings for Log4J, JDK 1.4 logging API, and NLog4J. Please put \
an appropriate SLF4J JAR file which corresponds to your favorite logging framework to \
the classpath as SLF4J documentation explains.</p>
<p><a href="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/" \
rel="nofollow">backport-util-concurrent</a> is a backport implementation of \
<tt>java.util.concurrent</tt> package which was introduced in JDK 1.5. MINA 1.0 uses \
it to retain the runtime compatibility with JDK 1.4. Please note that MINA 1.1 or \
above depends on <tt>java.util.concurrent</tt> package directly, and therefore \
doesn't depend on it anymore.</p>
<p><a href="http://www.springframework.org/" rel="nofollow">Spring framework</a> and \
<a href="http://www.jcraft.com/jzlib/" rel="nofollow">JZlib</a> are also required to \
build <tt>integration-spring</tt> and <tt>filter-compression</tt> module.</p>
<h3><a name="FAQ-HowcanIgethelp%3F"></a>How can I get help?</h3>
<p>The primary source to get help is the <a \
href="/confluence/display/MINA/Documentation" \
title="Documentation">documentation</a>. You can also contact us via <a \
href="/confluence/display/MINA/Contact" title="Contact">various channels</a> to ask \
questions on MINA or to contribute to it.</p>
<h3><a name="FAQ-How%2FWhatcanIcontribute%3F"></a>How / What can I contribute?</h3>
<p>You can contribute anything related with MINA; examples, useful codecs for \
existing protocols, tutorials, feature improvements, bug fixes, benchmarks, and \
whatever. Please <a href="/confluence/display/MINA/Contact" title="Contact">contact \
us</a> without hesitation.</p>
<h2><a name="FAQ-CanMINA...%3F"></a>Can MINA...?</h2>
<h3><a name="FAQ-CanIuseMINAtocreateclient%28orserver%29applications%3F"></a>Can I \
use MINA to create client (or server) applications?</h3>
<p>Yes. You can create both client and server applications with MINA. Please take a \
look at <tt>IoConnector</tt> and <tt>IoAcceptor</tt>.</p>
<h3><a name="FAQ-CanMINAhandletextprotocolssuchasHTTP%3F"></a>Can MINA handle text \
protocols such as HTTP?</h3>
<p>Yes. Please take a look at <a href="/confluence/display/MINA/Documentation" \
title="Documentation">the Reversed and HTTP server examples</a>. <a \
href="http://asyncweb.safehaus.org/" rel="nofollow">AsyncWeb</a> is a HTTP server \
implementation based on MINA.</p>
<h3><a name="FAQ-CanMINAhandlecomplexbinaryprotocolssuchasLDAP%3F"></a>Can MINA \
handle complex binary protocols such as LDAP?</h3>
<p>Yes. Please take a look at <a href="/confluence/display/MINA/Documentation" \
title="Documentation">the SumUp example</a>. There is no full ASN.1 support yet, but \
we will implement it someday and you can contribute to make it available sooner.</p>
<h3><a name="FAQ-CanIimplementprotocolsthatkeepsconnectionalivewithMINA%3F"></a>Can I \
implement protocols that keeps connection alive with MINA?</h3>
<p>Yes. MINA doesn't close any connections unless you called \
<tt>IoSession.close()</tt> or connection is closed by the remote peer.</p>
<h3><a name="FAQ-DoesMINAsupportSSL%2FTLSandSASLoutofthebox%3F"></a>Does MINA support \
SSL/TLS and SASL out-of-the-box?</h3>
<p>We support SSL/TLS out-of-the-box. Please refer to <tt>SSLFilter</tt>. It also \
provides a way to implement <tt>StartTLS</tt>. JDK 1.5 provides complete SASL \
support which works well with MINA.</p>
<h3><a name="FAQ-DoIneedtomakemyIoHandlerthreadsafe%3F"></a>Do I need to make my \
IoHandler thread-safe?</h3>
<p>It depends on your implementation. If you access the resource which is shared \
across multiple sessions, you have to make it thread-safe. If the resource is not \
shared at all and accessed by only one session (e.g. storing context information as a \
session attribute), then you don't need to make it thread-safe. It is because all \
events generated by MINA are transmitted to your handler in order (when using the \
Executor Filter), and the newer event is not processed if the event handler method \
for the older event for the same session hasn't returned yet.</p>
<h3><a name="FAQ-WhattransporttypescanMINAsupportexceptTCP%2FIPandUDP%2FIP%3F"></a>What \
transport types can MINA support except TCP/IP and UDP/IP?</h3>
<p>Virtually all kind of transport types. MINA API is designed to be \
transport-independent. You can implement any transport type support only if you can \
conform to MINA API. Support for Pre-1.4 I/O (aka BIO), reliable multicast, Java \
Communications API, and file I/O are planned.</p>
<h3><a name="FAQ-DoesMINAsupportmulticast%3F"></a>Does MINA support multicast?</h3>
<p>Not yet. Java NIO doesn't support multicast yet. Multicast for NIO will be \
available in Java SE 7, Dolphin. We are seriously considering to implement multicasts \
using pre-1.4 Java API.</p>
<h2><a name="FAQ-HowdoI...%3F"></a>How do I...?</h2>
<h3><a name="FAQ-HowcanIstoresessionspecificinformation%3F"></a>How can I store \
session-specific information?</h3>
<p>Sessions are capable of custom attributes that you can add or remove at any time. \
These custom attributes are not shared between sessions; it is designed to store \
session specific information.</p>
<h3><a name="FAQ-HowcanIseparateaneventhandlerintomultiplehandlerswhenIimplementcomplexbusinesslogic%3F"></a>How \
can I separate an event handler into multiple handlers when I implement complex \
business logic?</h3>
<p>Please refer to <tt>DemuxingIoHandler</tt>.</p>
<h3><a name="FAQ-HowdoIclosemysessionsanddisposemyConnector%3F"></a>How do I close my \
sessions and dispose my Connector ?</h3> <p>You have to do it in two steps : first \
close your sessions, then dispose the connector. Of course, if you dispose your \
Connector first, then all the sessions will be closed. Here is the code :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent \
panelContent"> <pre class="code-java">
ConnectFuture cf = connector.connect(<span class="code-keyword">new</span> \
InetSocketAddress(<span class="code-quote">"localhost"</span>, 8080));
<span class="code-comment">// Get the close <span \
class="code-keyword">future</span> <span class="code-keyword">for</span> <span \
class="code-keyword">this</span> session </span> CloseFuture closeFuture = \
cf.getSession().getCloseFuture();
<span class="code-comment">// Adding a listener to <span \
class="code-keyword">this</span> close event </span> \
closeFuture.addListener((IoFutureListener<?>) <span \
class="code-keyword">new</span> IoFutureListener<IoFuture>() { @Override
<span class="code-keyword">public</span> void operationComplete(IoFuture \
<span class="code-keyword">future</span>) {
<span class="code-object">System</span>.out.println(<span \
class="code-quote">"The session is now closed"</span>); }
});
<span class="code-comment">// Do the close requesting that the pending messages \
are sent before </span> <span class="code-comment">// the session is closed
</span> closeFuture.getSession().close(<span class="code-keyword">false</span>);
<span class="code-comment">// Now wait <span class="code-keyword">for</span> the \
close to be completed </span> closeFuture.awaitUninterruptibly();
<span class="code-comment">// We can now dispose the connector
</span> connector.dispose();
{code:java}
h3. How can I reconnect to server after my client session is closed.
Here is an example code:
{code:java}
<span class="code-keyword">public</span> void sessionClosed( IoSession session ) \
<span class="code-keyword">throws</span> Exception { <span class="code-comment">// \
Wait <span class="code-keyword">for</span> five seconds before reconnecting. </span> \
<span class="code-object">Thread</span>.sleep( 5000 );
<span class="code-comment">// Reconnect.
</span> connector.connect( session.getRemoteAddress(), <span \
class="code-keyword">this</span> ); }
</pre>
</div></div>
<p>Possibly it would be better to extract this code to a method like 'reconnect()' so \
that it can reusable in more than one place.</p>
<h3><a name="FAQ-WhenshouldIimplementmyprotocolhandlerusingfilters%3F"></a>When \
should I implement my protocol handler using filters?</h3>
<p><tt>IoFilter</tt> is usually considered reusable just like we think about Servlet \
filters. Please implement commonly used business logic such as authorization and \
logging as a filter. In case you implement just complex multi-layer protocols like \
Kerberos, you could consider using <tt>org.apache.mina.handler.chain</tt> \
package.</p>
<h3><a name="FAQ-HowcanIdetectwhentheremotepeerdoesn%27tsendaresponsemessageformyrequestmessage%3F"></a>How \
can I detect when the remote peer doesn't send a response message for my request \
message?</h3>
<p>You can't use <tt>sessionIdle event</tt> simply here. You'll have to use \
<tt>java.util.concurrent.ScheduledExecutor</tt> (or <a \
href="http://www.opensymphony.com/quartz/" rel="nofollow">OpenSymphony Quartz</a> as \
an alternative). Schedule a timeout task to be executed on timeout situation for each \
request message, and cancel it when you receive the corresponding response \
message.</p>
<h3><a name="FAQ-HowcanIletMINAlogmessagesusingmyfavoriteloggingframework%28i.e.Log4J%29%3F"></a>How \
can I let MINA log messages using my favorite logging framework (i.e. Log4J)?</h3>
<p>Please refer to 'Swapping implementations at deployment time' section in <a \
href="http://www.slf4j.org/manual.html" rel="nofollow">the SLF4J Manual</a>.</p>
<h2><a name="FAQ-Troubleshooting"></a>Troubleshooting</h2>
<h3><a name="FAQ-Iget%7B%7BOutOfMemoryError%7D%7Dorresponsetimeoutandconnectionresetunderheavyload."></a>I \
get <tt>OutOfMemoryError</tt> or response timeout and connection reset under heavy \
load.</h3>
<p>We recommend to switch the default buffer type to 'heap' by inserting the \
following code before you start a server:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent \
panelContent"> <pre class="code-java">
ByteBuffer.setUseDirectBuffers(<span class="code-keyword">false</span>);
ByteBuffer.setAllocator(<span class="code-keyword">new</span> \
SimpleByteBufferAllocator()); </pre>
</div></div>
<p>If you prefer direct buffers to heap buffers, JVM might have ran out of direct \
memory. Please try increasing maximum direct memory size using \
<tt>-XX:MaxDirectMemorySize</tt> option (e.g. \
<tt>-XX:MaxDirectMemorySize=128M</tt>)</p>
<h3><a name="FAQ-Nodataiswrittinouttothesessionevenifthebufferisnotempty."></a>No \
data is writtin out to the session even if the buffer is not empty.</h3>
<p>Please make sure if you called <tt>ByteBuffer.flip()</tt> to flip the buffer \
before writing the buffer out. It is a common mistake NIO beginners make.</p>
<h3><a name="FAQ-IcreatedanSSLclientwithMINA%2Cbutitdoesn%27tinitiateanyhandshakeafterthesessionisopen."></a>I \
created an SSL client with MINA, but it doesn't initiate any handshake after the \
session is open.</h3>
<p>Please make sure you called <tt>SSLFilter.setUseClientMode(true)</tt> before you \
initiate a connection. Server developers will also have to disconnect users who \
doesn't initiate SSL handshake by setting <tt>IoSession.readerIdleTime</tt> and \
closing the session in <tt>IoHandler.sessionIdle()</tt>.</p>
<h3><a name="FAQ-WhydoesSocketConnectorsendseveralmessagesasonemessage%3F"></a>Why \
does SocketConnector send several messages as one message?</h3>
<p><em>For example, I tried using SocketConnector to send "abc" and "def", but it \
sent "abcdef". Is it a MINA bug?</em></p>
<p>No, this is due to your OS trying to send packets more efficiently (see <a \
href="http://en.wikipedia.org/wiki/Nagle_algorithm" \
rel="nofollow">http://en.wikipedia.org/wiki/Nagle_algorithm</a>). You can \
enable/disable Nagle's algorithm by a call to SocketSessionConfig.setTcpNoDelay(), \
e.g.:</p>
<p>((SocketSessionConfig) connector.getSessionConfig()).setTcpNoDelay(false)</p>
<p>However, even if you do this you cannot expect one session.write(bytes) in MINA to \
correspond to one TCP packet on your network. You should probably implement your own \
MINA ProtocolDecoder to handle the assembly of incoming bytes into message objects. \
The TextLineCodec is a good start if the protocol you're implementing is based on \
text lines. For a more advanced example have a look at the SumUp example in the MINA \
distribution.</p>
<h3><a name="FAQ-Iget%7B%7BInvalidClassChangeError%7D%7D."></a>I get \
<tt>InvalidClassChangeError</tt>.</h3>
<p>Please make sure if you are using the appropriate SLF4J version. You will get \
<tt>InvalidClassChangeError</tt> if you are using outdated SLF4J release.</p>
<h3><a name="FAQ-Myserverfailswithjava.net.SocketException%3AToomanyfilesopen"></a>My \
server fails with java.net.SocketException: Too many files open</h3>
<p>Network sockets are treated like files and your operating system has a limit to \
the number of file handles it can manage. Running out of file handles is usually due \
to a large number of clients connecting and disconnecting frequently. As specified by \
TCP, after being closed sockets remain in the TIME_WAIT state for some additional \
time. The reason is to ensure that delayed packets arrive on the correct socket. In \
Windows, the default TIME_WAIT timeout is 4 minutes, in Linux it is 60 seconds.</p>
<h4><a name="FAQ-ChangethetimeoutinWindows"></a>Change the timeout in Windows</h4>
<ol>
<li>Run regedit to start the Registry Editor</li>
<li>Locate the following key: \
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\tcpip\Parameters</li> <li>Add a \
new value named TcpTimedWaitDelay asa decimal and set the desired timeout in seconds \
(30-300)</li> <li>Reboot</li>
</ol>
<h4><a name="FAQ-ChangethetimeoutinLinux"></a>Change the timeout in Linux</h4>
<ol>
<li>Update the configuration value by running (30 seconds used in the example)</li>
</ol>
<p> echo 30 > /proc/sys/net/ipv4/tcp_fin_timeout</p>
<ol>
<li>Restart the networking component, for example by running</li>
</ol>
<p> /etc/init.d/networking restart</p>
<p> or</p>
<p> service network restart</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;">
<a href="http://cwiki.apache.org/confluence/users/viewnotifications.action" \
class="grey">Change Notification Preferences</a> </div>
<a href="http://cwiki.apache.org/confluence/display/MINA/FAQ">View Online</a>
|
<a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=29027&revisedVersion=21&originalVersion=20">View \
Change</a> |
<a href="http://cwiki.apache.org/confluence/display/MINA/FAQ?showComments=true&showCommentArea=true#addcomment">Add \
Comment</a> </div>
</div>
</div>
</div>
</div>
</body>
</html>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic