directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 6442 - in incubator/directory/eve/trunk/eve: . xdocs xdocs/backend xdocs/design xdocs/frontend xdocs/images
Date Tue, 03 Feb 2004 06:30:38 GMT
Author: akarasulu
Date: Mon Feb  2 22:30:38 2004
New Revision: 6442

Added:
   incubator/directory/eve/trunk/eve/xdocs/design/scm.xml
   incubator/directory/eve/trunk/eve/xdocs/images/apache-incubator-logo.png   (contents, props
changed)
Modified:
   incubator/directory/eve/trunk/eve/project.xml
   incubator/directory/eve/trunk/eve/xdocs/backend/index.xml
   incubator/directory/eve/trunk/eve/xdocs/backend/navigation.xml
   incubator/directory/eve/trunk/eve/xdocs/design/components.xml
   incubator/directory/eve/trunk/eve/xdocs/design/index.xml
   incubator/directory/eve/trunk/eve/xdocs/design/navigation.xml
   incubator/directory/eve/trunk/eve/xdocs/frontend/index.xml
   incubator/directory/eve/trunk/eve/xdocs/frontend/navigation.xml
   incubator/directory/eve/trunk/eve/xdocs/index.xml
   incubator/directory/eve/trunk/eve/xdocs/navigation.xml
Log:
added more design documentation

Modified: incubator/directory/eve/trunk/eve/project.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/project.xml	(original)
+++ incubator/directory/eve/trunk/eve/project.xml	Mon Feb  2 22:30:38 2004
@@ -4,16 +4,19 @@
     <groupId>directory</groupId>
     <id>eve-directory-server</id>
     <name>Eve Directory Server</name>
-    <package>org.apache.eve</package>
-
-  <organization>
-      <name>The Apache Directory Project</name>
-      <url>http://incubator.apache.org/directory</url>
-      <logo>/images/apache-directory-logo.png</logo>
-  </organization>
+    
+    <organization>
+      <name>The Apache Incubator</name>
+      <url>http://incubator.apache.org</url>
+      <logo>/images/apache-incubator-logo.png</logo>
+    </organization>
 
     <inceptionYear>2003</inceptionYear>
-    <url>http://directory.apache.org/${module.path}modules</url>
+    <package>org.apache.eve</package>
+    
+    <logo>/images/apache-directory-logo.png</logo>
+    <url>http://incubator.apache.org/directory</url>
+    
     <issueTrackingUrl>
       http://nagoya.apache.org/scarab/servlet/scarab
     </issueTrackingUrl>
@@ -154,7 +157,7 @@
     	<report>maven-jxr-plugin</report>
     	<report>maven-license-plugin</report>
         <!-- report>maven-changelog-plugin</report -->
-        <report>maven-javadoc-plugin</report>
+        <!-- <report>maven-javadoc-plugin</report> -->
     	<report>maven-tasklist-plugin</report>
     </reports>
 </project>

Modified: incubator/directory/eve/trunk/eve/xdocs/backend/index.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/backend/index.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/backend/index.xml	Mon Feb  2 22:30:38 2004
@@ -5,32 +5,88 @@
     <title>Apache Directory Project: Eve Backend Subsystem</title>
   </properties>
   
-  <body>
-    <section name="Eve Backend Subsystem">
-      <subsection name="Overview">
+  <body>
+    
+          
+      <section name="Backend Subsystem Introduction">
         <p>
-          Coming soon ...
+          The backend subsystem is responsible for many different aspects of the
+          server besides just entry storage.  It is a major subsystem that 
+          contains within it other subsystems which in turn contain several
+          granular services implemented by components.  Although you'll have to
+          look into the detailed design of the backend and the other subsystems
+          composing it we have here a cursory overview of the responsibilities
+          of the entire backend subsystem:
         </p>
         
-        <table>
-          <tr>
-            <th>Heading I</th>
-            <th>Heading II</th>
-          </tr>
+        <ul>
+          <li>
+            manages multiple backends (a.k.a. partitions) each associated with
+            a naming context within the server
+          </li>
+          
+          <li>
+            maintains special system backends used to manage schema information 
+            and server (DSA) specific configuration information in addition to
+            backends used to manage application specific information
+          </li>
+          
+          <li>
+            decorates backend operations with orthogonal services using an
+            interceptor framework - the framework will be used to neatly manage
+            the following aspects possibly associated with backend system 
+            operations:
+            <ul>
+              <li>operation authorization on entries using ACLs</li>
+              <li>replication</li>
+              <li>schema checking</li>
+              <li>input normalization</li>
+              <li>trigger firing</li>
+              <li>error handling</li>
+              <li>transaction support</li>
+            </ul>
+          </li>
+          
+          <li>
+            manages Java and Groovy stored procedures
+          </li>
           
-          <tr>
-            <td>
-              Coming soon ...
-            </td>
-            <td>
-              <p>
-                Coming soon ...
-              </p>
-            </td>
-          </tr>
-        </table>
-      </subsection>
-
-    </section>
+          <li>
+            contains a server side JNDI provider which wraps the backend nexus
+            translating JNDI operations efficently to nexus operations where 
+            several backends hang.  The JNDI provider is intended for used 
+            within stored procedures to access backend entries.  This makes
+            stored procedures written in Java and Groovy operable within the
+            server as well as outside of it as remote procedures.
+          </li>
+        </ul>
+        
+        <p>
+          Together these subsystems are wrapped as one major system using JNDI 
+          as the top level facade.  The entire backend subsystem of Eve is
+          actually designed as a server side JNDI provider.  The frontend 
+          translates protocol requests into JNDI calls against the backend 
+          subsystem's JNDI Contexts to operate on entries.  
+        </p>
+        
+        <p>
+          The backend subsystem without the frontend itself is embeddable using
+          the JNDI to start up the backend.  JNDI is used to load the provider
+          in a fashion already familiar to those using JNDI.  So code written to
+          operate remotely against an LDAP server using the SUN JNDI LDAP 
+          provider can work locally against Eve's server side JNDI LDAP 
+          provider where the backend is embedded within the same process space.
+          Because we chose to push the interceptor framework into the backend 
+          all decorative services are available through the embedded backend
+          when used as a JNDI provider.  Meaning if you embed Eve's backend 
+          things like replication, schema checking and triggers are still active
+          and available without the frontend.
+        </p>
+        
+        <p>
+          There is are so many details to discuss however we leave these details
+          to more specific documentation in the sections below:
+        </p>
+      </section>
   </body>
 </document>

Modified: incubator/directory/eve/trunk/eve/xdocs/backend/navigation.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/backend/navigation.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/backend/navigation.xml	Mon Feb  2 22:30:38 2004
@@ -23,7 +23,7 @@
       <item name="Latest News" href="../../news.html"/>
       <item name="Sub-Projects" href="../../subprojects/index.html">
         <item name="Eve" href="/index.html">
-          <item name="Design" href="/design.html"/>
+          <item name="Design" href="/design/index.html"/>
           <item name="Features" href="/features.html"/>
           <item name="Backend" href="/backend/index.html"/>
           <item name="Frontend" href="/frontend/index.html"/>

Modified: incubator/directory/eve/trunk/eve/xdocs/design/components.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/design/components.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/design/components.xml	Mon Feb  2 22:30:38 2004
@@ -2,12 +2,29 @@
 <document>
   <properties>
     <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Apache Directory Project: Eve Directory Server</title>
+    <title>Apache Directory Project: Components and Services</title>
   </properties>
   
   <body>
+    <section name="TODO">
+      <ul>
+        <li>
+          Talk about not taking advantage of container specific functionality
+          within pojo implementations.
+        </li>
+        
+        <li>
+          Talk more about the service interface.  Talk about how dependencies 
+          are between services not components.
+        </li>
+        
+        <li>
+          Break this section down a little better.  It's all in one clump.
+        </li>
+      </ul>
+    </section>
+    
     <section name="Design">
-      
       <subsection name="Components and Services">
         <p>
           The server is designed as a system of highly granular components.
@@ -69,226 +86,6 @@
           another.
         </p>
       </subsection>
-
-      <subsection name="Project Layout">
-        <p>
-          Within the Subversion repository Eve contains several small Maven 
-          projects.  Each component within Eve has at least two separate Maven
-          projects.  The layout of component and API projects are based on
-          Eve's structure.
-        </p>
-        
-        <p>
-          Eve tries to make a logical distinction between various subsystems and
-          separates out its components in a heirarchy based on function within 
-          the source code repository.  The aspects of each subsystem shall be 
-          discussed in detail within the documentation set for that subsystem.  
-          Developers looking at Eve's source should know that the Subversion 
-          repository is structured to mimic this component containment 
-          heirarchy.  Here's a brief listing of the directory structure we're 
-          referring to:
-        </p>
-        
-        <source>
-eve                       -- holds Eve's top component projects and subsystems
-    ./frontend            -- holds frontend subsystem API and component projects
-        ./common          -- holds projects containing code common to components
-            ./api         -- holds API common to all components in frontend
-        ./buffer          -- holds buffer component projects
-            ./spi         -- holds buffer component SPI project
-            ./impl        -- holds buffer component implementation project
-        ./event           -- holds SEDA event dispatcher component projects
-            ./spi         -- holds event dispatcher component SPI project
-            ./impl        -- holds event dispatcher implementation project
-        </source>
-        
-        <p>
-          The structure above my nest deeper for other subsystems.  For example 
-          the backend subsystem has within it other sub subsystems.  Each 
-          subsystem itself is a new directory depth.  In turn this subsystem
-          may have other subsystems and or component directories that have an
-          SPI and an implementation project.  Some subsystems may have a common
-          API under a common directory used to centralize some classes shared 
-          by the subsystem.  This helps localize domain specific classes and 
-          interfaces and helps reduce the possibility of cyclic java class 
-          dependencies between component projects within the subsystem.  
-          Basically if there are classes that depend on each other but are 
-          kept apart in separate component projects, they create a dependency
-          between the two projects when both classes are needed by both 
-          projects.  To decouple these component projects we relocate these 
-          ancillary non SPI classes into the common API where possible.  This
-          way both component projects depend on a common API project rather than
-          each other.
-        </p>
-      </subsection>
-      
-      <subsection name="Frontend Subsystem Introduction">
-        <p>
-          At the topmost level Eve is composed of two major subsystems: the 
-          <a href="./frontend/index.html">frontend</a> subsystem and the 
-          <a href="./backend/index.html">backend</a> subsystem.
-        </p>
-        
-        <p>
-          As a network protocol server Eve handles LDAP requests and returns
-          zero or more responses for them.  The handling of these requests are 
-          the responsibility of the frontend subsystem.  The frontend listens 
-          for new client connections, services new requests for established 
-          client connections, decodes these requests, processes them and encodes
-          responses using BER encoding rules.  Components within the frontend
-          are designed to handle these specific frontend aspects.
-        </p>
-        
-        <p>
-          The frontend may have components swapped out to make it operate as a
-          X.500 directory or as an LDAP frontend to a X.500.  Both the encoding
-          and decoding of protocol responses and requests are handled by 
-          separate services.  Implementations of these services can encode or 
-          decode different kinds of BER messages.  One implementation is 
-          designed to work with the LDAP version 3 ASN.1 definition, and another
-          can be implemented to work with X.500 ASN.1 definitions.  X.500 now 
-          supports the TCP/IP stack in addition to the OSI stack so there is no 
-          need to swap out the network components.  All that would be required
-          to have the server frontend operate as an X.500 server frontend would
-          be the replacement of the set of services dealing with response 
-          encodeing and request decodeing.  The processing of these requests
-          will also change requiring a new set of request handlers in the heart 
-          of the protocol engine which is also designed as a service and 
-          implemented as a component.
-        </p>
-        
-        <p>
-          Eve's frontend LDAP request processing component is designed today 
-          to take each request and operate against a JNDI context using any
-          JNDI provider.  Hence the frontend can serve as a virtual directory
-          front'ing other LDAP servers or as a LDAP gateway to an X.500 
-          directory.
-        </p>
-        
-        <p>
-          The frontend is designed using a simplified form of Matt Welsh's 
-          <a href="http://www.eecs.harvard.edu/~mdw/proj/seda/">Staged Event 
-          Driven Architecture</a> (SEDA).  A short description of SEDA is 
-          from Matt Welsh is quoted in the source block below:
-        </p>
-        
-        <source>
-SEDA is an acronym for staged event-driven architecture, and decomposes a 
-complex, event-driven application into a set of stages connected by queues. 
-This design avoids the high overhead associated with thread-based concurrency 
-models, and decouples event and thread scheduling from application logic. 
-By performing admission control on each event queue, the service can be 
-well-conditioned to load, preventing resources from being overcommitted when 
-demand exceeds service capacity. SEDA employs dynamic control to automatically 
-tune runtime parameters (such as the scheduling parameters of each stage), as 
-well as to manage load, for example, by performing adaptive load shedding. 
-Decomposing services into a set of stages also enables modularity and code 
-reuse, as well as the development of debugging tools for complex event-driven 
-applications. 
-        </source>
-          
-        <p>
-          The frontend has been designed around the non-blocking channels of 
-          the NIO package to handle small chunks of arriving data when that IO 
-          is available.  The processing of each chunk is staged in the server 
-          and eventually the request built from these peices is itself processed
-          in a staged manner.  Our SEDA alignment is very simple without some 
-          of the bells and whistles used for the dynamic control of load sheding
-          and so on.  We would like to wreak the benefits of high concurrency
-          without all the extra features for now at least.
-        </p>
-        
-        <p>
-          Eve's frontend subsystem is very flexible.  It's based on a granular 
-          set of services and their component implementations.  Everything is 
-          plugable and can be reconfigured for different fuctions or swapped out
-          for experimentation.  Furthermore the frontend uses JNDI as the 
-          coupling interface between it and other systems including the backend
-          subsystem so it's very generic.
-        </p>
-      </subsection>
-      
-      <subsection name="Backend Subsystem Introduction">
-        <p>
-          The backend subsystem is responsible for many different aspects of the
-          server besides just entry storage.  It is a major subsystem that 
-          contains within it other subsystems which in turn contain several
-          granular services implemented by components.  Although you'll have to
-          look into the detailed design of the backend and the other subsystems
-          composing it we have here a cursory overview of the responsibilities
-          of the entire backend subsystem:
-        </p>
-        
-        <ul>
-          <li>
-            manages multiple backends (a.k.a. partitions) each associated with
-            a naming context within the server
-          </li>
-          
-          <li>
-            maintains special system backends used to manage schema information 
-            and server (DSA) specific configuration information in addition to
-            backends used to manage application specific information
-          </li>
-          
-          <li>
-            decorates backend operations with orthogonal services using an
-            interceptor framework - the framework will be used to neatly manage
-            the following aspects possibly associated with backend system 
-            operations:
-            <ul>
-              <li>operation authorization on entries using ACLs</li>
-              <li>replication</li>
-              <li>schema checking</li>
-              <li>input normalization</li>
-              <li>trigger firing</li>
-              <li>error handling</li>
-              <li>transaction support</li>
-            </ul>
-          </li>
-          
-          <li>
-            manages Java and Groovy stored procedures
-          </li>
-          
-          <li>
-            contains a server side JNDI provider which wraps the backend nexus
-            translating JNDI operations efficently to nexus operations where 
-            several backends hang.  The JNDI provider is intended for used 
-            within stored procedures to access backend entries.  This makes
-            stored procedures written in Java and Groovy operable within the
-            server as well as outside of it as remote procedures.
-          </li>
-        </ul>
-        
-        <p>
-          Together these subsystems are wrapped as one major system using JNDI 
-          as the top level facade.  The entire backend subsystem of Eve is
-          actually designed as a server side JNDI provider.  The frontend 
-          translates protocol requests into JNDI calls against the backend 
-          subsystem's JNDI Contexts to operate on entries.  
-        </p>
-        
-        <p>
-          The backend subsystem without the frontend itself is embeddable using
-          the JNDI to start up the backend.  JNDI is used to load the provider
-          in a fashion already familiar to those using JNDI.  So code written to
-          operate remotely against an LDAP server using the SUN JNDI LDAP 
-          provider can work locally against Eve's server side JNDI LDAP 
-          provider where the backend is embedded within the same process space.
-          Because we chose to push the interceptor framework into the backend 
-          all decorative services are available through the embedded backend
-          when used as a JNDI provider.  Meaning if you embed Eve's backend 
-          things like replication, schema checking and triggers are still active
-          and available without the frontend.
-        </p>
-        
-        <p>
-          There is are so many details to discuss however we leave these details
-          to more specific documentation in the sections below:
-        </p>
-      </subsection>
     </section>
-    
   </body>
 </document>

Modified: incubator/directory/eve/trunk/eve/xdocs/design/index.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/design/index.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/design/index.xml	Mon Feb  2 22:30:38 2004
@@ -7,30 +7,40 @@
   
   <body>
     <section name="Design Overview">
-      <subsection name="Overview">
-        <p>
-          Coming soon ...
-        </p>
+      <p>
+        Here we cover some general design decisions.  Other specific designs 
+        localized to subsystems and/or components are discussed in those regions
+        of the documentation at greater detail.  Here we discuss the high level
+        common architecture of the server and the organization of its source.
+      </p>
+      
+      <table>
+        <tr>
+          <th>Topic</th>
+          <th>Description</th>
+        </tr>
         
-        <table>
-          <tr>
-            <th>Heading I</th>
-            <th>Heading II</th>
-          </tr>
-          
-          <tr>
-            <td>
-              Coming soon ...
-            </td>
-            <td>
-              <p>
-                Coming soon ...
-              </p>
-            </td>
-          </tr>
-        </table>
-      </subsection>
+        <tr>
+          <td>
+            <a href="./scm.html">SCM</a>
+          </td>
+          <td>
+            As with every large code base the source must be managed properly.  
+            This section discusses Eve's source code layout within the 
+            repository and how it is used to build and manage developement.
+          </td>
+        </tr>
 
+        <tr>
+          <td>
+            <a href="./components.html">Components</a>
+          </td>
+          <td>
+            Eve is a system made up of several components.  The aspects 
+            associated with Eve's component based design are discussed here.
+          </td>
+        </tr>
+      </table>
     </section>
   </body>
 </document>

Modified: incubator/directory/eve/trunk/eve/xdocs/design/navigation.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/design/navigation.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/design/navigation.xml	Mon Feb  2 22:30:38 2004
@@ -23,8 +23,9 @@
       <item name="Latest News" href="../../news.html"/>
       <item name="Sub-Projects" href="../../subprojects/index.html">
         <item name="Eve" href="/index.html">
-          <item name="Design" href="/index.html">
-            <item name="Components" href="/design/components.html">
+          <item name="Design" href="/design/index.html">
+            <item name="SCM" href="/design/scm.html"/>
+            <item name="Components" href="/design/components.html"/>
           </item>  
           <item name="Features" href="/features.html"/>
           <item name="Backend" href="/backend/index.html"/>

Added: incubator/directory/eve/trunk/eve/xdocs/design/scm.xml
==============================================================================
--- (empty file)
+++ incubator/directory/eve/trunk/eve/xdocs/design/scm.xml	Mon Feb  2 22:30:38 2004
@@ -0,0 +1,292 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <title>Apache Directory Project: Software Configuration Management</title>
+  </properties>
+  
+  <body>
+    <section name="Overview">
+      <p>
+        The design for a project has as much to do with how the source code is 
+        organized as it does the structure of the program.  This section 
+        discusses the software configuration management principals used to 
+        organize, maintain and build Eve's code base.
+      </p>
+      <p>
+        After reading this section you should have gained the following:
+      </p>
+      
+      <ul>
+        <li>
+          Know how the repo is organized and why
+        </li>
+          
+        <li>
+          Ability to navigate source and add to it
+        </li>
+        
+        <li>
+          Know how to build and deploy Eve
+        </li>
+      </ul>
+    </section>
+      
+    <section name="Resources">
+      <p>
+        While reading the next section you might want to use the following 
+        resources:
+      </p>
+        
+      <table>
+        <tr><th>Resource</th></tr>
+        <tr>
+          <td><a href="http://cvs.apache.org/viewcvs.cgi/incubator/directory/eve/trunk/eve?root=Apache-SVN">
+          Eve's Subversion Repository</a></td>
+        </tr>
+          
+        <tr><td>
+          <a href="../../../svn.html">
+          Subversion Documentation</a></td>
+        </tr>
+      </table>
+    </section>
+
+    <section name="Organization">
+      <subsection name="Repository Layout">
+        <p>
+          Within the Subversion repository Eve contains several small Maven 
+          projects that are consolidated into groups based on subsystem.  Each 
+          component within Eve has at least two separate Maven
+          projects.  The layout of component and API projects are based on
+          Eve's structure.
+        </p>
+        
+        <p>
+          A logical distinction is made between various subsystems whose 
+          components are separated out in a heirarchy based on function within 
+          the source code repository.  The aspects of each subsystem shall be 
+          discussed in detail within the documentation set for that subsystem.  
+          Developers looking at Eve's source should know that the Subversion 
+          repository is structured to mimic this component containment 
+          heirarchy.  Here's a brief listing of the directory structure we're 
+          referring to:
+        </p>
+        
+        <source>
+./eve               -- top component projects and subsystems
+  ./frontend        -- contains frontend subsystem APIs and service projects
+    ./common        -- contains shared code common to frontend subsystem
+      ./api         -- API common to all projects in frontend
+    ./buffer        -- frontend buffer service projects
+      ./spi         -- frontend buffer service provider interface project
+      ./pojo-impl   -- frontend buffer component POJO implementation project
+      ./merlin-impl -- frontend buffer component Merlin implementation project
+    ./event         -- frontend SEDA event dispatcher service projects
+      ./spi         -- frontend event dispatcher SPI project
+      ./pojo-impl   -- frontend event dispatcher POJO implementation project
+      ./merlin-impl -- frontend event dispatcher Merlin wrapper impl project
+      ...
+  ./backend
+      ...
+        </source>
+        
+        <p>
+          The structure above my nest deeper for other subsystems.  For example 
+          the backend subsystem has within it other sub subsystems.  Each nested
+          subsystem adds an extra level of directory depth.  In turn this 
+          subsystem may have other subsystems and/or component directories that 
+          have an SPI and an implementation project.
+        </p>
+      </subsection>
+      
+      <subsection name="Subsystem Directories and Common APIs">   
+        <p>
+          Eve is composed of components and these components are logically 
+          grouped into subsystems.  For more on Eve's component oriented design
+          aspects take a look <a href="./components.html">here</a>.
+        </p>
+        
+        <p>
+          Subsystems may contain a common directory used to centralize some 
+          classes shared by the subsystem as a common subsystem API of sorts.
+          Centralization of common code helps localize domain specific classes 
+          and interfaces for a subsystem assigned to a specific function.  Take
+          for example the minor schema subsystem which resides under the 
+          backend subsystem.  The schema subsystem contains a common API for 
+          the various interfaces and classes representing schema objects found 
+          within LDAP and X.500.
+        </p>
+        
+        <p>
+          The most benefit we gain from these subsystem common APIs is in the
+          area of project dependency management.  Natural class dependencies
+          will exist within a subsystem.  When dependent classes are distributed
+          across several Maven projects within the subsystem interproject 
+          dependencies are introduced.  By design dependencies between projects
+          will exist to lightly couple the subsystem.  However these class 
+          dependencies should not drive the project dependencies between 
+          services and components.  If class dependencies are allowed to drive
+          project dependencies, you quickly find a web of cyclic project 
+          dependencies creating build problems.
+        </p>
+      </subsection>
+      
+      <subsection name="Service/Component Directories">
+        <p>
+          The COP based approach as we said is discussed in more detail 
+          within the component design documentation.  However we discuss the
+          effects this has on the layout of the subsystem services and the 
+          components that implement them within the software repository.
+        </p>
+        
+        <p>
+          Components have a service interface and one or more implementations.
+          For reasons described within component documentation we separate out 
+          the service interface into its own jar along with other helper classes
+          and interfaces.  Each implementation is also packaged into its own 
+          jar.  Each jar is essentially built by a separate Maven project.  For 
+          each service within a subsystem, a top level directory is named after 
+          the service like the <em>eve/frontend/buffer</em> directory for the

+          buffer service within the frontend subsystem.  The buffer service 
+          creates and pools expensive direct memory buffers for the frontend.  
+          The service interface is kept within an <em>'spi'</em> project 
+          directory and an implementation is defined within a <em>'pojo-impl'
+          </em> directory.  Other implementations of the service may also get 
+          their own directory.  For example the Merlin specific wrappers may be 
+          packaged under another implementation directory like <em>'merlin-impl'
+          </em>.
+        </p>
+        
+        <p>
+          The service directory layout pattern is simple and outlined below:
+        </p>
+        
+        <table>
+          <tr><th>Directory</th><th>Purpose</th><th>Number</th></tr>
+          
+          <tr>
+            <td>
+              *spi
+            </td>
+            <td>
+              contains the SPI jar project
+            </td>
+            <td>
+              In the immortal words of the highlander, "there can only be one!"
+            </td>
+          </tr>
+          
+          <tr>
+            <td>
+              *pojo-impl
+            </td>
+            <td>
+              contains projects for components that implement the service and
+              are plain old java objects: they depend on the SPI project
+            </td>
+            <td>
+              one or more: some services have bootstrap and solidstate versions
+              and may have more than one implementation
+            </td>
+          </tr>
+          
+          <tr>
+            <td>
+              [container]-*-impl
+            </td>
+            <td>
+              contains projects for components that implement the service and
+              are wrappers around the plain old java objects for specific 
+              containers: they depend on the SPI project and the POJO
+              implementations.  Examples are merlin-impl, loom-impl ...
+            </td>
+            <td>
+              one or more: when we start amassing wrappers for various IoC 
+              containers we'll add them here.
+            </td>
+          </tr>
+          
+        </table>
+      </subsection>
+      
+      <subsection name="Why go to such lengths?">
+        <p>
+          One might ask why we have gone to such lengths to separate out our 
+          code in this fashion with projects for each service SPI and projects
+          for each implementation.
+        </p>
+        
+        <ul>
+          <li>
+            Source code configuration is just as important as the code, 
+            sometimes more so - going the distance is worth it.
+          </li>
+          
+          <li>
+            Clean and clear management of project dependencies.
+          </li>
+          
+          <li>
+            Project directory names clearly imply the purpose.  SPI is for
+            service interfaces.  And the implementations can be differentiated
+            with respect to their design (POJO) or the container they're 
+            destined to run in.
+          </li>
+          
+          <li>
+            Conformance to this pattern down the road will make configuration
+            and deployment to various containers easier to maintain and 
+            fuctionality to perform these tasks may be shared.
+          </li>
+          
+          <li>
+            Container Classloader heirachies can hang multiple implementations
+            under an SPI Classloader if the SPI and implementations are kept
+            separate.
+          </li>
+        
+          <li>
+            A separation of concerns: those interested in a specific container 
+            don't care about the wrapper implementation, setup and configuration
+            of the wrapper implementations for other containers.
+          </li>
+          
+          <li>
+            One pleseant side-effect is that it makes people stop and think 
+            about what they are doing in terms of service interfaces and 
+            component implementations.
+          </li>
+          
+          <li>
+            It makes sense to keep a subsystem's nested subsystems and its 
+            services together under one directory.  This way the directory
+            heirarchy models the project and service dependencies within the
+            system.
+          </li>
+
+          <li>
+            It makes sense to keep the implementations of a service interface
+            together under on umbrella directory for the service.
+          </li>
+        </ul>
+      </subsection>
+    </section>
+      
+    <section name="Building Eve">
+      <p>
+        Put something here about how we use maven and talk about reactor and
+        the organization of projects.  Talk about documentation and site
+        content generation.  Talk about the use of a component documentation
+        plugin.
+      </p>
+    </section>
+      
+    <section name="Deploying Eve">
+      <p>
+        Talk about deployment tools and issues pertaining to the container.
+      </p>
+    </section>
+      
+  </body>
+</document>
\ No newline at end of file

Modified: incubator/directory/eve/trunk/eve/xdocs/frontend/index.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/frontend/index.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/frontend/index.xml	Mon Feb  2 22:30:38 2004
@@ -5,32 +5,93 @@
     <title>Apache Directory Project: Eve Frontend Subsystem</title>
   </properties>
   
-  <body>
-    <section name="Eve Frontend Subsystem">
-      <subsection name="Overview">
-        <p>
-          Coming soon ...
+  <body>
+    
+          
+      <section name="Frontend Subsystem Introduction">
+        <p>
+          At the topmost level Eve is composed of two major subsystems: the 
+          <a href="./index.html">frontend</a> subsystem and the 
+          <a href="../backend/index.html">backend</a> subsystem.
+        </p>
+        
+        <p>
+          As a network protocol server Eve handles LDAP requests and returns
+          zero or more responses for them.  The handling of these requests are 
+          the responsibility of the frontend subsystem.  The frontend listens 
+          for new client connections, services new requests for established 
+          client connections, decodes these requests, processes them and encodes
+          responses using BER encoding rules.  Components within the frontend
+          are designed to handle these specific frontend aspects.
         </p>
         
-        <table>
-          <tr>
-            <th>Heading I</th>
-            <th>Heading II</th>
-          </tr>
+        <p>
+          The frontend may have components swapped out to make it operate as a
+          X.500 directory or as an LDAP frontend to a X.500.  Both the encoding
+          and decoding of protocol responses and requests are handled by 
+          separate services.  Implementations of these services can encode or 
+          decode different kinds of BER messages.  One implementation is 
+          designed to work with the LDAP version 3 ASN.1 definition, and another
+          can be implemented to work with X.500 ASN.1 definitions.  X.500 now 
+          supports the TCP/IP stack in addition to the OSI stack so there is no 
+          need to swap out the network components.  All that would be required
+          to have the server frontend operate as an X.500 server frontend would
+          be the replacement of the set of services dealing with response 
+          encodeing and request decodeing.  The processing of these requests
+          will also change requiring a new set of request handlers in the heart 
+          of the protocol engine which is also designed as a service and 
+          implemented as a component.
+        </p>
+        
+        <p>
+          Eve's frontend LDAP request processing component is designed today 
+          to take each request and operate against a JNDI context using any
+          JNDI provider.  Hence the frontend can serve as a virtual directory
+          front'ing other LDAP servers or as a LDAP gateway to an X.500 
+          directory.
+        </p>
+        
+        <p>
+          The frontend is designed using a simplified form of Matt Welsh's 
+          <a href="http://www.eecs.harvard.edu/~mdw/proj/seda/">Staged Event 
+          Driven Architecture</a> (SEDA).  A short description of SEDA is 
+          from Matt Welsh is quoted in the source block below:
+        </p>
+        
+        <source>
+SEDA is an acronym for staged event-driven architecture, and decomposes a 
+complex, event-driven application into a set of stages connected by queues. 
+This design avoids the high overhead associated with thread-based concurrency 
+models, and decouples event and thread scheduling from application logic. 
+By performing admission control on each event queue, the service can be 
+well-conditioned to load, preventing resources from being overcommitted when 
+demand exceeds service capacity. SEDA employs dynamic control to automatically 
+tune runtime parameters (such as the scheduling parameters of each stage), as 
+well as to manage load, for example, by performing adaptive load shedding. 
+Decomposing services into a set of stages also enables modularity and code 
+reuse, as well as the development of debugging tools for complex event-driven 
+applications. 
+        </source>
           
-          <tr>
-            <td>
-              Coming soon ...
-            </td>
-            <td>
-              <p>
-                Coming soon ...
-              </p>
-            </td>
-          </tr>
-        </table>
-      </subsection>
-
-    </section>
+        <p>
+          The frontend has been designed around the non-blocking channels of 
+          the NIO package to handle small chunks of arriving data when that IO 
+          is available.  The processing of each chunk is staged in the server 
+          and eventually the request built from these peices is itself processed
+          in a staged manner.  Our SEDA alignment is very simple without some 
+          of the bells and whistles used for the dynamic control of load sheding
+          and so on.  We would like to wreak the benefits of high concurrency
+          without all the extra features for now at least.
+        </p>
+        
+        <p>
+          Eve's frontend subsystem is very flexible.  It's based on a granular 
+          set of services and their component implementations.  Everything is 
+          plugable and can be reconfigured for different fuctions or swapped out
+          for experimentation.  Furthermore the frontend uses JNDI as the 
+          coupling interface between it and other systems including the backend
+          subsystem so it's very generic.
+        </p>
+      </section>
   </body>
 </document>

Modified: incubator/directory/eve/trunk/eve/xdocs/frontend/navigation.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/frontend/navigation.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/frontend/navigation.xml	Mon Feb  2 22:30:38 2004
@@ -23,7 +23,7 @@
       <item name="Latest News" href="../../news.html"/>
       <item name="Sub-Projects" href="../../subprojects/index.html">
         <item name="Eve" href="/index.html">
-          <item name="Design" href="/design.html"/>
+          <item name="Design" href="/design/index.html"/>
           <item name="Features" href="/features.html"/>
           <item name="Backend" href="/backend/index.html"/>
           <item name="Frontend" href="/frontend/index.html"/>

Added: incubator/directory/eve/trunk/eve/xdocs/images/apache-incubator-logo.png
==============================================================================
Binary file. No diff available.

Modified: incubator/directory/eve/trunk/eve/xdocs/index.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/index.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/index.xml	Mon Feb  2 22:30:38 2004
@@ -7,29 +7,54 @@
   
   <body>
     <section name="Overview">
-      <subsection name="">
-        <p>
-          Coming soon ...
-        </p>
+      <p>Welcome to the Eve Directory Server Homepage!</p>
+      <p>
+        Eve is a modular LDAP server written in pure Java.
+      </p>
+      
+      <table>
+        <tr>
+          <th>Topic</th>
+          <th>Description</th>
+        </tr>
         
-        <table>
-          <tr>
-            <th>Heading I</th>
-            <th>Heading II</th>
-          </tr>
-          
-          <tr>
-            <td>
-              Coming soon ...
-            </td>
-            <td>
-              <p>
-                Coming soon ...
-              </p>
-            </td>
-          </tr>
-        </table>
-      </subsection>
+        <tr>
+          <td>
+            <a href="./features.html">Features</a>
+          </td>
+          <td>
+            Eve's existing and planned features
+          </td>
+        </tr>
+        
+        <tr>
+          <td>
+            <a href="./design/index.html">Design</a>
+          </td>
+          <td>
+            Documentation regarding high level design
+          </td>
+        </tr>
+        
+        <tr>
+          <td>
+            <a href="./frontend/index.html">Frontend Design</a>
+          </td>
+          <td>
+            Server's frontend design documentation
+          </td>
+        </tr>
+        
+        <tr>
+          <td>
+            <a href="./backend/index.html">Backend Design</a>
+          </td>
+          <td>
+            Server's backend design documentation
+          </td>
+        </tr>
+        
+      </table>
 
     </section>
   </body>

Modified: incubator/directory/eve/trunk/eve/xdocs/navigation.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/navigation.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/navigation.xml	Mon Feb  2 22:30:38 2004
@@ -23,7 +23,7 @@
       <item name="Latest News" href="../../news.html"/>
       <item name="Sub-Projects" href="../../subprojects/index.html">
         <item name="Eve" href="/index.html">
-          <item name="Design" href="/design.html"/>
+          <item name="Design" href="/design/index.html"/>
           <item name="Features" href="/features.html"/>
           <item name="Backend" href="/backend/index.html"/>
           <item name="Frontend" href="/frontend/index.html"/>

Mime
View raw message