Author: buildbot
Date: Wed Oct 31 04:48:41 2012
New Revision: 836680
Log:
Staging update by buildbot for mina
Added:
websites/staging/mina/trunk/content/ (with props)
websites/staging/mina/trunk/content/mina/
websites/staging/mina/trunk/content/mina/userguide/
websites/staging/mina/trunk/content/mina/userguide/ch3-service/
websites/staging/mina/trunk/content/mina/userguide/ch3-service/acceptor.html
Propchange: websites/staging/mina/trunk/content/
------------------------------------------------------------------------------
cms:source-revision = 1403977
Added:
websites/staging/mina/trunk/content/mina/userguide/ch3-service/acceptor.html
==============================================================================
---
websites/staging/mina/trunk/content/mina/userguide/ch3-service/acceptor.html
(added)
+++
websites/staging/mina/trunk/content/mina/userguide/ch3-service/acceptor.html
Wed Oct 31 04:48:41 2012
@@ -0,0 +1,265 @@
+<!DOCTYPE html>
+<!--
+ 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.
+-->
+<html>
+<head>
+ <title>Chapter 8 - Acceptor — Apache MINA</title>
+
+ <link href="./../../../css/common.css" rel="stylesheet"
type="text/css">
+ <link href="./../../../css/mina.css" rel="stylesheet"
type="text/css">
+
+</head>
+ <body>
+ <div id="container">
+ <div id="header">
+ <div id="subProjectsNavBar">
+ <a href="./../../../">
+
+ Apache MINA Project
+
+ </a>
+ |
+ <a href="./../../../mina/index.html">
+
+ <strong>MINA</strong>
+
+ </a>
+ |
+ <a href="./../../../asyncweb/index.html">
+
+ AsyncWeb
+
+ </a>
+ |
+ <a href="./../../../ftpserver/index.html">
+
+ FtpServer
+
+ </a>
+ |
+ <a href="./../../../sshd/index.html">
+
+ Sshd
+
+ </a>
+ |
+ <a href="./../../../vysper/index.html">
+
+ Vysper
+
+ </a>
+ </div><!-- subProjectsNavBar -->
+ </div><!-- header -->
+ <div id="content">
+ <div id="leftColumn">
+
+
+
+
+ <div id="navigation">
+
+ <h5>Latest Downloads</h5>
+ <ul>
+ <li><a href="./../../../mina/downloads.html">Mina 2.0.7</a></li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li><a href="./../../../mina/userguide/user-guide-toc.html"
class="external-link" rel="nofollow">User guide</a></li>
+ <li><a href="./../../../mina/features.html" class="external-link"
rel="nofollow">Features</a/</li>
+ <li><a href="./../../../mina/road-map.html" class="external-link"
rel="nofollow">Road Map</a/</li>
+ <li><a href="./../../../mina/faq.html" class="external-link"
rel="nofollow">FAQ</a/</li>
+ </ul>
+ <h5>Resources</h5>
+ <ul>
+ <li><a href="./../../../mina/downloads.html" class="external-link"
rel="nofollow">Downloads</a></li>
+ <li><a href="./../../../mina/mailing-lists.html" class="external-link"
rel="nofollow">Mailing lists & IRC</a></li>
+ <li><a href="./../../../mina/issue-tracking.html" class="external-link"
rel="nofollow">Issue tracking</a></li>
+ <li><a href="./../../../mina/sources.html" class="external-link"
rel="nofollow">Sources</a></li>
+ <li><a href="./../../../mina/performances.html" class="external-link"
rel="nofollow">Performances</a></li>
+ <li><a href="./../../../mina/testimonials.html" class="external-link"
rel="nofollow">Testimonials</a></li>
+ <li><a href="./../../../mina/conferences.html" class="external-link"
rel="nofollow">Conferences</a></li>
+ <li><a href="./../../../mina/developper-guide.html"
class="external-link" rel="nofollow">Developers Guide</a></li>
+ <li><a href="./../../../mina/related-projects.html"
class="external-link" rel="nofollow">Related Projects</a></li>
+ <li><a
href="http://people.apache.org/~vgritsenko/stats/projects/mina.html";
class="external-link" rel="nofollow">Statistics</a></li>
+ </ul>
+
+ <h5>Community</h5>
+ <ul>
+ <li><a href="http://www.apache.org/foundation/contributing.html";
class="external-link" rel="nofollow">Contributing</a></li>
+ <li><a href="./../../../contributors.html" class="external-link"
rel="nofollow">Team</a></li>
+ <li><a href="./../../../special-thanks.html" class="external-link"
rel="nofollow">Special Thanks</a></li>
+ <li><a href="http://www.apache.org/security/"; class="external-link"
rel="nofollow">Security</a></li>
+ </ul>
+
+ <h5>About Apache</h5>
+ <ul>
+ <li><a href="http://www.apache.org"; class="external-link"
rel="nofollow">Apache main site</a></li>
+ <li><a href="http://www.apache.org/licenses/"; class="external-link"
rel="nofollow">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html";
title="The ASF sponsorship program" class="external-link"
rel="nofollow">Sponsorship program</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html";
class="external-link" rel="nofollow">Thanks</a></li>
+ </ul>
+
+ <h3><a name="Navigation-Upcoming"></a>Upcoming</h3>
+ <ul>
+ <li>No event</li>
+ </ul>
+
+</div>
+
+<!-- navigation -->
+
+
+ </div><!-- leftColumn -->
+ <div id="rightColumn">
+
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="../ch7-handler/ch7-handler.html">Chapter 7 - Handler</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../user-guide-toc.html">User Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="../ch9-connector/ch9-connector.html">Chapter 9 -
Connector</a>
+
+ </div>
+ <div class="clearfix"></div>
+ </div>
+
+
+<h1 id="chapter-8-acceptor">Chapter 8 - Acceptor</h1>
+<p>In order to build a server, you need to select an implementation of the
<em>IoAcceptor</em> interface.</p>
+<h2 id="ioacceptor">IoAcceptor</h2>
+<p>Basically, this interface is named because of the <em>accept()</em> method,
responsible for the creation of new connection between a client and the server.
The server accepts incoming connection request.</p>
+<p>At some point, we could have named this interface 'Server'.</p>
+<p>As we may deal with more than one kind of transport (TCP/UDP/...), we have
more than one implementation for this interface. It would be very unlikely that
you need to implement a new one.</p>
+<p>We have many of those implementing classes</p>
+<ul>
+<li><strong>NioSocketAcceptor</strong> : the non-blocking Socket transport
<em>IoAcceptor</em></li>
+<li><strong>NioDatagramAcceptor</strong> : the non-blocking UDP transport
<em>IoAcceptor</em></li>
+<li><strong>AprSocketAcceptor</strong> : the blocking Socket transport
<em>IoAcceptor</em>, based on APR</li>
+<li><strong>VmPipeSocketAcceptor</strong> : the in-VM <em>IoAcceptor</em></li>
+</ul>
+<p>Just pick the one that fit your need.</p>
+<p>Here is the class diagram for the <em>IoAcceptor</em> interfaces and
classes :</p>
+<p><img alt=""
src="../../../staticresources/images/mina/IoServiceAcceptor.png" /></p>
+<h2 id="creation">Creation</h2>
+<p>You first have to select the type of <em>IoAcceptor</em> you want to
instanciate. This is a choice you will made early in the process, as it all
boils down to which network protocol you will use. Let's see with an example
how it works :</p>
+<div class="codehilite"><pre><span class="n">public</span> <span
class="n">TcpServer</span><span class="p">()</span> <span
class="n">throws</span> <span class="n">IOException</span> <span
class="p">{</span>
+ <span class="sr">//</span> <span class="n">Create</span> <span
class="n">a</span> <span class="n">TCP</span> <span class="n">acceptor</span>
+ <span class="n">IoAcceptor</span> <span class="n">acceptor</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">NioSocketAcceptor</span><span class="p">();</span>
+
+ <span class="sr">//</span> <span class="n">Associate</span> <span
class="n">the</span> <span class="n">acceptor</span> <span class="n">to</span>
<span class="n">an</span> <span class="n">IoHandler</span> <span
class="n">instance</span> <span class="p">(</span><span class="n">your</span>
<span class="n">application</span><span class="p">)</span>
+ <span class="n">acceptor</span><span class="o">.</span><span
class="n">setHandler</span><span class="p">(</span><span
class="n">this</span><span class="p">);</span>
+
+ <span class="sr">//</span> <span class="n">Bind</span> <span
class="p">:</span> <span class="n">this</span> <span class="n">will</span>
<span class="n">start</span> <span class="n">the</span> <span
class="n">server</span><span class="o">...</span>
+ <span class="n">acceptor</span><span class="o">.</span><span
class="nb">bind</span><span class="p">(</span><span class="k">new</span> <span
class="n">InetSocketAddress</span><span class="p">(</span><span
class="n">PORT</span><span class="p">));</span>
+
+ <span class="n">System</span><span class="o">.</span><span
class="n">out</span><span class="o">.</span><span class="n">println</span><span
class="p">(</span><span class="s">"Server started..."</span><span
class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>That's it ! You have created a TCP server. If you want to start an UDP
server, simply replace the first line of code :</p>
+<div class="codehilite"><pre> <span class="o">...</span>
+ <span class="sr">//</span> <span class="n">Create</span> <span
class="n">an</span> <span class="n">UDP</span> <span class="n">acceptor</span>
+ <span class="n">IoAcceptor</span> <span class="n">acceptor</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">NioDatagramAcceptor</span><span class="p">();</span>
+ <span class="o">...</span>
+</pre></div>
+
+
+<h2 id="disposal">Disposal</h2>
+<p>The service can be stopped by calling the <em>dispose()</em> method. The
service will be stopped only when all the pending sessions have been processed
:</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span
class="n">Stop</span> <span class="n">the</span> <span
class="n">service</span><span class="p">,</span> <span class="n">waiting</span>
<span class="k">for</span> <span class="n">the</span> <span
class="n">pending</span> <span class="n">sessions</span> <span
class="n">to</span> <span class="n">be</span> <span class="n">inactive</span>
+<span class="n">acceptor</span><span class="o">.</span><span
class="n">dispose</span><span class="p">();</span>
+</pre></div>
+
+
+<p>You can also wait for every thread being executed to be properly completed
by passing a boolean parameter to this method :</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span
class="n">Stop</span> <span class="n">the</span> <span
class="n">service</span><span class="p">,</span> <span class="n">waiting</span>
<span class="k">for</span> <span class="n">the</span> <span
class="n">processing</span> <span class="n">session</span> <span
class="n">to</span> <span class="n">be</span> <span class="n">properly</span>
<span class="n">completed</span>
+<span class="n">acceptor</span><span class="o">.</span><span
class="n">dispose</span><span class="p">(</span> <span class="n">true</span>
<span class="p">);</span>
+</pre></div>
+
+
+<h2 id="status">Status</h2>
+<p>You can get the <em>IoService</em> status by calling one of the following
methods :</p>
+<ul>
+<li><em>isActive()</em> : true if the service can accept incoming requests</li>
+<li><em>isDisposing()</em> : true if the <em>dispose()</em> method has been
called. It does not tell if the service is actually stopped (some sessions
might be processed)</li>
+<li><em>isDisposed()</em> : true if the <em>dispose(boolean)</em> method has
been called, and the executing threads have been completed.</li>
+</ul>
+<h2 id="managing-the-iohandler">Managing the IoHandler</h2>
+<p>You can add or get the associated <em>IoHandler</em> when the service has
been instanciated. Youjust have to call the <em>setHandler(IoHandler)</em> or
<em>getHandler()</em> methods.</p>
+<h2 id="managing-the-filters-chain">Managing the Filters chain</h2>
+<p>if you want to manage the filters chain, you will have to call the
<em>getFilterChain()</em> method. Here is an example :</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span
class="n">Add</span> <span class="n">a</span> <span class="n">logger</span>
<span class="n">filter</span>
+<span class="n">DefaultIoFilterChainBuilder</span> <span
class="n">chain</span> <span class="o">=</span> <span
class="n">acceptor</span><span class="o">.</span><span
class="n">getFilterChain</span><span class="p">();</span>
+<span class="n">chain</span><span class="o">.</span><span
class="n">addLast</span><span class="p">(</span><span
class="s">"logger"</span><span class="p">,</span> <span
class="k">new</span> <span class="n">LoggingFilter</span><span
class="p">());</span>
+</pre></div>
+
+
+<p>You can also create the chain before and set it into the service :</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span
class="n">Add</span> <span class="n">a</span> <span class="n">logger</span>
<span class="n">filter</span>
+<span class="n">DefaultIoFilterChainBuilder</span> <span
class="n">chain</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">DefaultIoFilterChainBuilder</span><span class="p">();</span>
+<span class="n">chain</span><span class="o">.</span><span
class="n">addLast</span><span class="p">(</span><span
class="s">"logger"</span><span class="p">,</span> <span
class="k">new</span> <span class="n">LoggingFilter</span><span
class="p">());</span>
+
+<span class="sr">//</span> <span class="n">And</span> <span
class="n">inject</span> <span class="n">the</span> <span
class="n">created</span> <span class="n">chain</span> <span
class="n">builder</span> <span class="n">in</span> <span class="n">the</span>
<span class="n">service</span>
+<span class="n">acceptor</span><span class="o">.</span><span
class="n">setFilterChainBuilder</span><span class="p">(</span><span
class="n">chain</span><span class="p">);</span>
+</pre></div>
+
+
+<h2></h2>
+
+
+ <div class="nav">
+ <div class="nav_prev">
+
+ <a href="../ch7-handler/ch7-handler.html">Chapter 7 - Handler</a>
+
+ </div>
+ <div class="nav_up">
+
+ <a href="../user-guide-toc.html">User Guide</a>
+
+ </div>
+ <div class="nav_next">
+
+ <a href="../ch9-connector/ch9-connector.html">Chapter 9 -
Connector</a>
+
+ </div>
+ <div class="clearfix"></div>
+ </div>
+
+
+ </div><!-- rightColumn -->
+ <div id="endContent"></div>
+ </div><!-- content -->
+ <div id="footer">© 2003-2012, <a
href="http://www.apache.org";>The Apache Software Foundation</a> - <a
href="privacy-policy.html">Privacy Policy</a><br />
+ Apache MINA, MINA, Apache Vysper, Vysper, Apache SSHd, SSHd,
Apache FtpServer, FtpServer, Apache AsyncWeb, AsyncWeb,
+ Apache, the Apache feather logo, and the Apache Mina project
logos are trademarks of The Apache Software Foundation.
+ </div>
+ </div><!-- container -->
+ </body>
+</html>
+
