directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Directory Wiki] Update of "MinaTutorial" by VinodPanicker
Date Sat, 07 May 2005 11:52:27 GMT
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 ==
  

Mime
View raw message