Mailing-List: contact commits-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@directory.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
From: Apache Wiki <wikidiffs@apache.org>
To: directory-cvs@incubator.apache.org
Date: Sat, 07 May 2005 11:52:27 -0000
Message-ID: <20050507115227.9589.91452@ajax.apache.org>
Subject: [Directory Wiki] Update of "MinaTutorial" by VinodPanicker

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Directory Wiki" for change notification.

The following page has been changed by VinodPanicker:
http://wiki.apache.org/directory/MinaTutorial

The comment on the change is:
Corrected typos and grammar

------------------------------------------------------------------------------
  
  == Overview ==
  
- It’s an era of World Wide Web.  Countless web application frameworks were born to improve development productivity by order of magnitude.  In spite of this dominance of WWW, we know there are a lot of protocols that HTTP cannot replace, and even HTTP is just one of them.  We still need to build clients and servers that implements appropriate protocols.
+ It’s the era of the World Wide Web.  Countless web application frameworks were born to improve development productivity by orders of magnitude.  In spite of this dominance of the WWW, we know that there are a lot of protocols that HTTP cannot replace, and even HTTP is just one of them.  We still need to build clients and servers that implement appropriate protocols.
  
  === What is MINA? ===
  
- Have you ever implemented any protocols in Java, or in any other languages?  As you experienced, programming network applications is not so easy even for professional developers.  It is due to a few significant problems:
+ Have you ever implemented any protocol stack in Java, or in any other languages?  As you must have experienced, programming network applications is not so easy even for professional developers.  It is due to a few significant problems:
  
    * There is no appropriate network application framework designed for developer productivity.
      * You lose any chance to create your application in limited time.
@@ -25, +25 @@

    * Network applications are difficult to unit-test
      * You lose agility.
  
- MINA is a network application framework to resolve all the issues above not sacrificing its performance or scalability.
+ MINA is a network application framework to resolve all the issues listed above without sacrificing performance nor scalability.
  
  == I/O Layer: Programming Echo Server ==
  
@@ -33, +33 @@

  
  TODO: I/O Layer diagram here
  
- The above diagram shows interaction between clients and I/O layer.  IoAcceptor performs all low-level I/O, translates them to abstract I/O events, and forwards the translated events with associated IoSession to IoHandler.
+ The above diagram shows interaction between clients and the MINA I/O layer.  IoAcceptor performs all low-level I/O, translates them into abstract I/O events, and forwards the translated events with the associated IoSession to IoHandler.
  
  === IoSession ===
  
  TODO: IoSession class diagram here
  
- An IoSession represents an I/O connection between remote peer and your application.  With IoSession, you can write messages to the remote peer, access session configurations, and store custom attributes associated with the connection.
+ An IoSession represents an I/O connection between a remote peer and your application.  With IoSession, you can write messages to the remote peer, access session configurations, and store custom attributes associated with the session.
  
  === IoHandler ===
  
@@ -47, +47 @@

  
    * sessionCreated: Invoked when a new I/O connection is established.  This method is invoked before any I/O operation is executed so that any socket parameters or session attributes can be set first.
    * sessionOpened: Invoked after sessionCreated is invoked.
-   * sessionClosed: Invoked when I/O connection is closed.
+   * sessionClosed: Invoked when the I/O connection is closed.
    * sessionIdle: Invoked when there is no transmission of data between remote peer and user application.
    * exceptionCaught: Invoked when any exceptions are thrown from IoAcceptor or your IoHandler.
-   * dataRead: Invoked when data is read from remote peer.
+   * dataRead: Invoked when data is read from the remote peer.
-   * dataWritten: Invoked when your write request is written out to remote peer.
+   * dataWritten: Invoked when your write request is written out to the remote peer.
  
  We’ll see how to implement IoHandler for echo protocol in the next section.
  
@@ -93, +93 @@

  }
  }}}
  
- You’ve just implemented echo protocol with MINA.  Now you need to bind your handler to server port:
+ You’ve just implemented echo protocol with MINA.  Now you need to bind your handler to a server port:
  
  {{{
  package org.apache.mina.examples.echoserver;
@@ -125, +125 @@

  
  === Adding IoFilters ===
  
- IoFilter provides the most powerful way to extend MINA.  It intercepts all I/O events and pre- or post-processes them.  You can simply think it is similar to Servlet filters.  IoFilters can be used for many purposes such as:
+ IoFilter provides the most powerful way to extend MINA.  It intercepts all I/O events and pre- or post-processes them.  You may think it is similar to Servlet filters.  IoFilters can be used for many purposes such as:
  
    * Event logging
    * Performance profiling
@@ -164, +164 @@

  
  == Protocol Layer: Reversing the Echo ==
  
- We learned how to use I/O layer via simplistic echo server example.  But have you ever imagined you implement complex protocols like LDAP?  It must be a nightmare because I/O layer doesn’t help you separate message codec and actual business logic such as accessing directory database.  Protocol layer is introduced to resolve this issue by transforming ByteBuffer events to POJO events which is higher-level:
+ We learned how to use I/O layer via simplistic echo server example.  But have you ever imagined how you would implement complex protocols like LDAP?  It must be a nightmare because the I/O layer doesn’t help you separate message codec and actual business logic such as accessing a directory database.  MINA provides a Protocol layer to resolve this issue.  The Protocol layer transforms ByteBuffer events to POJO events which are at a higher-level:
  
  TODO: Protocol Layer diagram here
  
@@ -172, +172 @@

  
  TODO: Class diagram here
  
- Are they too many?  But please note that ProtocolCodecFactory, ProtocolEncoder, and ProtocolDecoder are fully reusable; Apache ASN1 project provides ASN.1 codec for MINA, and more common codecs like XML, Java object serialization, and simple text will be ready in the next release of MINA.  Once you implemented a flexible codec, you can reuse it for later uses.  Even if you don’t have any plan to reuse your codec, of course, MINA provides quite easy way to implement complex protocols. (Please refer to Advanced Topics)
+ Maybe it looks like overkill, but please note that ProtocolCodecFactory, ProtocolEncoder, and ProtocolDecoder are fully reusable; Apache ASN1 project provides ASN.1 codec for MINA, and more common codecs like XML, Java object serialization, and simple text will be provided in the next release of MINA.  Once you implemente a flexible codec, you can reuse it in future applications.  Even if you don’t plan to reuse your codec, of course, MINA provides a quite easy way to implement complex protocols. (Please refer to Advanced Topics)
  
  In this chapter, we create a ‘reverse’ server that reverses all text lines it receives to demonstrate how to program in protocol layer.
  
@@ -180, +180 @@

  
  TODO: Class diagram here
  
- ProtocolSession is a counterpart of IoSession of I/O layer.  As you noticed from FIGURE X, you write messages as a POJO instead of a ByteBuffer.  ProtocolEncoder encodes message objects to ByteBuffers so that I/O layer can write them to sockets.
+ ProtocolSession is a counterpart of the I/O layer IoSession.  As you must have noticed from FIGURE X, you write messages as POJO's instead of ByteBuffer's.  ProtocolEncoder encodes message objects to ByteBuffers so that the I/O layer can write them to underlying sockets.
  
  === ProtocolHandler ===
  
  TODO: Class diagram here
  
- ProtocolHandler is a counterpart of IoHandler of I/O layer.  dataRead and dataWritten method are replaced with messageReceived and messageSent because ProtodolDecoder decodes ByteBuffers received from I/O layer into message objects.
+ ProtocolHandler is a counterpart of the I/O layer IoHandler.  dataRead and dataWritten methods are replaced with messageReceived and messageSent.  This is because ProtocolDecoder decodes ByteBuffers received from I/O layer into message objects.
  
  === ProtocolEncoder and ProtocolDecoder ===
  
  TODO: Class diagram here
  
- ProtocolEncoder and ProtocolDecoder have one method.  ProtocolEncoder encodes message objects to ByteBuffer, and ProtocolDecoder decodes ByteBuffers into message objects.  We’ll learn how to implement these interfaces below.
+ ProtocolEncoder and ProtocolDecoder have just one method each.  ProtocolEncoder encodes message objects into a ByteBuffer, and ProtocolDecoder decodes ByteBuffers into message objects.  We’ll learn how to implement these interfaces below.
  
  === Implementing ProtocolHandler ===
  
- Let’s implement ProtocolHandler first.  We extend ProtocolHandlerAdapter here, too, just like we did when we implement IoHandler:
+ Let’s implement a ProtocolHandler first.  We extend ProtocolHandlerAdapter here too, just like we did when we implemented IoHandler:
  
  {{{
  package org.apache.mina.examples.reverser;
@@ -276, +276 @@

  }
  }}}
  
- Reverse protocol is fully implemented now.  Setup code is very similar to that of echo server:
+ That's it, the Reverser protocol is fully implemented now.  Startup code is very similar to that of echo server:
  
  TODO: startup code here
  
@@ -286, +286 @@

  
  TODO: Protocol Layer Diagram with filters here
  
- Adding IoLoggingFilter logs low-level I/O events which is appropriate for debugging.  We could use ProtocolLoggingFilter instead to log higher-level events:
+ Adding IoLoggingFilter logs low-level I/O events which are appropriate for debugging purposes.  We could use ProtocolLoggingFilter instead to log higher-level events:
  
  TODO: Code here
  
@@ -296, +296 @@

  
  === ByteBuffers ===
  
- MINA doesn’t user NIO ByteBuffer class directly.  It uses custom ByteBuffer class that wraps NIO ByteBuffer to extend it.  Here are some differences:
+ MINA doesn’t use the Java NIO ByteBuffer class directly.  It uses custom a ByteBuffer class that extends the functionality of the Java NIO ByteBuffer.  Here are some differences:
  
    * MINA ByteBuffer is an abstract class that users can extend freely.
    * MINA manages and pools MINA ByteBuffers.  Users can control the point the buffers are released by providing acquire() and release() methods.
@@ -306, +306 @@

  
  ==== ByteBuffer pooling ====
  
- MINA has a global ByteBuffer pool that is shared by all MINA applications in the same virtual machine.  Any allocated buffers are released after I/O operation or event handler method is performed or invoked.  So you can simply call ByteBuffer.allocate() to get a clean buffer from the pool and forget about returning it to the pool.  Please refer to ByteBuffer JavaDoc for more details.
+ MINA has a global ByteBuffer pool that is shared by all MINA applications in the same Virtual Machine.  Any allocated buffers are released after the I/O operation or event handler method is performed or invoked.  So you can simply call ByteBuffer.allocate() to get a clean buffer from the pool and forget about returning it to the pool.  Please refer to the ByteBuffer JavaDocs for more details.
  
  === Thread Model ===
  
- MINA fulfills capability for various thread models via filter mechanism.  It runs in a single thread mode when no thread pool filters are added.  If you add one IoThreadPoolFilter to IoAcceptor, you get one leader-follower thread pool.  If you add one more ProtocolThreadPoolFilter, Your server will have two; one (IoThreadPoolFilter) for decoding message objects and the other (ProtocolThreadPoolFilter) for processing business logic.
+ MINA provides support for various threading models using its versatile filter mechanism.  It runs in a single thread mode when no thread pool filters are added.  If you add one IoThreadPoolFilter to IoAcceptor, you get one leader-follower thread pool.  If you add one more ProtocolThreadPoolFilter, Your server will have two thread pools; one (IoThreadPoolFilter) for decoding message objects and the other (ProtocolThreadPoolFilter) for processing business logic.
  
- SimpleServiceRegistry adds IoThreadPoolFilter and ProtocolThreadPoolFilter which is adequate for applications that requires high-scalability by default.  If you want to use your own thread model, please refer to SimpleServiceRegistry source code and initialize acceptors by yourself.  It is, of course, a trivial task.
+ The SimpleServiceRegistry adds IoThreadPoolFilter and ProtocolThreadPoolFilter which is adequate for applications that require high-scalability by default.  If you want to use your own threading model, please refer to the SimpleServiceRegistry source code and initialize Acceptors by yourself.  It is, of course, a trivial task.
  
  TODO: Example code here
  
  === More Complex Protocols ===
  
- ‘Reverser’ example is still too simple comparing to other complex protocols.  There should be dozens of message types, and their codec is required to make the server work.  MINA provides utility classes to help you:
+ ‘Reverser’ example is still too simple compared to other complex protocols.  There should be dozens of message types, and their codec is required to make the server work.  MINA provides the following utility classes to help you:
  
    * DemuxingProtocolHandler
    * DemuxingProtocolCodecFactory
  
- Please refer to JavaDocs for more details.
+ Please refer to the JavaDocs for more details.
  
  === In-VM Pipe Communication ===
  
- You must have learned that protocol layer is built on top of I/O layer, but it is not really true.  Though we usually use protocol layer that wraps I/O layer, there is a special implementation of protocol layer called as ‘in-VM pipe communication.’
+ You must have learned that protocol layer is built on top of I/O layer, but it is not really true.  Though we usually use protocol layer that wraps I/O layer, there is a special implementation of protocol layer called as ‘in-VM pipe communication’.
  
- Let’s assume that you implemented SMTP server and spam filter server in MINA.  SMTP server will possibly communicate with spam filter server to detect spam messages or any clients which are listed in RBL.  If there two servers are in the same Java VM, I/O layer is not necessary; you can simply bypass encoding and decoding of message objects.  In-VM pipe communication enables you to use the same code without regarding whether spam filter server resides in the same VM or not.
+ Let’s assume that you implement a SMTP server and a Spam Filter server in MINA.  The SMTP server will possibly communicate with the Spam Filter server to detect spam messages or any clients which are listed in the RBL.  If these two servers are in the same Java VM, an I/O layer is unnecessary; you can simply bypass encoding and decoding of message objects.  In-VM pipe communication enables you to use the same code regardless of whether spam filter server resides in the same VM or not.
  
- Please refer to ‘Tennis’ example in the source distribution.
+ Please refer to the ‘Tennis’ example in the source distribution.
  
  == How to Contribute ==
  
- We want MINA to evolve actively reacting to user requests, and therefore we need your feedback as much as possible.  The Apache Directory team will strive to satisfy all possible use cases of MINA.  Please feel free to contact us.
+ We want MINA to evolve actively, reacting to user requests, and therefore we need as much feedback from you as possible.  The Apache Directory team will strive to satisfy all possible use cases of MINA.  Please feel free to contact us.
  
  === How to Contact Us ===
  
@@ -352, +352 @@

  
    * http://issues.apache.org/jira/browse/DIRMINA
  
- Or, you could do some performance benchmark on MINA and tune it.
+ Or, you could do some performance benchmarks on MINA and tune it.
  
  == Acknowledgements ==