You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by ak...@apache.org on 2004/02/03 07:30:38 UTC
svn commit: rev 6442 - in incubator/directory/eve/trunk/eve: . xdocs xdocs/backend xdocs/design xdocs/frontend xdocs/images
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"/>