directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 6991 - in incubator/directory/eve/trunk/eve/frontend/decoder: . spi spi/src spi/src/docbook spi/src/images spi/src/java spi/src/java/org spi/src/java/org/apache spi/src/java/org/apache/eve spi/src/java/org/apache/eve/decoder spi/xdocs
Date Thu, 04 Mar 2004 05:50:15 GMT
Author: akarasulu
Date: Wed Mar  3 21:50:14 2004
New Revision: 6991

Added:
   incubator/directory/eve/trunk/eve/frontend/decoder/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/project.xml
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/docbook/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/images/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/org/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/org/apache/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/org/apache/eve/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/org/apache/eve/decoder/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/org/apache/eve/decoder/DecoderManager.java
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/xdocs/
   incubator/directory/eve/trunk/eve/frontend/decoder/spi/xdocs/index.xml
Log:
Added decoder component interface.


Added: incubator/directory/eve/trunk/eve/frontend/decoder/spi/project.xml
==============================================================================
--- (empty file)
+++ incubator/directory/eve/trunk/eve/frontend/decoder/spi/project.xml	Wed Mar  3 21:50:14
2004
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project>
+    <extend>${basedir}/../../../project.xml</extend>
+    <groupId>directory</groupId>
+    <id>eve-frontend-decoder-spi</id>
+  
+    <name>Eve Frontend Decoder SPI</name>
+    <package>org.apache.eve.decoder</package>
+    <currentVersion>SNAPSHOT</currentVersion>
+    <inceptionYear>2003</inceptionYear>
+      
+    <shortDescription>Eve Frontend Decoder SPI</shortDescription>
+
+    <description>
+       The Decoder's service interface for the front end determines how
+       other components can interact with it to decode ASN.1 BER encoded
+       LDAPv3 messages into Java data structures representing the PDU.
+    </description>
+      
+    <dependencies>
+      <dependency>
+        <groupId>commons-codec</groupId>
+        <artifactId>commons-codec</artifactId>
+        <version>SNAPSHOT</version>
+        <url>http://jakarta.apache.org/commons/codec</url>
+      </dependency>
+      <dependency>
+        <groupId>directory</groupId>
+        <artifactId>eve-frontend-common-api</artifactId>
+        <version>SNAPSHOT</version>
+        <url>http://incubator.apache.org/directory/subprojects/eve/frontend/common/api</url>
+      </dependency>
+      <dependency>
+        <groupId>directory</groupId>
+        <artifactId>ldap-common</artifactId>
+        <version>SNAPSHOT</version>
+        <url>http://incubator.apache.org/directory/subprojects/ldap/common</url>
+      </dependency>
+    </dependencies>
+</project>
+

Added: incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/org/apache/eve/decoder/DecoderManager.java
==============================================================================
--- (empty file)
+++ incubator/directory/eve/trunk/eve/frontend/decoder/spi/src/java/org/apache/eve/decoder/DecoderManager.java
Wed Mar  3 21:50:14 2004
@@ -0,0 +1,73 @@
+/*
+ *   Copyright 2004 The Apache Software Foundation
+ *
+ *   Licensed 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.
+ *
+ */
+package org.apache.eve.decoder ;
+
+
+import java.nio.ByteBuffer ;
+
+import org.apache.eve.listener.ClientKey ;
+
+import org.apache.commons.codec.stateful.ErrorHandler ;
+import org.apache.commons.codec.stateful.DecoderCallback ;
+
+
+/**
+ * The DecoderManager creates, maintains and destroys StatefulDecoder instances,
+ * one dedicated per client.  The StatefulDecoder implementation decodes BER 
+ * encoded LDAPv3 messages into Message instances.
+ *
+ * @author <a href="mailto:directory-dev@incubator.apache.org">
+ * Apache Directory Project</a>
+ * @version $Rev$
+ */
+public interface DecoderManager
+{
+    /** Avalon likes to have the ROLE associated with the service interface */
+    String ROLE = DecoderManager.class.getName() ;
+
+    /**
+     * Sets a client decoder's callback.
+     * 
+     * @param key the unique key associated with the client
+     * @param cb the decoder callback used to deliver decode events to
+     */
+    void setCallback( ClientKey key, DecoderCallback cb ) ;
+    
+    /**
+     * Sets a client decoder's error handler.
+     * 
+     * @param key the unique key associated with the client
+     * @param cb the callback used to deliver error events
+     */
+    void setErrorHandler( ClientKey key, ErrorHandler handler ) ;
+    
+    /**
+     * Disables callback events for a client destroying decoding state if any.
+     * 
+     * @param key the unique key associated with the client
+     */
+    boolean disable( ClientKey key ) ;
+    
+    /**
+     * Decodes a buffer of encoded data.
+     * 
+     * @param key the unique key associated with the client
+     * @param buffer the buffer of encoded data
+     * @return the set of keys for decoding sessions
+     */
+    void decode( ClientKey key, ByteBuffer buffer ) ;
+}

Added: incubator/directory/eve/trunk/eve/frontend/decoder/spi/xdocs/index.xml
==============================================================================
--- (empty file)
+++ incubator/directory/eve/trunk/eve/frontend/decoder/spi/xdocs/index.xml	Wed Mar  3 21:50:14
2004
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <title></title>
+  </properties> 
+  
+  <body>
+    <section name="Decoder Introduction and Background">
+      <p>
+       A service interface for the front end to decode BER encoded ASN.1 
+       LDAPv3 Protocol Data Units and demarshal them into Java stubs.  It
+       is designed as an interface to a streaming decoder which can decode 
+       partial PDU's while maintaining the state of the decoding process for
+       a request.
+      </p>
+
+      <p>
+        The server is event driven and based on NIO non-blocking channels.  
+        Hence incoming requests may not arrive in one big complete chunk.  In 
+        fact reads from a client channel into a buffer may contain any number 
+        of requests, and at most two partial requests.  Then again each chunck
+        may nicely contain a single complete PDU image.  You just never know 
+        how the client and the server host operating systems are going to 
+        negotiate the transfers.  Also the size of the message might be huge 
+        containing attributes representing massive blob's like high resolution 
+        JPEG images taking the size of an entire screen or whatever.  Such a 
+        massive request would take multiple packets, reads and buffers to make 
+        its way to the decoder.  The decoder must correctly and efficiently
+        handle these messages for the server to perform well under heavy load.
+      </p>
+    </section>
+
+    <section name="Decoder Design">
+      <p>
+        Multiple approaches can be taken for a decoder design.  Non-blocking IO
+        makes localizing an entire message PDU at one time difficult as seen 
+        above.  The decoder must be prepared to get peices of the PDU at 
+        different times and hence manage a per request decoding session.  This
+        overwhelming aspect has the greatest effect on the decoder interface.
+      </p>
+      
+      <p>
+        The decode interface must provide a way to correlate chunk buffer 
+        contents with request decoding sessions.  Here's how we propose to do 
+        that.
+      </p>
+      
+      <p>
+        A decoder can take two approaches to decode a message.  The decoder can
+        collect all the arriving chunks and decode the entire PDU in one shot 
+        or decode the chunks as they arrive while maintaining the decoding 
+        state for the request.  The first option is inefficient.  It's how 
+        virtually every ASN.1 BER decoder works on the market and that's a 
+        shame.  The collect and decode in the one shot method we'll refer to as 
+        the brut force method.  The brut force method wastes resources and the 
+        waste is variable.  Consider the total footprint needed in memory to 
+        process a single request of size N bytes.  The collection buffer would 
+        be N bytes, which represents the PDU's transfer image.  When 
+        demarshalled into a message stub the image of the message probably takes
+        a tiny bit less memory than the actual transfer image.  Also the last
+        chunk triggers the decode and is held until the decoder finishes
+        actively decoding.  We can reasonably conclude that at the end of the 
+        decoding process a memory requirement of approximately 2N is needed for
+        each PDU of size N.  We can analyze this further within the appendix
+        section.
+      </p>
+      
+      <p>
+        The second approach where the decoder is a state machine started and 
+        stoped with the arrival of more data is ideal.  This is what allows the
+        streaming of content.  Servers designed with these constructs are much
+        more efficient and can hence support a higher degree of load.  Such a
+        decoder does not need the entire transfer image of the PDU in memory.
+        However if it returns the message it is still holding at least N + a 
+        chunk of memory when the decode completes.  This is still variable.
+      </p>
+      
+      <p>
+        The problem is with having all the data within the message.  This is
+        tolerable for small PDU's but not in the case of the PDU with 
+        massive JPEG attributes.  Holding the massive transfer image in memory
+        is wasteful.  The server's message framework can be designed to store 
+        and lazy load large blobs of binary data to and from disk.  Furthermore
+        these binary blobs are not usually indexed nor are they used in filter 
+        expressions on a search: you wouldn't use the bits of a friends JPEG to 
+        search for them in a directory would you?  So this info can be streamed
+        in and streamed out without having it all in memory at one time.  This
+        technique along with memory mapping IO can be used for breaking 
+        extremely high performance barriers for an LDAP server.
+      </p>
+      
+    </section>
+    
+    <!--
+        put this in an appendix        
+        
+        and the final demarshaled message produced from it would be almost 
+        the same size.  Basically the attribute size density of the PDU 
+        determines how many TLVs are in the message.  If this is high the 
+        structure to content information is high and the size of the message is
+        smaller than the PDU's transfer image.
+      
+    -->
+  </body>
+</document>
\ No newline at end of file

Mime
View raw message