Return-Path: 
 <commits-return-5982-apmail-directory-commits-archive=directory.apache.org@directory.apache.org>
Delivered-To: apmail-directory-commits-archive@www.apache.org
Received: (qmail 97911 invoked from network); 6 Sep 2005 15:51:35 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 6 Sep 2005 15:51:35 -0000
Received: (qmail 38426 invoked by uid 500); 6 Sep 2005 15:51:34 -0000
Delivered-To: apmail-directory-commits-archive@directory.apache.org
Received: (qmail 38366 invoked by uid 500); 6 Sep 2005 15:51:34 -0000
Mailing-List: contact commits-help@directory.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@directory.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@directory.apache.org>
List-Post: <mailto:commits@directory.apache.org>
List-Id: <commits.directory.apache.org>
Reply-To: dev@directory.apache.org
Delivered-To: mailing list commits@directory.apache.org
Received: (qmail 38352 invoked by uid 99); 6 Sep 2005 15:51:34 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 06 Sep 2005 08:51:34 -0700
X-ASF-Spam-Status: No, hits=-9.2 required=10.0
	tests=ALL_TRUSTED,NO_REAL_NAME,URIBL_SBL
X-Spam-Check-By: apache.org
Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194)
    by apache.org (qpsmtpd/0.29) with SMTP; Tue, 06 Sep 2005 08:51:46 -0700
Received: (qmail 97879 invoked by uid 65534); 6 Sep 2005 15:51:31 -0000
Message-ID: <20050906155131.97878.qmail@minotaur.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r279025 - in /directory/network/trunk: project.xml
 xdocs/faq.fml
 xdocs/navigation.xml
Date: Tue, 06 Sep 2005 15:51:30 -0000
To: commits@directory.apache.org
From: trustin@apache.org
X-Mailer: svnmailer-1.0.5
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Author: trustin
Date: Tue Sep  6 08:51:25 2005
New Revision: 279025

URL: http://svn.apache.org/viewcvs?rev=279025&view=rev
Log:
Reflected the changes in branches/0.7 into trunk.


Added:
    directory/network/trunk/xdocs/faq.fml
Modified:
    directory/network/trunk/project.xml
    directory/network/trunk/xdocs/navigation.xml

Modified: directory/network/trunk/project.xml
URL: http://svn.apache.org/viewcvs/directory/network/trunk/project.xml?rev=279025&r1=279024&r2=279025&view=diff
==============================================================================
--- directory/network/trunk/project.xml (original)
+++ directory/network/trunk/project.xml Tue Sep  6 08:51:25 2005
@@ -157,6 +157,7 @@
     <report>maven-jdepend-plugin</report>
     <report>maven-simian-plugin</report>
     <report>maven-tasklist-plugin</report>
+    <report>maven-faq-plugin</report>
   </reports>
 
 </project>

Added: directory/network/trunk/xdocs/faq.fml
URL: http://svn.apache.org/viewcvs/directory/network/trunk/xdocs/faq.fml?rev=279025&view=auto
==============================================================================
--- directory/network/trunk/xdocs/faq.fml (added)
+++ directory/network/trunk/xdocs/faq.fml Tue Sep  6 08:51:25 2005
@@ -0,0 +1,341 @@
+<?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>
+          </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>
+      </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 IoHandler and ProtocolHandler thread-safe?
+      </question>
+      <answer>
+        <p>
+          You don't need to do because all events generated by MINA are
+          transmitted to your handlers 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 5, 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>
+  </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>
+  </part>
+</faqs>
+   

Modified: directory/network/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/directory/network/trunk/xdocs/navigation.xml?rev=279025&r1=279024&r2=279025&view=diff
==============================================================================
--- directory/network/trunk/xdocs/navigation.xml (original)
+++ directory/network/trunk/xdocs/navigation.xml Tue Sep  6 08:51:25 2005
@@ -20,8 +20,10 @@
      <item name="Overview" href="/index.html"/>
      <item name="Features" href="/features.html"/>
      <item name="Getting Started" href="/getting_started.html"/>
+     <item name="F.A.Q" href="/faq.html"/>
      <item name="Downloads" href="http://cvs.apache.org/repository/directory-network/"/>
      <item name="Roadmap" href="/roadmap.html"/>
+     <item name="Changes" href="http://issues.apache.org/jira/browse/DIRMINA?report=com.atlassian.jira.plugin.system.project:changelog-panel"/>
      <item name="History" href="/history.html"/>
    </menu>