directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 10017 - in incubator/directory/snickers/trunk: . codec-stateful xdocs xdocs/ber-codec xdocs/codec-stateful xdocs/stub-compiler
Date Thu, 15 Apr 2004 01:11:26 GMT
Author: akarasulu
Date: Wed Apr 14 18:11:26 2004
New Revision: 10017

Modified:
   incubator/directory/snickers/trunk/codec-stateful/maven.xml
   incubator/directory/snickers/trunk/maven.xml
   incubator/directory/snickers/trunk/project.xml
   incubator/directory/snickers/trunk/xdocs/ber-codec/eureka.xml
   incubator/directory/snickers/trunk/xdocs/ber-codec/index.xml
   incubator/directory/snickers/trunk/xdocs/ber-codec/navigation.xml
   incubator/directory/snickers/trunk/xdocs/codec-stateful/index.xml
   incubator/directory/snickers/trunk/xdocs/codec-stateful/navigation.xml
   incubator/directory/snickers/trunk/xdocs/index.xml
   incubator/directory/snickers/trunk/xdocs/navigation.xml
   incubator/directory/snickers/trunk/xdocs/stub-compiler/navigation.xml
Log:
o document changes to referrence the right JIRA project


Modified: incubator/directory/snickers/trunk/codec-stateful/maven.xml
==============================================================================
--- incubator/directory/snickers/trunk/codec-stateful/maven.xml	(original)
+++ incubator/directory/snickers/trunk/codec-stateful/maven.xml	Wed Apr 14 18:11:26 2004
@@ -1,7 +1,7 @@
-<?xml version="1.0" encoding="ISO-8859-1"?> 
-  
-<project 
-  default="jar:install" 
-  >
-  
-</project>
+<?xml version="1.0" encoding="ISO-8859-1"?> 
+  
+<project 
+  default="jar:install" 
+  >
+  
+</project>

Modified: incubator/directory/snickers/trunk/maven.xml
==============================================================================
--- incubator/directory/snickers/trunk/maven.xml	(original)
+++ incubator/directory/snickers/trunk/maven.xml	Wed Apr 14 18:11:26 2004
@@ -1,89 +1,89 @@
-<?xml version="1.0" encoding="ISO-8859-1"?> 
-  
-<project 
-  default="buildall" 
-  xmlns:j="jelly:core" 
-  xmlns:u="jelly:util" 
-  xmlns:ant="jelly:ant" 
-  xmlns:maven="jelly:maven" 
-  xmlns:m="maven" 
-  xmlns:deploy="deploy"
-  >
-  
-  <preGoal name="site">
-    <attainGoal name="docbook:transform"/>
-  </preGoal>
-  
-  <postGoal name="site">
-    <attainGoal name="server:copy-images"/>
-    <attainGoal name="subproject:collectdocs"/>
-  </postGoal>
-
-  <goal name="subproject:collectdocs">
-    <ant:copy 
-      toDir="../../sitedocs/trunk/target/docs/subprojects/snickers">
-      
-      <ant:fileSet dir="${basedir}/target/docs">
-        <ant:include name="**"/>
-      </ant:fileSet>
-    </ant:copy>
-  </goal>
-
-  <goal name="server:copy-images">
-    <copy toDir="target/docs/images">
-      <fileSet dir="${basedir}/src/images">
-        <include name="*.gif"/>
-      </fileSet>
-    </copy>
-  </goal>
-  
-  <goal name="buildall" description="Build All Jar Files And Intall">
-    <ant:delete dir="${basedir}/target/classes"/>
-    <maven:reactor basedir="${basedir}" postProcessing="true" 
-      includes="**/project.xml" excludes="project.xml" goals="jar:install" 
-      banner="Building" ignoreFailures="false"/>
-  </goal>
-  
-  <goal name="deployall" description="Deploy All Jar Files And Intall">
-    <maven:reactor basedir="${basedir}" postProcessing="true" 
-      includes="**/project.xml" excludes="./project.xml" goals="jar:deploy" 
-      banner="Deploying" ignoreFailures="false"/>
-  </goal>
-  
-  <goal name="sitedocs" description="Builds the entire site documentation">
-    <maven:reactor basedir="${basedir}" postProcessing="true" 
-      includes="**/project.xml" excludes="./project.xml" goals="site" 
-      banner="site" ignoreFailures="false"/>
-  </goal>
-  
-  <goal name="clean-all" description="Clean all sandbox projects">
-    <maven:reactor basedir="${basedir}" postProcessing="true" 
-      includes="**/project.xml" excludes="./project.xml" goals="cleanall" 
-      banner="Clean All" 
-      ignoreFailures="true"/>
-    <attainGoal name="clean"/>
-    <delete dir="home"/>
-  </goal>
-  
-  <goal name="eclipseall" 
-    description="Generate eclipse descriptors for all projects">
-    <maven:reactor basedir="${basedir}" postProcessing="true" 
-      includes="*/project.xml" goals="clean" banner="Clean All" 
-      ignoreFailures="true"/>
-  </goal>
-  
-  <goal name="eclipse-all" description="Create all eclipse projects">
-    <maven:reactor basedir="${basedir}" postProcessing="true" 
-      includes="*/project.xml" goals="eclipse" banner="Eclipse Project" 
-      ignoreFailures="true"/>
-  </goal>
-  
-  <!-- ========================================================================
-    Experimentation section starts here!
-    ======================================================================= -->
-  
-  <goal name="components">
-    <j:import inherit="true" uri="components.xml"/>  
-  </goal>
-    
-</project>
+<?xml version="1.0" encoding="ISO-8859-1"?> 
+  
+<project 
+  default="buildall" 
+  xmlns:j="jelly:core" 
+  xmlns:u="jelly:util" 
+  xmlns:ant="jelly:ant" 
+  xmlns:maven="jelly:maven" 
+  xmlns:m="maven" 
+  xmlns:deploy="deploy"
+  >
+  
+  <preGoal name="site">
+    <attainGoal name="docbook:transform"/>
+  </preGoal>
+  
+  <postGoal name="site">
+    <attainGoal name="server:copy-images"/>
+    <attainGoal name="subproject:collectdocs"/>
+  </postGoal>
+
+  <goal name="subproject:collectdocs">
+    <ant:copy 
+      toDir="../../sitedocs/trunk/target/docs/subprojects/snickers">
+      
+      <ant:fileSet dir="${basedir}/target/docs">
+        <ant:include name="**"/>
+      </ant:fileSet>
+    </ant:copy>
+  </goal>
+
+  <goal name="server:copy-images">
+    <copy toDir="target/docs/images">
+      <fileSet dir="${basedir}/src/images">
+        <include name="*.gif"/>
+      </fileSet>
+    </copy>
+  </goal>
+  
+  <goal name="buildall" description="Build All Jar Files And Intall">
+    <ant:delete dir="${basedir}/target/classes"/>
+    <maven:reactor basedir="${basedir}" postProcessing="true" 
+      includes="**/project.xml" excludes="project.xml" goals="jar:install" 
+      banner="Building" ignoreFailures="false"/>
+  </goal>
+  
+  <goal name="deployall" description="Deploy All Jar Files And Intall">
+    <maven:reactor basedir="${basedir}" postProcessing="true" 
+      includes="**/project.xml" excludes="./project.xml" goals="jar:deploy" 
+      banner="Deploying" ignoreFailures="false"/>
+  </goal>
+  
+  <goal name="sitedocs" description="Builds the entire site documentation">
+    <maven:reactor basedir="${basedir}" postProcessing="true" 
+      includes="**/project.xml" excludes="./project.xml" goals="site" 
+      banner="site" ignoreFailures="false"/>
+  </goal>
+  
+  <goal name="clean-all" description="Clean all sandbox projects">
+    <maven:reactor basedir="${basedir}" postProcessing="true" 
+      includes="**/project.xml" excludes="./project.xml" goals="cleanall" 
+      banner="Clean All" 
+      ignoreFailures="true"/>
+    <attainGoal name="clean"/>
+    <delete dir="home"/>
+  </goal>
+  
+  <goal name="eclipseall" 
+    description="Generate eclipse descriptors for all projects">
+    <maven:reactor basedir="${basedir}" postProcessing="true" 
+      includes="*/project.xml" goals="clean" banner="Clean All" 
+      ignoreFailures="true"/>
+  </goal>
+  
+  <goal name="eclipse-all" description="Create all eclipse projects">
+    <maven:reactor basedir="${basedir}" postProcessing="true" 
+      includes="*/project.xml" goals="eclipse" banner="Eclipse Project" 
+      ignoreFailures="true"/>
+  </goal>
+  
+  <!-- ========================================================================
+    Experimentation section starts here!
+    ======================================================================= -->
+  
+  <goal name="components">
+    <j:import inherit="true" uri="components.xml"/>  
+  </goal>
+    
+</project>

Modified: incubator/directory/snickers/trunk/project.xml
==============================================================================
--- incubator/directory/snickers/trunk/project.xml	(original)
+++ incubator/directory/snickers/trunk/project.xml	Wed Apr 14 18:11:26 2004
@@ -18,7 +18,7 @@
     <url>http://incubator.apache.org/directory</url>
 
     <issueTrackingUrl>
-      http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400
+      http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10515
     </issueTrackingUrl>
     <siteAddress>incubator.apache.org</siteAddress>
     <siteDirectory>/home/akarasulu/public_html</siteDirectory>

Modified: incubator/directory/snickers/trunk/xdocs/ber-codec/eureka.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/ber-codec/eureka.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/ber-codec/eureka.xml	Wed Apr 14 18:11:26 2004
@@ -10,7 +10,7 @@
   <section name="And we saw the light ... ">
      <p>
        One day Wes and Alex started talking about going to town on a new 
-       ASN.1 BER Library and here's what happened ...
+       ASN.1 BER Library and here's what happened ...
      </p>    
      <subsection name="The Conversation">
       <source>

Modified: incubator/directory/snickers/trunk/xdocs/ber-codec/index.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/ber-codec/index.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/ber-codec/index.xml	Wed Apr 14 18:11:26 2004
@@ -11,7 +11,7 @@
         The Snickers BER codec runtime is based on the stateful codec interfaces
         defined in the <a href="http://jakarta.apache.org/commons/codec">
         commons-codec</a> API (hopefully these stateful codec interfaces make 
-        there way there).
+        there way there).
       </p>
       
       <p>
@@ -33,7 +33,7 @@
       <p>
         For more involved information concerning how the BER codec runtime is
         designed and operates see the design documentation on the decoder 
-        <a href="./design.html">here</a>.
+        <a href="./design.html">here</a>.
       </p>
       
       <p>
@@ -41,7 +41,7 @@
         Below we show how a decoder can be established to be used within a 
         standard selector based input detection loop.  This use case is by no
         means specific to the SnickersDecoder, it is a characteristic of 
-        StatefulDecoders in general.  Below we show how the decoder is setup:
+        StatefulDecoders in general.  Below we show how the decoder is setup:
       </p>
       
       <source>
@@ -51,7 +51,7 @@
       MyClass.this.process( ( Message ) decoded ) ;
   }
 };
-decoder.setCallback( cb ) ;
+decoder.setCallback( cb ) ;
       </source>
       
       <p>
@@ -60,7 +60,7 @@
         object is cast to is the super interface used by the LDAP common message
         API.  The objects returned are LDAP PDU message envelopes but they can 
         be any Java stub generated for ASN.1 data types using the Snickers stub
-        compiler.
+        compiler.
       </p>
       
       <p>
@@ -68,7 +68,7 @@
         available input the decoder can be used to decode encoded BER messages.
         The example below is a trivialized example of how the decoder can be 
         used to decoded BER encoded data in parts as a message arrives 
-        fragmented by the tcp/ip stack:
+        fragmented by the tcp/ip stack:
       </p>
       
       <source>
@@ -91,7 +91,7 @@
         is void.  Because the callback is used to deliver the finished product
         when it is ready the decode operation can occur asynchronously in 
         another thread or stage of a server.  This is what makes 
-        StatefulDecoders and the SnickersDecoder in particular so exciting.
+        StatefulDecoders and the SnickersDecoder in particular so exciting.
       </p>
     </section>
   </body>

Modified: incubator/directory/snickers/trunk/xdocs/ber-codec/navigation.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/ber-codec/navigation.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/ber-codec/navigation.xml	Wed Apr 14 18:11:26
2004
@@ -41,7 +41,7 @@
     <menu name="Resources">
       <item name="IRC" href="../../irc.html"/>
       <item name="Jira" href=
-        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400"/>
+        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10515"/>
       <item name="Wiki" href="http://wiki.apache.org/directory"/>
       <item name="Lists" href="../../mailing-lists.html"/>
       <item name="License" href="../../license.html"/>

Modified: incubator/directory/snickers/trunk/xdocs/codec-stateful/index.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/codec-stateful/index.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/codec-stateful/index.xml	Wed Apr 14 18:11:26
2004
@@ -1,235 +1,235 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<document>
-  <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Stateful Codecs</title>
-  </properties>
-  <body>
-    <section name="Introduction">
-      <p>
-        Stateful encoder and decoder pairs, or codecs for short, maintain state 
-        between respective operations.  By maintaining state in the codec all 
-        the data needed for the operation not be available at one time.  This 
-        leads to codecs with significantly reduced active footprints which are 
-        constant in size regardless of the size of the substrates they operate
-        upon.
-      </p>
-      
-      <p>
-        Furthermore Stateful codecs operate on data as it arrives instead of in
-        one shot.  This way the computational requirements are spread out over
-        time as the substrate is made available.
-      </p>
-      
-      <p>
-        Stateful codecs must be handled with care since they maintain the state
-        of an operation.  Stateful codecs must be dedicated to a serial 
-        stream of substrate objects whatever that may be.  This makes them ideal
-        for streams which have long lifespans however sensitive to the loss of 
-        data which may retard their state and require a reset.
-      </p>
-    </section>
-    
-    <section name="StatefulDecoder Usage">
-      <p>
-        StatefulDecoders use callbacks to notify the successful decode of a
-        unit of encoded substrate.  Other than this the definition of what a
-        'unit of encoded substrate' is depends on the codec's decoder 
-        implementation.  The definition may be size constrained or be a function
-        of context.
-      </p>
-      
-      <p>
-        Basically you give a decoder some of the substrate every so often
-        as more of the substrate is made available, then when a unit of 
-        encoded substrate has been decoded, the decoder notifies those 
-        concerned by invoking the callback.  
-      </p>
-      
-      <p>
-        A demonstration of how a StatefulDecoder works is illustrated below:
-      </p>
-      
-      <source>
-StatefulDecoder decoder = new SomeConcreteDecoder( 512 ) ;
-DecoderCallback cb = new DecoderCallback() {
-  decodeOccurred( StatefulDecoder decoder, Object decoded ) {
-      // do something with the decoded object
-  }
-};
-decoder.setCallback( cb ) ;
-      </source>
-      
-      <p>
-        The StatefulDecoder uses a callback to deliver decoded objects which 
-        are the decoded 'unit of encoded substrate'.  StatefulDecoders are ideal
-        for use in high performance servers based on non-blocking IO.   Often
-        StatefulDecoders will be used with a Selector in a loop to detect input
-        made available.  As the substrate arrives, it can be fed to the decoder
-        intermittantly.  Finally the callback delivers the decoded units of 
-        encoded substrate.  Below there is a trivialized example of how 
-        a StatefulDecoder can be used to decoded the substrate as it arrives 
-        fragmented by the tcp/ip stack:
-      </p>
-      
-      <source>
-while ( true ) {
-  ...
-  SelectionKey key = ( SelectionKey ) list.next() ;
-  if ( key.isReadable() ) {
-    SocketChannel channel = ( SocketChannel ) l_key.channel() ;
-    channel.read( buf ) ;
-    buf.flip() ;
-    decoder.decode( buf ) ;
-  }
-  ...
-}
-      </source>
-      
-      <p>
-        As you can see from the code fragment the decode() returns anything with
-        a void return type.  Because the callback is used to deliver the 
-        finished product when it is ready, the decode operation can occur 
-        asynchronously in another thread or stage of a server if so desired.  
-        This is what makes StatefulDecoders so simple yet powerful.
-      </p>
-    </section>
-    
-    <section name="Strengths and Weaknesses">
-      <p>
-        As can be seen from the section above and some of the characteristics 
-        of StatefulDecoders, they are ideal for building network servers.  These
-        decoders waste very little memory per request, cannot be overloaded by
-        massive requests which may be used for DoS attacks, and they process the
-        substrate as it arrives in chucks instead of in one prolonged CPU and 
-        memory intensive step.
-      </p>
-      
-      <p>
-        Servers with a high degree of concurrency need to keep overheads low.
-        StatefulDecoders certainly help achieve that end by keeping the
-        active processing footprint low with a constant size regardless of the 
-        size of the substrate.
-      </p>
-      
-      <p>
-        The cost of creating a decoder for every new connection is usually very
-        minimal however we cannot forsee every possible implementation.  
-        Regardless of the cost associated with dedicating a StatefulDecoder to
-        each new connection, stateful protocol servers will always pay a lesser
-        price.  The longer the life of the connection, the more worth while it
-        is to create a StatefulDecoder and thereby have it amortize over the 
-        life of the connection.
-      </p>
-      
-      <p>
-        StatefulDecoders are much more complex for implementors.  They are 
-        basically state driven automata which change their state with the
-        arrival of data.  Furthermoe it is very difficult for StatefulDecoders
-        to gracefully recover from corrupt or lost input.
-      </p>
-    </section>
-    
-    <section name="StatefulDecoder Chaining/Stacking">
-      <p>
-        StatefulDecoders can easily be chained or stacked to operate on a 
-        substrate stream.  This is achieved by having the callback of one 
-        decoder feed the <code>decode(Object)</code> method of another.  Hence
-        the decoded byproduct of one decoder is the encoded substrate of 
-        another.
-      </p>
-      
-      <p>
-        Because the occurence of chaining may be common and several folks have
-        already expressed their interest in it we have devised a special 
-        StatefulDecoder implementation called a DecoderStack.  It itself is 
-        a decoder however other decoders can be pushed onto it.  When empty
-        without any decoders in the stack it operates in pass-thro mode.  When
-        StatefulDecoders are pushed decode operations invoke a chain of decoders
-        starting with the bottom most in the stack going up to the top.  The
-        final callback is the callback registered with the DecoderStack.
-      </p>
-      
-      <p>
-        Below is an example of how this DecoderStack is used.  The example is
-        taken from one of the JUnit test cases for DecoderStack:
-      </p>
-
-      <source>
-public void testDecode() {
-  DecoderStack stack = new DecoderStack() ;
-  CallbackHistory history = new CallbackHistory() ;
-  stack.setCallback( history ) ;
-  stack.push( decoder ) ;
-  stack.decode( new Integer(0) ) ;
-  assertEquals( new Integer(0), history.getMostRecent() ) ;
-        
-  stack.push( new IncrementingDecoder() ) ;
-  stack.decode( new Integer(0) ) ;
-  assertEquals( new Integer(1), history.getMostRecent() ) ;
-
-  stack.push( new IncrementingDecoder() ) ;
-  stack.decode( new Integer(0) ) ;
-  assertEquals( new Integer(2), history.getMostRecent() ) ;
-}
-...
-
-class IncrementingDecoder extends AbstractStatefulDecoder
-{
-  public void decode( Object encoded ) throws DecoderException
-  {
-    Integer value = ( Integer ) encoded ;
-    value = new Integer( value.intValue() + 1 ) ;
-    super.decodeOccurred( value ) ;
-  }
-}
-      </source>      
-    </section>
-    
-    <section name="Recommendations to Implementors">
-      <p>
-        Keep it simple and rely on chaining to divide and concur complex 
-        decoders into several trivial decoders.  Besides simple chaining,  
-        situations will warrent the use of a choice driven decoder.  Such a 
-        decoder chooses which subordinate decoder to use based on its
-        current state.  For example in the simple BER byte stream to TLV 
-        decoder in Snickers, their is a TagDecoder, a LengthDecoder and
-        several Value decoders that are swapped in and out when the top 
-        BERDecoder switches state or detects a new primitive datatype.
-      </p>
-      
-      <p>
-        When reading encoded data from buffers, keep in mind that there are 
-        5 different possible configurations to the contents of arriving data 
-        with respect to the unit of encoded substrate:
-      </p>
-      
-      <ul>
-        <li>
-          it contains a single complete discrete unit of encoded substrate
-        </li>
-        <li>
-          it contains many discrete and complete units of encoded substrate
-        </li>
-        <li>
-          it contains a partial fragment of a unit of encoded substrate
-        </li>
-        <li>
-          it contains two partial fragments of a unit of encoded substrate with
-          the start of one and the end of another
-        </li>
-        <li>
-          it contains one or more fragments with one or more units of encoded 
-          substrate
-        </li>
-      </ul>
-      
-      <p>
-        When fragments arrive they are either head or tail fragments.  Head
-        fragments are those that start a unit and they are found at the end 
-        of the buffer.  Tail fragments end a unit of encoded substrate and are
-        found at the front of the buffer.
-      </p>
-    </section>
-  </body>
-</document>
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <title>Stateful Codecs</title>
+  </properties>
+  <body>
+    <section name="Introduction">
+      <p>
+        Stateful encoder and decoder pairs, or codecs for short, maintain state 
+        between respective operations.  By maintaining state in the codec all 
+        the data needed for the operation not be available at one time.  This 
+        leads to codecs with significantly reduced active footprints which are 
+        constant in size regardless of the size of the substrates they operate
+        upon.
+      </p>
+      
+      <p>
+        Furthermore Stateful codecs operate on data as it arrives instead of in
+        one shot.  This way the computational requirements are spread out over
+        time as the substrate is made available.
+      </p>
+      
+      <p>
+        Stateful codecs must be handled with care since they maintain the state
+        of an operation.  Stateful codecs must be dedicated to a serial 
+        stream of substrate objects whatever that may be.  This makes them ideal
+        for streams which have long lifespans however sensitive to the loss of 
+        data which may retard their state and require a reset.
+      </p>
+    </section>
+    
+    <section name="StatefulDecoder Usage">
+      <p>
+        StatefulDecoders use callbacks to notify the successful decode of a
+        unit of encoded substrate.  Other than this the definition of what a
+        'unit of encoded substrate' is depends on the codec's decoder 
+        implementation.  The definition may be size constrained or be a function
+        of context.
+      </p>
+      
+      <p>
+        Basically you give a decoder some of the substrate every so often
+        as more of the substrate is made available, then when a unit of 
+        encoded substrate has been decoded, the decoder notifies those 
+        concerned by invoking the callback.  
+      </p>
+      
+      <p>
+        A demonstration of how a StatefulDecoder works is illustrated below:
+      </p>
+      
+      <source>
+StatefulDecoder decoder = new SomeConcreteDecoder( 512 ) ;
+DecoderCallback cb = new DecoderCallback() {
+  decodeOccurred( StatefulDecoder decoder, Object decoded ) {
+      // do something with the decoded object
+  }
+};
+decoder.setCallback( cb ) ;
+      </source>
+      
+      <p>
+        The StatefulDecoder uses a callback to deliver decoded objects which 
+        are the decoded 'unit of encoded substrate'.  StatefulDecoders are ideal
+        for use in high performance servers based on non-blocking IO.   Often
+        StatefulDecoders will be used with a Selector in a loop to detect input
+        made available.  As the substrate arrives, it can be fed to the decoder
+        intermittantly.  Finally the callback delivers the decoded units of 
+        encoded substrate.  Below there is a trivialized example of how 
+        a StatefulDecoder can be used to decoded the substrate as it arrives 
+        fragmented by the tcp/ip stack:
+      </p>
+      
+      <source>
+while ( true ) {
+  ...
+  SelectionKey key = ( SelectionKey ) list.next() ;
+  if ( key.isReadable() ) {
+    SocketChannel channel = ( SocketChannel ) l_key.channel() ;
+    channel.read( buf ) ;
+    buf.flip() ;
+    decoder.decode( buf ) ;
+  }
+  ...
+}
+      </source>
+      
+      <p>
+        As you can see from the code fragment the decode() returns anything with
+        a void return type.  Because the callback is used to deliver the 
+        finished product when it is ready, the decode operation can occur 
+        asynchronously in another thread or stage of a server if so desired.  
+        This is what makes StatefulDecoders so simple yet powerful.
+      </p>
+    </section>
+    
+    <section name="Strengths and Weaknesses">
+      <p>
+        As can be seen from the section above and some of the characteristics 
+        of StatefulDecoders, they are ideal for building network servers.  These
+        decoders waste very little memory per request, cannot be overloaded by
+        massive requests which may be used for DoS attacks, and they process the
+        substrate as it arrives in chucks instead of in one prolonged CPU and 
+        memory intensive step.
+      </p>
+      
+      <p>
+        Servers with a high degree of concurrency need to keep overheads low.
+        StatefulDecoders certainly help achieve that end by keeping the
+        active processing footprint low with a constant size regardless of the 
+        size of the substrate.
+      </p>
+      
+      <p>
+        The cost of creating a decoder for every new connection is usually very
+        minimal however we cannot forsee every possible implementation.  
+        Regardless of the cost associated with dedicating a StatefulDecoder to
+        each new connection, stateful protocol servers will always pay a lesser
+        price.  The longer the life of the connection, the more worth while it
+        is to create a StatefulDecoder and thereby have it amortize over the 
+        life of the connection.
+      </p>
+      
+      <p>
+        StatefulDecoders are much more complex for implementors.  They are 
+        basically state driven automata which change their state with the
+        arrival of data.  Furthermoe it is very difficult for StatefulDecoders
+        to gracefully recover from corrupt or lost input.
+      </p>
+    </section>
+    
+    <section name="StatefulDecoder Chaining/Stacking">
+      <p>
+        StatefulDecoders can easily be chained or stacked to operate on a 
+        substrate stream.  This is achieved by having the callback of one 
+        decoder feed the <code>decode(Object)</code> method of another.  Hence
+        the decoded byproduct of one decoder is the encoded substrate of 
+        another.
+      </p>
+      
+      <p>
+        Because the occurence of chaining may be common and several folks have
+        already expressed their interest in it we have devised a special 
+        StatefulDecoder implementation called a DecoderStack.  It itself is 
+        a decoder however other decoders can be pushed onto it.  When empty
+        without any decoders in the stack it operates in pass-thro mode.  When
+        StatefulDecoders are pushed decode operations invoke a chain of decoders
+        starting with the bottom most in the stack going up to the top.  The
+        final callback is the callback registered with the DecoderStack.
+      </p>
+      
+      <p>
+        Below is an example of how this DecoderStack is used.  The example is
+        taken from one of the JUnit test cases for DecoderStack:
+      </p>
+
+      <source>
+public void testDecode() {
+  DecoderStack stack = new DecoderStack() ;
+  CallbackHistory history = new CallbackHistory() ;
+  stack.setCallback( history ) ;
+  stack.push( decoder ) ;
+  stack.decode( new Integer(0) ) ;
+  assertEquals( new Integer(0), history.getMostRecent() ) ;
+        
+  stack.push( new IncrementingDecoder() ) ;
+  stack.decode( new Integer(0) ) ;
+  assertEquals( new Integer(1), history.getMostRecent() ) ;
+
+  stack.push( new IncrementingDecoder() ) ;
+  stack.decode( new Integer(0) ) ;
+  assertEquals( new Integer(2), history.getMostRecent() ) ;
+}
+...
+
+class IncrementingDecoder extends AbstractStatefulDecoder
+{
+  public void decode( Object encoded ) throws DecoderException
+  {
+    Integer value = ( Integer ) encoded ;
+    value = new Integer( value.intValue() + 1 ) ;
+    super.decodeOccurred( value ) ;
+  }
+}
+      </source>      
+    </section>
+    
+    <section name="Recommendations to Implementors">
+      <p>
+        Keep it simple and rely on chaining to divide and concur complex 
+        decoders into several trivial decoders.  Besides simple chaining,  
+        situations will warrent the use of a choice driven decoder.  Such a 
+        decoder chooses which subordinate decoder to use based on its
+        current state.  For example in the simple BER byte stream to TLV 
+        decoder in Snickers, their is a TagDecoder, a LengthDecoder and
+        several Value decoders that are swapped in and out when the top 
+        BERDecoder switches state or detects a new primitive datatype.
+      </p>
+      
+      <p>
+        When reading encoded data from buffers, keep in mind that there are 
+        5 different possible configurations to the contents of arriving data 
+        with respect to the unit of encoded substrate:
+      </p>
+      
+      <ul>
+        <li>
+          it contains a single complete discrete unit of encoded substrate
+        </li>
+        <li>
+          it contains many discrete and complete units of encoded substrate
+        </li>
+        <li>
+          it contains a partial fragment of a unit of encoded substrate
+        </li>
+        <li>
+          it contains two partial fragments of a unit of encoded substrate with
+          the start of one and the end of another
+        </li>
+        <li>
+          it contains one or more fragments with one or more units of encoded 
+          substrate
+        </li>
+      </ul>
+      
+      <p>
+        When fragments arrive they are either head or tail fragments.  Head
+        fragments are those that start a unit and they are found at the end 
+        of the buffer.  Tail fragments end a unit of encoded substrate and are
+        found at the front of the buffer.
+      </p>
+    </section>
+  </body>
+</document>

Modified: incubator/directory/snickers/trunk/xdocs/codec-stateful/navigation.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/codec-stateful/navigation.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/codec-stateful/navigation.xml	Wed Apr 14 18:11:26
2004
@@ -1,55 +1,55 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<project>
-
- <title>Apache Directory Project</title>
-
- <body>
-
-    <links>
-      <item name="Apache" href="http://apache.org/"/>
-      <item name="Directory" href="../../index.html"/>
-      <item name="Eve" href="../eve/index.html"/>
-      <item name="RMS" href="../rms/index.html"/>
-      <item name="LDAP" href="../ldap/index.html"/>
-      <item name="Naming" href="../naming/index.html"/>
-      <item name="Janus" href="../janus/index.html"/>
-      <item name="Snickers" href="/index.html"/>
-      <item name="Sitedocs" href="../sitedocs/index.html"/>
-    </links>
-
-    <menu name="About Directory">
-      <item name="Overview" href="../../index.html"/>
-      <item name="Community" href="../../community/index.html"/>
-      <item name="Latest News" href="../../news.html"/>
-      <item name="Subprojects" href="../../index.html">
-        <item name="Eve" href="../eve/index.html"/>
-        <item name="RMS" href="../rms/index.html"/>
-        <item name="LDAP" href="../ldap/index.html"/>
-        <item name="Janus" href="../janus/index.html"/>
-        <item name="Naming" href="../naming/index.html"/>
-        <item name="Snickers" href="/index.html">
-          <item name="Stateful Codecs" href="/codec-stateful/index.html"/>
-          <item name="BER Codec" href="/ber-codec/index.html"/>
-          <item name="Stub Compiler" href="/stub-compiler/index.html"/>
-        </item>
-        <item name="Sitedocs" href="../sitedocs/index.html"/>
-      </item>
-      <item name="Documentation" href="../../doc/index.html"/>
-    </menu>
-
-    <menu name="Resources">
-      <item name="IRC" href="../../irc.html"/>
-      <item name="Jira" href=
-        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400"/>
-      <item name="Wiki" href="http://wiki.apache.org/directory"/>
-      <item name="Lists" href="../../mailing-lists.html"/>
-      <item name="License" href="../../license.html"/>
-      <item name="Sandbox" href="../../sandbox/index.html"/>
-      <item name="Downloads" href="../../download.cgi"/>
-      <item name="Subversion" href="../../svn.html"/>
-      <item name="Related Projects" href="../../related/index.html"/>
-    </menu>
- </body>
-
-</project>
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project>
+
+ <title>Apache Directory Project</title>
+
+ <body>
+
+    <links>
+      <item name="Apache" href="http://apache.org/"/>
+      <item name="Directory" href="../../index.html"/>
+      <item name="Eve" href="../eve/index.html"/>
+      <item name="RMS" href="../rms/index.html"/>
+      <item name="LDAP" href="../ldap/index.html"/>
+      <item name="Naming" href="../naming/index.html"/>
+      <item name="Janus" href="../janus/index.html"/>
+      <item name="Snickers" href="/index.html"/>
+      <item name="Sitedocs" href="../sitedocs/index.html"/>
+    </links>
+
+    <menu name="About Directory">
+      <item name="Overview" href="../../index.html"/>
+      <item name="Community" href="../../community/index.html"/>
+      <item name="Latest News" href="../../news.html"/>
+      <item name="Subprojects" href="../../index.html">
+        <item name="Eve" href="../eve/index.html"/>
+        <item name="RMS" href="../rms/index.html"/>
+        <item name="LDAP" href="../ldap/index.html"/>
+        <item name="Janus" href="../janus/index.html"/>
+        <item name="Naming" href="../naming/index.html"/>
+        <item name="Snickers" href="/index.html">
+          <item name="Stateful Codecs" href="/codec-stateful/index.html"/>
+          <item name="BER Codec" href="/ber-codec/index.html"/>
+          <item name="Stub Compiler" href="/stub-compiler/index.html"/>
+        </item>
+        <item name="Sitedocs" href="../sitedocs/index.html"/>
+      </item>
+      <item name="Documentation" href="../../doc/index.html"/>
+    </menu>
+
+    <menu name="Resources">
+      <item name="IRC" href="../../irc.html"/>
+      <item name="Jira" href=
+        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10515"/>
+      <item name="Wiki" href="http://wiki.apache.org/directory"/>
+      <item name="Lists" href="../../mailing-lists.html"/>
+      <item name="License" href="../../license.html"/>
+      <item name="Sandbox" href="../../sandbox/index.html"/>
+      <item name="Downloads" href="../../download.cgi"/>
+      <item name="Subversion" href="../../svn.html"/>
+      <item name="Related Projects" href="../../related/index.html"/>
+    </menu>
+ </body>
+
+</project>

Modified: incubator/directory/snickers/trunk/xdocs/index.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/index.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/index.xml	Wed Apr 14 18:11:26 2004
@@ -23,17 +23,17 @@
           <td>
             Candidates to serve as extended commons codec interfaces for
             stateful encode and decode operations.
-          </td>
+          </td>
         </tr>
-        
+        
         <tr>
           <td><a href="ber-codec/index.html">BER Codec</a></td>
           <td>
             ASN.1 data structures are encoded onto and decoded off of the wire
             using the Basic Encoding Rules (BER) codec.
-          </td>
+          </td>
         </tr>
-        
+        
         <tr>
           <td><a href="stub-compiler/index.html">Java Stub Compiler</a></td>
           <td>
@@ -43,7 +43,7 @@
             units (PDU).
           </td>
         </tr>
-      </table>
+      </table>
     </section>
 
     <section name="Motivation">
@@ -66,7 +66,7 @@
         require approximately twice the transfer footprint of a message to 
         decode it and there is no limit to the accepted transfer footprint size.
         DoS attacks could easily be mounted using a single large request to bog
-        down the server making it unresponsive.
+        down the server making it unresponsive.
       </p>
 
       <p>

Modified: incubator/directory/snickers/trunk/xdocs/navigation.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/navigation.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/navigation.xml	Wed Apr 14 18:11:26 2004
@@ -41,7 +41,7 @@
     <menu name="Resources">
       <item name="IRC" href="../../irc.html"/>
       <item name="Jira" href=
-        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400"/>
+        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10515"/>
       <item name="Wiki" href="http://wiki.apache.org/directory"/>
       <item name="Lists" href="../../mailing-lists.html"/>
       <item name="License" href="../../license.html"/>

Modified: incubator/directory/snickers/trunk/xdocs/stub-compiler/navigation.xml
==============================================================================
--- incubator/directory/snickers/trunk/xdocs/stub-compiler/navigation.xml	(original)
+++ incubator/directory/snickers/trunk/xdocs/stub-compiler/navigation.xml	Wed Apr 14 18:11:26
2004
@@ -41,7 +41,7 @@
     <menu name="Resources">
       <item name="IRC" href="../../irc.html"/>
       <item name="Jira" href=
-        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400"/>
+        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10515"/>
       <item name="Wiki" href="http://wiki.apache.org/directory"/>
       <item name="Lists" href="../../mailing-lists.html"/>
       <item name="License" href="../../license.html"/>

Mime
View raw message