From d3f24589a40bf38e79deefe289a8dc6845ed7017 Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Mon, 22 Sep 2008 02:10:31 +0000
Subject: [PATCH] * Fixed too frequent plugin update * Keep writing the
 guide...

---
 pom.xml                      |  3 ++
 src/docbook/custom.dtd       |  5 ++++
 src/docbook/module/start.xml | 57 ++++++++++++++++++++++++++++--------
 3 files changed, 52 insertions(+), 13 deletions(-)

diff --git a/pom.xml b/pom.xml
index 9ab1b8cf4b..f5c849c3e6 100644
--- a/pom.xml
+++ b/pom.xml
@@ -433,6 +433,9 @@
       <snapshots>
         <enabled>false</enabled>
       </snapshots>
+      <releases>
+        <updatePolicy>interval:10080</updatePolicy>
+      </releases>
       <id>jboss.release</id>
       <name>JBoss releases</name>
       <url>http://repository.jboss.org/maven2</url>
diff --git a/src/docbook/custom.dtd b/src/docbook/custom.dtd
index 3c12eabae7..8e86f6dafa 100644
--- a/src/docbook/custom.dtd
+++ b/src/docbook/custom.dtd
@@ -17,6 +17,7 @@
 
 <!ENTITY Channel                  "<ulink url='&API;channel/Channel.html'><interfacename>Channel</interfacename></ulink>">
 <!ENTITY ChannelDownstreamHandler "<ulink url='&API;channel/ChannelDownstreamHandler.html'><interfacename>ChannelDownstreamHandler</interfacename></ulink>">
+<!ENTITY ChannelEvent             "<ulink url='&API;channel/ChannelEvent.html'><interfacename>ChannelEvent</interfacename></ulink>">
 <!ENTITY ChannelFactory           "<ulink url='&API;channel/ChannelFactory.html'><interfacename>ChannelFactory</interfacename></ulink>">
 <!ENTITY ChannelHandler           "<ulink url='&API;channel/ChannelHandler.html'><interfacename>ChannelHandler</interfacename></ulink>">
 <!ENTITY ChannelHandlerContext    "<ulink url='&API;channel/ChannelHandlerContext.html'><interfacename>ChannelHandlerContext</interfacename></ulink>">
@@ -27,6 +28,10 @@
 <!ENTITY MessageEvent             "<ulink url='&API;channel/MessageEvent.html'><interfacename>MessageEvent</interfacename></ulink>">
 <!ENTITY SimpleChannelHandler     "<ulink url='&API;channel/SimpleChannelHandler.html'><classname>SimpleChannelHandler</classname></ulink>">
 
+<!-- Types in the channel.socket package -->
+
+<!ENTITY ServerSocketChannel  "<ulink url='&API;channel/socket/ServerSocketChannel.html'><classname>ServerSocketChannel</classname></ulink>">
+
 <!-- Types in the channel.socket.nio package -->
 
 <!ENTITY NioServerSocketChannelFactory  "<ulink url='&API;channel/socket/nio/NioServerSocketChannelFactory.html'><classname>NioServerSocketChannelFactory</classname></ulink>">
diff --git a/src/docbook/module/start.xml b/src/docbook/module/start.xml
index 36cbcbbee8..d3dec59fa8 100644
--- a/src/docbook/module/start.xml
+++ b/src/docbook/module/start.xml
@@ -77,8 +77,7 @@ public class DiscardServerHandler extends &SimpleChannelHandler; {<co id="exampl
           one &Channel; (and its associated &ChannelPipeline;).
           <classname>DiscardServerHandler</classname> doesn't manage any
           stateful information, and therefore it's annotated with the value
-          <literal>"all"</literal>.  It's OK even if you are confused with
-          this yet.  We will revisit it soon.
+          <literal>"all"</literal>.
         </para>
       </callout>
       <callout arearefs="example.discard.co2">
@@ -131,47 +130,79 @@ import org.jboss.netty.channel.socket.nio.&NioServerSocketChannelFactory;;
 public class DiscardServer {
 
     public static void main(String[] args) throws Exception {
-        &ChannelFactory;<co id="example.discard2.co1" /> factory =
-            new &NioServerSocketChannelFactory;<co id="example.discard2.co2" />(
+        &ChannelFactory; factory =
+            new &NioServerSocketChannelFactory;<co id="example.discard2.co1" />(
                     Executors.newCachedThreadPool(),
                     Executors.newCachedThreadPool());
 
-        &ServerBootstrap; bootstrap = new &ServerBootstrap;<co id="example.discard2.co3" />(factory);
+        &ServerBootstrap; bootstrap = new &ServerBootstrap;<co id="example.discard2.co2" />(factory);
 
         DiscardServerHandler handler = new DiscardServerHandler();
         &ChannelPipeline; pipeline = bootstrap.getPipeline();
-        pipeline.addLast("handler", handler);<co id="example.discard2.co4" />
+        pipeline.addLast("handler", handler);<co id="example.discard2.co3" />
 
-        bootstrap.setOption("child.tcpNoDelay", true);<co id="example.discard2.co5" />
+        bootstrap.setOption("child.tcpNoDelay", true);<co id="example.discard2.co4" />
         bootstrap.setOption("child.keepAlive", true);
 
-        bootstrap.bind(new InetSocketAddress(8080));<co id="example.discard2.co6" />
+        bootstrap.bind(new InetSocketAddress(8080));<co id="example.discard2.co5" />
     }
 }</programlisting>
     <calloutlist>
       <callout arearefs="example.discard2.co1">
         <para>
-          &ChannelFactory; is a factory which creates a &Channel;
+          &ChannelFactory; is a factory which creates and manages &Channel;s
+          and its related resources.  It processes all I/O requests and
+          performs I/O to generate &ChannelEvent;s.  Netty provides various
+          &ChannelFactory; implementations.  We are implementing a server-side
+          application in this example, and therefore
+          &NioServerSocketChannelFactory; was used.  Another thing to note is
+          that it doesn't create I/O threads by itself.  It is supposed to
+          acquire threads from the thread pool you specified in the
+          constructor, and it gives you more control over how threads should
+          be managed in the environment where your application runs, such as
+          an application server with a security manager.
         </para>
       </callout>
       <callout arearefs="example.discard2.co2">
         <para>
+          &ServerBootstrap; is a helper class that sets up a server. You can
+          set up the server by yourself using a &Channel; directly, but it's a
+          tedious process and you won't need to do that in most cases.
         </para>
       </callout>
       <callout arearefs="example.discard2.co3">
         <para>
+          Here, we add the <classname>DiscardServerHandler</classname> to the
+          <emphasis>default</emphasis> &ChannelPipeline;.  Whenever a new
+          connection is accepted by the server, a new &ChannelPipeline; will
+          be created for a newly accepted &Channel; and all the
+          &ChannelHandler;s added here will be added to the new
+          &ChannelPipeline;.  It's just like
+          <ulink url="http://en.wikipedia.org/wiki/Object_copy">a shallow-copy
+          operation</ulink>; all &Channel; and their &ChannelPipeline;s will
+          share the same <classname>DiscardServerHandler</classname> instance.
         </para>
       </callout>
       <callout arearefs="example.discard2.co4">
         <para>
+          You can also set the parameters which are specific to the &Channel;
+          implementation.  We are writing a TCP/IP server, so we are allowed
+          to set the socket options such as <literal>tcpNoDelay</literal> and
+          <literal>keepAlive</literal>.  Please note that the
+          <literal>"child."</literal> prefix was added to all options.  It
+          means the options will be applied to the accepted &Channel;s instead
+          of the options of the &ServerSocketChannel;.  To set the options of
+          the &ServerSocketChannel;, you could do the following:
+          <programlisting>bootstrap.setOption("reuseAddress", true);</programlisting>
         </para>
       </callout>
       <callout arearefs="example.discard2.co5">
         <para>
-        </para>
-      </callout>
-      <callout arearefs="example.discard2.co6">
-        <para>
+          OK, we are all set.  What's left is bind to the port to start the
+          server.  Here, we bind to the port <literal>8080</literal> of all
+          NICs in the machine.  You are allowed to call the
+          <methodname>bind</methodname> method as many times as you want with
+          different bind addresses. 
         </para>
       </callout>
     </calloutlist>