src/site/fml/faq.fml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed 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.
 */
 -->

<faqs title="Frequently Asked Questions">

  <part id="general">
    <title>General</title>

    <faq id="definition">
      <question>What does MINA mean?</question>
      <answer>
        <p>
          MINA is:
          <ul>
            <li>an acronym for 'Multipurporse 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>
          </ul>
        </p>
      </answer>
    </faq>

    <faq id="versions">
      <question>Which version of MINA should I use?</question>
      <answer>
        <p>
          MINA uses Linux-like version numbers.  There are currently two
          streams in MINA; 0.7 and 0.9:
          <ul>
            <li>0.7 is the first public release of MINA.</li>
            <li>0.8 is the official stable release of 0.7.</li>
            <li>0.9 has richer features and cleaner API than 0.8.</li>
            <li>1.0 is the official stable release of 0.9</li>
          </ul>
        </p>
        <p>
          Here are the general rules for choosing an appropriate release:
          <ul>
            <li>Prefer the latest release with even version numbers to with
                odd ones.</li>
            <li>Try the latest release with odd version numbers if there are
                missing features in the stable release.</li>
          </ul>
        </p>
      </answer>
    </faq>

    <faq id="requirements">
      <question>What is required to build/run MINA?</question>
      <answer>
        <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 depends on <a href="http://www.slf4j.org">SLF4J (Simple Logging
          Facade for Java)</a>, a logging framework from the author of
          <a href="http://logging.apache.org/log4j/docs/index.html">Log4J</a>.
          SLF4J is very similar to
          <a href="http://jakarta.apache.org/commons/logging/">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>
      </answer>
    </faq>

    <faq id="support">
      <question>How can I get help?</question>
      <answer>
        <p>
          The primary source to get help is the documentation.  Please
          take a look at <a href="getting_started.html">Getting Started</a>
          section.
        </p>
        <p>
          You can also contact us via <a href="mail-lists.html">the mailing 
          list</a> or <a href="http://gleamynode.net/dev/forum/list.php?1">the
          support forum</a> to ask questions on MINA or to contribute to it.
          Please do not send messages to the authors directly.
        </p>
        <p>
          If you've found some problem in MINA, please report the bug using
          <a href="http://issues.apache.org/jira/browse/DIRMINA">our bug
          reporting system</a>.  A step-by-step instruction to reproduce the bug
          or JUnit test case code is appreciated.
        </p>
      </answer>
    </faq>
    
    <faq id="contribution">
      <question>How / What can I contribute?</question>
      <answer>
        <p>
          You can contribute anything related with MINA; examples, useful
          codecs for existing protocols, tutorials, feature improvements,
          bug fixes, benchmarks, and whatever.  Please contact us via
          <a href="mail-lists.html">the mailing list</a> or
          <a href="http://gleamynode.net/dev/forum/list.php?1">the support 
          forum</a>.
        </p>
      </answer>
    </faq>
  </part>
  
  <part id="features">
    <title>Can MINA ...?</title>

    <faq id="client-api">
      <question>
        Can I use MINA to create client applications?
      </question>
      <answer>
        <p>
          Yes.  You can create both client and server applications with MINA.
          Please take a look at <tt>IoConnector</tt> and
          <tt>ProtocolConnector</tt>.
        </p>
      </answer>
    </faq>

    <faq id="text-protocols">
      <question>
        Can MINA handle text protocols such as HTTP?
      </question>
      <answer>
        <p>
          Yes.  Please take a look at <a target="classFrame" href="xref-examples/org/apache/mina/examples/reverser/package-summary.html">Reverser</a> and <a target="classFrame" href="xref-examples/org/apache/mina/examples/httpserver/package-summary.html">HTTP server</a> example.
        </p>
      </answer>
    </faq>

    <faq id="binary-protocols">
      <question>
        Can MINA handle complex binary protocols such as LDAP?
      </question>
      <answer>
        <p>
          Yes.  Please take a look at <a target="classFrame" href="xref-examples/org/apache/mina/examples/sumup/package-summary.html">SumUp</a> example.
          There is also <a href="http://directory.apache.org/subprojects/asn1/">Apache ASN.1</a> project which provides ASN.1 codec for MINA.
        </p>
      </answer>
    </faq>
    
    <faq id="keep-alive">
      <question>
        Can I implement protocols that keeps connection alive with MINA?
      </question>
      <answer>
        <p>
          Yes.  MINA doesn't close any connections unless you called
          <tt>Session.close()</tt> or connection is closed by the remote peer.
        </p>
      </answer>
    </faq>
    
    <faq id="tls-and-sasl">
      <question>
        Does MINA support TLS and SASL out-of-the-box?
      </question>
      <answer>
        <p>
          Not yet.  We're going to provide an easy way to implement TLS
          and SASL in version 0.9.
        </p>
      </answer>
    </faq>

    <faq id="handler-synchronization">
      <question>
        Do I need to make my IoHandler thread-safe?
      </question>
      <answer>
        <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, and the newer event is not processed if the
          event handler method for the older event for the same session didn't
          return yet because MINA uses leader-followers thread pool by default.
        </p>
      </answer>
    </faq>

    <faq id="other-transport-types">
      <question>
        What transport types can MINA support except TCP/IP and UDP/IP?
      </question>
      <answer>
        <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 is planned.
        </p>
      </answer>
    </faq>

    <faq id="multicast">
      <question>
        Does MINA support multicast?
      </question>
      <answer>
        <p>
          Not yet.  Java NIO doesn't support multicast yet.  Multicast for NIO
          will be available in Java 6, Mustang.  We are seriously considering
          to implement multicasts using pre-1.4 Java API.
        </p>
      </answer>
    </faq>
  </part>
  
  <part id="howto">
    <title>How do I ...?</title>

    <faq id="per-session-data">
      <question>
        How can I store session-specific information?
      </question>
      <answer>
        <p>
          Sessions are capable of custom attributes that users can add or
          remove at any time.  These custom attributes are not shared between
          sessions; it is designed to store session specific information.
        </p>
      </answer>
    </faq>
    
    <faq id="demuxing-messages">
      <question>
        How can I separate an event handler into multiple handlers when I
        implement complex business logic?
      </question>
      <answer>
        <p>
          Please refer to DemuxingIoHandler (or DemuxingProtocolHandler).
          <a target="classFrame" href="xref-examples/org/apache/mina/examples/sumup/package-summary.html">SumUp</a> example
          demonstrates the usage.
        </p>
      </answer>
    </faq>
    
    <faq id="reconnect-to-server">
      <question>
        How can I reconnect to server after my client session is closed.
      </question>
      <answer>
        <p>
          Here is an example code:
<source>
public void sessionClosed( ProtocolSession session ) throws Exception
{
    // Wait for five seconds before reconnecting; you'll have to perform
    // reconnection in other thread if you're using MINA 0.7 or 0.8.
    // (You don't need to do if you're using MINA 0.9 or above.)
    Thread.sleep( 5000 ); 
    
    // Reconnect.
    connector.connect( session.getRemoteAddress(), this );
}
</source>
        </p>
        <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>
      </answer>
    </faq>
    
    <faq id="when-use-filter">
      <question>
        When should I implement my protocol handler using filters?
      </question>
      <answer>
        <p>
          Filters (both <tt>IoFilter</tt> and <tt>ProtocolFilter</tt>) are
          usually considered reusable just like we think 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
          <a href="http://jakarta.apache.org/commons/chain/">Apache Jakarta
          Commons Chain</a> as an alternative.
        </p>
      </answer>
    </faq>
    
    <faq id="message-timeout">
      <question>
        How can I detect when the remote peer doesn't send a response message
        for my request message?
      </question>
      <answer>
        You can't use <tt>sessionIdle</tt> event simply here.  You'll have to
        use <tt>java.util.Timer</tt> and <tt>java.util.TimerTask</tt> (or 
        <a href="http://www.opensymphony.com/quartz/">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.
      </answer>
    </faq>
    
    <faq id="adding-filters-per-session">
      <question>
        How can I add filters to a specific session or port?
      </question>
      <answer>
        There is <tt>IoSession.getFilterChain()</tt> and
        <tt>ProtocolSession.getFilterChain()</tt> that returns
        <tt>IoFilterChain</tt> and <tt>ProtocolFilterChain</tt> respectively.
        You can add any session-specific filters using the returned chain.
        But you cannot add port-specific filters right now.  You'll have to
        create more than one <tt>IoAcceptor</tt> or <tt>ProtocolAcceptor</tt>
        because each acceptors have one filter chain you can adjust.
      </answer>
    </faq>

    <faq id="logging-framework">
      <question>
        How can I let MINA log messages using my favorite logging framework (i.e. Log4J)?
      </question>
      <answer>
        MINA depends on <a href="http://www.slf4j.org">SLF4J (Simple Logging
        Facade for Java)</a>, a logging framework from the author of
        <a href="http://logging.apache.org/log4j/docs/index.html">Log4J</a>.
        SLF4J is very similar to
        <a href="http://jakarta.apache.org/commons/logging/">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.
      </answer>
    </faq>
  </part>
  
  <part id="troubleshooting">
    <title>Troubleshooting</title>
    
    <faq id="connection-reset">
      <question>
        I get response timeout and connection reset under heavy load.
      </question>
      <answer>
        <p>
          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>
      </answer>
    </faq>
    
    <faq id="no-data-written">
      <question>
        No data is writtin out to the session even if the buffer is not empty.
      </question>
      <answer>
        <p>
          Please check 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>
      </answer>
    </faq>
    
    <faq id="ssl-client-hangs">
      <question>
        I created an SSL client with MINA, but it doesn't initiate any handshake
        after the session is open.
      </question>
      <answer>
        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.
      </answer>
    </faq>
  </part>
</faqs>