directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 6559 - in incubator/directory/eve/trunk/eve/xdocs: frontend images
Date Sat, 07 Feb 2004 19:50:02 GMT
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.

Mime
View raw message