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/07 20:50:02 UTC
svn commit: rev 6559 - in incubator/directory/eve/trunk/eve/xdocs: frontend images
Author: akarasulu
Date: Sat Feb 7 11:50:01 2004
New Revision: 6559
Added:
incubator/directory/eve/trunk/eve/xdocs/images/dependencies-with-events.gif (contents, props changed)
incubator/directory/eve/trunk/eve/xdocs/images/dependencies-without-events.gif (contents, props changed)
Modified:
incubator/directory/eve/trunk/eve/xdocs/frontend/events.xml
incubator/directory/eve/trunk/eve/xdocs/frontend/requirements.xml
incubator/directory/eve/trunk/eve/xdocs/frontend/status.xml (contents, props changed)
incubator/directory/eve/trunk/eve/xdocs/frontend/x.500-ldap.xml
Log:
added the requirments, events, status and x.500 content
Modified: incubator/directory/eve/trunk/eve/xdocs/frontend/events.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/frontend/events.xml (original)
+++ incubator/directory/eve/trunk/eve/xdocs/frontend/events.xml Sat Feb 7 11:50:01 2004
@@ -6,28 +6,235 @@
</properties>
<body>
- <section name="Event Decoupling">
- <p>Coming soon ...</p>
- <!--
- <subsection name="">
+ <section name="Event Notification Pattern">
+ <p>
+ The Event Notification Pattern is used to allow components to react to
+ events in other components without having to know about the existance
+ of other components.
+ </p>
+
+ <p>
+ The pattern is also known as the dispatcher, decoupler, and publish
+ subscribe pattern. For more information regarding this pattern look
+ at this <a href="http://members.ispwest.com/jeffhartkopf/notifier/">
+ article</a>. Or you can look at the documentation for our event
+ <a href="./components/event/index.html">notification</a> service and
+ its implementation which is an exact manifestation of this pattern as
+ it is described in the artical.
+ </p>
+ </section>
+
+ <section name="Reducing Simple and Cyclic Dependencies">
+ <p>
+ Using events to drive communication between components reduces
+ dependencies between them. The frontend subsystem uses a centralized
+ event service to implement the event notification pattern to have
+ components communicate with one another using events. The use of
+ the event notification pattern and a common API decouples components
+ preventing simple and cyclic dependencies between components and their
+ Maven projects.
+ </p>
+
+ <subsection name="Dependencies Without Events">
<p>
+ Without events, components within the server would interdepend on one
+ another through their service interfaces. For example a dependent
+ component 'FooImpl' may depend on the dependecy, service Bar, which is
+ implemented by component 'BarImpl'. Component FooImpl must be aware
+ of service Bar and is dependent on having at least one component that
+ implements it. FooImpl must be aware of service interface Bar to call
+ methods on it say for example <em>process(Buffer)</em>. The
+ component diagram below depicts this relationship:
</p>
+
+ <center>
+ <img src="../images/dependencies-without-events.gif"/>
+ </center>
+
+ <p>
+ The dependency between the class FooImpl and the Bar service
+ interface makes the the foo-pojo-impl Maven project depend on the
+ bar-spi Maven project. That's the only way to get FooImpl to see
+ Bar.
+ </p>
+
+ <table>
+ <tr><th>NOTE</th></tr>
+ <tr>
+ <td>
+ <p>
+ Every component has an spi and a pojo-impl Maven project and
+ one or more container specific wrapper projects. For more info
+ consult the <a href="../source-layout.html">source organization
+ </a> documentation.
+ </p>
+ </td>
+ </tr>
+ </table>
+
<p>
+ Here's what the project interdependencies look like for the example
+ diagramed above:
+ </p>
+
+ <table>
+ <tr><th>Dependent</th><th>Dependency</th><th>Dangerous?</th></tr>
+ <tr>
+ <td>foo-pojo-impl</td>
+ <td>foo-spi</td>
+ <td>Harmless</td>
+ </tr>
+ <tr>
+ <td>foo-pojo-impl</td>
+ <td>bar-spi</td>
+ <td>Harmful</td>
+ </tr>
+ </table>
+
+ <p>
+ We can't avoid dependencies but we need to differentiate between
+ ones that are harmful and ones that are not. And so this brings us
+ to the topic of whether or not a dependency is 'Dangerous?' Harmful
+ dependencies are ones that create interdependencies between
+ implementation and service projects. The only exception to this is
+ when the dependency is to a service that we know is terminal: its
+ implementations now and forever will not depend on other system
+ services or components.
</p>
</subsection>
+
+ <subsection name="Dependencies With Events">
+ <p>
+ Instead of having components depend on the service interfaces
+ implemented by other components we use events to decouple them.
+ Continuing the example above, component FooImpl produces and
+ publishes FooEvents using a centralized event publisher service.
+ Service Bar's implementation component, BarImpl subscribes for
+ FooEvents. When BarImpl encounters a FooEvent an event handler
+ invokes the appropriate method <em>process(Buffer)</em> using
+ the Buffer payload packaged with FooEvent. This way FooImpl need
+ not be aware of service interface Bar and how to invoke the
+ <em>process(Buffer)</em> method on components implementing it.
+ FooImpl just lets everyone subscribed know that it has completed some
+ task that created data in the Buffer by publishing a FooEvent.
+ There is no dependency between FooImpl and service interface Bar
+ anymore as depicted below.
+ </p>
+
+ <center>
+ <img src="../images/dependencies-with-events.gif"/>
+ </center>
+
+ <p>
+ The dependency of the foo-pojo-impl on the bar-spi Maven disolves but
+ other ones result. The bar-spi project now depends on the FooEvent
+ class and this class is most likely located within the foo-spi or the
+ foo-pojo-impl Maven project jars. Also both the foo-pojo-impl and
+ other container wrapper implementations for Foo, now additionally
+ depend on the event-spi project. These dependencies on the
+ event-spi however are marked as harmless because the event service
+ and its implementations are terminal: they do not depend on any other
+ service or component. The event service by its nature was designed
+ this way since many components would depend on it. Here's what the
+ project dependencies look like now:
+ </p>
- <subsection name="">
+ <table>
+ <tr><th>Dependent</th><th>Dependency</th><th>Dangerous?</th></tr>
+ <tr>
+ <td>foo-pojo-impl</td>
+ <td>foo-spi</td>
+ <td>Harmless</td>
+ </tr>
+ <tr>
+ <td>foo-pojo-impl</td>
+ <td>event-spi</td>
+ <td>Harmless</td>
+ </tr>
+ <tr>
+ <td>bar-pojo-impl</td>
+ <td>bar-spi</td>
+ <td>Harmless</td>
+ </tr>
+ <tr>
+ <td>bar-pojo-impl</td>
+ <td>foo-spi</td>
+ <td>Harmful</td>
+ </tr>
+ <tr>
+ <td>bar-pojo-impl</td>
+ <td>event-spi</td>
+ <td>Harmless</td>
+ </tr>
+ </table>
+
+ <p>
+ Exchanging one harmful dependency for another is not what we wanted.
+ The bar-pojo-impl project's dependency on the foo-spi project for
+ resolving the FooEvent class is the only harmful dependency left.
+ This dependency between projects is due to the fact that the BarImpl
+ subscribes for FooEvents and the FooEvent class is defined in the
+ foo-spi project. Hence the project dependencey is driven by a class
+ dependency on FooEvent not by a dependency on the Foo service
+ interface.
+ </p>
+
<p>
+ To avoid this undesirable situation we maintain events within a
+ common API which does not depend on any other project in the
+ frontend. Any component may in the future need to subscribe for
+ FooEvents at some point. Rather than create new dependencies to the
+ foo-spi for every new FooEvent subscriber to see the FooEvent class,
+ we instead create a dependency to the common API project which has no
+ dependencies in the frontend. We have intentionally designed
+ subsystem common API packages this way. By having the bar-pojo-impl
+ depend on the common-api instead of foo-spi we avoid the chance of
+ a cyclic project dependency in the future. Now the dependencies
+ look like so and all are harmless in this respect:
</p>
<table>
+ <tr><th>Dependent</th><th>Dependency</th><th>Dangerous?</th></tr>
+ <tr>
+ <td>foo-pojo-impl</td>
+ <td>foo-spi</td>
+ <td>Harmless</td>
+ </tr>
<tr>
- <th>Topic</th>
- <th>Description</th>
+ <td>foo-pojo-impl</td>
+ <td>event-spi</td>
+ <td>Harmless</td>
+ </tr>
+ <tr>
+ <td>bar-pojo-impl</td>
+ <td>bar-spi</td>
+ <td>Harmless</td>
+ </tr>
+ <tr>
+ <td>bar-pojo-impl</td>
+ <td>common-api</td>
+ <td>Harmless</td>
+ </tr>
+ <tr>
+ <td>bar-pojo-impl</td>
+ <td>event-spi</td>
+ <td>Harmless</td>
</tr>
</table>
+
+ <p>
+ In the end dependencies are not bad things. They're necessary.
+ When managing dependencies we must prevent situations where cyclic
+ dependencies occur between compilation units, and Maven project's.
+ Making sure does not mean cleaning up by refectoring things around
+ after we detect a cycle. We prevent cycles from ever occuring by
+ only creating harmless dependencies where we can. Using common apis
+ within subsystems to consolidate shared interfaces and classes is one
+ tool. We always opt to create one or more safer dependencies rather
+ than allow for harmful ones that can later down the road impose
+ cyclic dependencies.
+ </p>
</subsection>
- -->
</section>
</body>
</document>
Modified: incubator/directory/eve/trunk/eve/xdocs/frontend/requirements.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/frontend/requirements.xml (original)
+++ incubator/directory/eve/trunk/eve/xdocs/frontend/requirements.xml Sat Feb 7 11:50:01 2004
@@ -7,28 +7,90 @@
<body>
<section name="Requirements">
- <p>Coming soon ...</p>
+ <p>
+ The following requiremest are what drive the design of Eve's frontend:
+ </p>
+
+ <ul>
+ <li>
+ Try to remain as protocol independent as possible so components can
+ easily be interchanged to offer both an LDAP configuration and an
+ X.500 (over IP) configuration.
+ </li>
- <subsection name="Requirements">
- <p>Requirements are must haves ...</p>
+ <li>
+ The frontend should facilitate experimentation with new features
+ and aspects of the protocol. This leads to several subordinate
+ requirements:
+ <ul>
+ <li>
+ a component based plugable architecture
+ </li>
+ <li>
+ micro-kernel (container) independence
+ </li>
+ <li>
+ clear separation of concerns
+ </li>
+ </ul>
+ </li>
+
+ <li>
+ Detachable frontend: the frontend should not need to be coupled
+ with the backend subsystem to operate. The two master subsystems
+ should be independent. This allows for the two parts to be easily
+ replaced and for frontends to be used as gateways to other servers
+ or virtual directories.
+ </li>
- <ul>
- <li>item I</li>
- <li>item II</li>
- <li>item III</li>
- </ul>
- </subsection>
-
- <subsection name="Nice-to-Haves">
- <p>These are rebust requirements that are nice to have ...</p>
+ <li>
+ The frontend should be binary compatible across operating systems
+ to avoid recompilation or conditional compilation. There should
+ be a zero porting effort. We want to write and build this once to
+ run everywhere.
+ </li>
- <ul>
- <li>item I</li>
- <li>item II</li>
- <li>item III</li>
- </ul>
- </subsection>
-
+ <li>
+ Design frontend request processors to interface with JNDI
+ providers. To facilitate a loose couple between the frontend
+ and backend master subsystems we need a published and common
+ API. The JNDI is a standard Java API with the 1.3 SDK and up.
+ Using the JNDI to process requests also keeps the learning curve
+ small for those altering the request processors. The processors
+ appear like simple JNDI clients and this JNDI code can be written
+ and tested outside of the server's frontend.
+ </li>
+
+ <li>
+ Eve's frontend must be able to support thousands of concurrent
+ connections without a linear degradation of performance. This
+ requirement leads to the need for non-blocking IO and the use of
+ NIO channels.
+ </li>
+
+ <li>
+ Responsiveness to requests with heavy load is also a requirement.
+ </li>
+ <li>Frontend end source should be easily modified.</li>
+ <li>Frontend end should be easily built.</li>
+ <li>Frontend should be easily configured.</li>
+ <li>Frontend should be easily deployed or installed.</li>
+ <li>Have a plethora of documentation.</li>
+ </ul>
</section>
+
+
+ <section name="Nice-to-Haves">
+ <p>
+ These are requirements that if imposed would lead to nice to have
+ features but they never made it to the critical list. Hence they're
+ not requirements but nice to have guide lines.
+ </p>
+
+ <ul>
+ <li>None yet!</li>
+ </ul>
+ </section>
+
</body>
</document>
Modified: incubator/directory/eve/trunk/eve/xdocs/frontend/status.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/frontend/status.xml (original)
+++ incubator/directory/eve/trunk/eve/xdocs/frontend/status.xml Sat Feb 7 11:50:01 2004
@@ -7,13 +7,87 @@
<body>
<section name="Frontend Status">
- <p>Coming soon ...</p>
-
+ <p>
+ Status should be on a per component basis and should be summarized for
+ the entire server here. At the present moment we have not evaluated
+ the overall status of the server.
+ </p>
+
+ <p>
+ Please also note that most of these components were at one point
+ complete in Eve's precursor written under the <a
+ href="http://sourceforge.net/projects/ldapd">LDAPd project</a>.
+ They are being rewritten with the frontend redesign while in the
+ incubator.
+ </p>
+ <table><tr><th>Status On: $LastChangedDate$</th></tr></table>
<table>
<tr>
<th>Component</th>
<th>State</th>
+ <th>Short Description</th>
</tr>
+
+ <tr>
+ <td>buffer</td>
+ <td>DONE</td>
+ <td>Direct memory buffer pool service</td>
+ </tr>
+
+ <tr>
+ <td>client</td>
+ <td>TBA</td>
+ <td>Client session manager service</td>
+ </tr>
+
+ <tr>
+ <td>common API</td>
+ <td>WORK IN PROGRESS</td>
+ <td>Not a component but a common API</td>
+ </tr>
+
+ <tr>
+ <td>decoder</td>
+ <td>TBD</td>
+ <td>BER message decoding service</td>
+ </tr>
+
+ <tr>
+ <td>encoder</td>
+ <td>TBD</td>
+ <td>BER message encoding service</td>
+ </tr>
+
+ <tr>
+ <td>event</td>
+ <td>DONE</td>
+ <td>Event notifier service</td>
+ </tr>
+
+ <tr>
+ <td>input</td>
+ <td>TBA</td>
+ <td>Input detection and reader service</td>
+ </tr>
+
+ <tr>
+ <td>listener</td>
+ <td>DONE</td>
+ <td>TCP port listener endpoint service</td>
+ </tr>
+
+ <tr>
+ <td>output</td>
+ <td>TBA</td>
+ <td>Output sender service</td>
+ </tr>
+
+ <tr>
+ <td>processor</td>
+ <td>TBA</td>
+ <td>Request processing handler service</td>
+ </tr>
+
</table>
</section>
Modified: incubator/directory/eve/trunk/eve/xdocs/frontend/x.500-ldap.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/frontend/x.500-ldap.xml (original)
+++ incubator/directory/eve/trunk/eve/xdocs/frontend/x.500-ldap.xml Sat Feb 7 11:50:01 2004
@@ -7,15 +7,27 @@
<body>
<section name="X.500 Vs. LDAP Overview">
- <p>Coming soon ...</p>
+ <p>
+ There really is not much to this for now. LDAP is the focus although
+ X.500 is not far behind. Expect to find here those things describing
+ the differences between the two and how the server accomodates both
+ protocols.
+ </p>
</section>
<section name="LDAP Support">
- <p>Coming soon ...</p>
+ <p>
+ The first release of the server will predominantly be for LDAP. There
+ may be X.500 hooks or features that are supported however the primary
+ focus initially is LDAP.
+ </p>
</section>
<section name="X.500 Support">
- <p>Coming soon ...</p>
+ <p>
+ As we add more X.500 directory modules and functionality we will grow
+ this section.
+ </p>
</section>
</body>
</document>
Added: incubator/directory/eve/trunk/eve/xdocs/images/dependencies-with-events.gif
==============================================================================
Binary file. No diff available.
Added: incubator/directory/eve/trunk/eve/xdocs/images/dependencies-without-events.gif
==============================================================================
Binary file. No diff available.