directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 6488 - in incubator/directory/eve/trunk/eve/xdocs: . backend frontend
Date Wed, 04 Feb 2004 07:53:54 GMT
Author: akarasulu
Date: Tue Feb  3 23:53:53 2004
New Revision: 6488

Modified:
   incubator/directory/eve/trunk/eve/xdocs/backend/navigation.xml
   incubator/directory/eve/trunk/eve/xdocs/components.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:
broke apart component stuff and added more

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	Tue Feb  3 23:53:53 2004
@@ -25,11 +25,11 @@
         <item name="Eve" href="/index.html">
           <item name="Features" href="/features.html"/>
           <item name="Source Layout" href="/source-layout.html"/>
-          <item name="Components" href="/components.html"/>
+          <item name="Component Design" href="/components.html"/>
           <item name="Building" href="/building.html"/>
           <item name="Deploying" href="/deploying.html"/>
-          <item name="Backend Subsystem" href="/backend/index.html"/>
-          <item name="Frontend Subsystem" href="/frontend/index.html"/>
+          <item name="Backend Design" href="/backend/index.html"/>
+          <item name="Frontend Design" href="/frontend/index.html"/>
         </item>
         <item name="LDAP" href="../ldap/index.html"/>
         <item name="Janus" href="../janus/index.html"/>

Modified: incubator/directory/eve/trunk/eve/xdocs/components.xml
==============================================================================
--- incubator/directory/eve/trunk/eve/xdocs/components.xml	(original)
+++ incubator/directory/eve/trunk/eve/xdocs/components.xml	Tue Feb  3 23:53:53 2004
@@ -6,37 +6,10 @@
   </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.
-          Some components are a collection of other components with a facade to 
-          form a subsystem of the server.  Subsystems can contain other 
-          subsystems and one component can depend on zero or more other
-          components.
-        </p>
-        
+    <section name="Resources">
         <p>
-          If the following paragraphs sounds a little confusing you might want 
-          to read a little about the IoC pattern and there is no better place 
+          If the following sections sound a little cryptic you might want 
+          to read a little about the IoC pattern. There is no better place 
           than Avalon for that.  Below are some Avalon documents you might find
           useful when translating some of this babble:
         </p>
@@ -48,44 +21,191 @@
           
           <li><a href="http://avalon.apache.org/framework/cop/index.html">
           Component Oriented Programing</a></li>
+          
+          <li><a href=
+          "http://nagoya.apache.org/wiki/apachewiki.cgi?AvalonNoLogging">Leo 
+          Sutic's use of Monitors instead of Loggers</a> is a technique we use.
+          </li>
         </ul>
+    </section>
+    
+    <section name="Components and Services">
+      <p>
+        The server is designed as a system of highly granular components.
+        Some components are a collection of other components with a facade to 
+        form a subsystem of the server.  Subsystems can contain other 
+        subsystems and one component can depend on zero or more other
+        components.
+      </p>
+      
+      <p>
+        A micro kernel or component container is required to run the server.
+        A micro kernel is a peice of code operating as a component container 
+        providing services for that component and running the component 
+        through a set of life-cycles.  Eve is designed to run on any micro 
+        kernel using component wrappers.  Her subsystems and components are 
+        designed as Plain Old Java Objects (POJOs) that can be wrapped to 
+        make them interoperate within different containers.  Eve is slated to 
+        work with both Merlin and PicoContainer, but there are no restrictions
+        to using containers like Loom, Plexus, or Phoenix.
+      </p>
+      
+      <p>
+        Each component within Eve has a public service interface which 
+        declares what that component can do for its clients.  The service
+        interface is kept and packaged separately from any component 
+        implementation.  The separation is achieved by using a different maven
+        project hence build jar for the SPI and the implementations of that
+        service.  An SPI project is often used to contain the service 
+        interface and other interfaces associated with the component.  
+        Providers of the service must implement the interfaces in the SPI.
+      </p>
+      
+      <p>
+        The drive behind this approach has to do with modularity and 
+        classloader schemes.  It is always good to keep the interfaces 
+        separate from any specific implementations.  You can have many 
+        implementations for the same service interface.  Secondly the 
+        classloader heirarchy in containers often puts implementation
+        classloaders under a classloader containing the service interface. 
+        This allows containers to manage multiple implementations for the
+        same service without having conflicts.  Also implementations can be
+        created and destroyed in separate classloaders without affecting one
+        another.
+      </p>
+    </section>
+    
+    <section name="Container Independence">
+      <p>
+        One of the biggest impediments we've had to deal with while developing
+        Eve and some precursors was having containers go in and out of fashion.
+        We lost several months of development time while switching from Pheonix
+        to Merlin.
+      </p>
+      
+      <p>
+        We believe we have a winner with Merlin but are not going to take 
+        anymore chances with container dependency.  The server is being 
+        designed from the ground up to be independent of any container.  We are
+        doing this by first making the default implementation of a service a 
+        Plain Old Java Object (POJO).  Wrapper implementation projects, one for 
+        each supported container, are used to wrap these POJO components to 
+        introduce container specific lifecycles and to encapsulate container 
+        idiosyncrasies.
+      </p>
+      
+      <p>
+        This approach we have found has several advantagous side-effects.  One 
+        benefit was a nice separation of concerns.  By separating out the 
+        container specific code, configuration and build aspects, developers
+        no longer need to be aware of container details.  They can focus on the
+        core implemenation as a simple class implementing an interface.  Those
+        interested in making Eve run in one container as opposed to another can
+        focus on their container wrapper without the clutter of another 
+        container getting in the way.  This reduces the complexity and learning
+        curve for all those involved in developing Eve's components and 
+        subsystems.
+      </p>
+    </section>
+    
+    <section name="Monitors Verse Loggers">
+      <p>
+        Above we provided a link to Leo Sutic's concept of a Monitor.  Briefly
+        without restating his wiki we'd like to review how we use Monitors 
+        instead of Loggers alone.
+      </p>
+      
+      <p>
+        Like any other server we need to log what goes on.  But rather than log
+        we need to monitor.  Logging is a specific type of monitoring for the 
+        sake of archiving what we monitor.  Leo proposed that every service 
+        should propose a very specific Monitor interface.  This is a good idea 
+        because it is the responsibility of the service to announce those 
+        interesting, and monitoring worthy events.  The interface forces 
+        signatures to explicitly describe what information is involved in the
+        monitoring of an event.
+      </p>
+      
+      <p>
+        This allows us to add Monitor interfaces and adapter to an SPI to 
+        define the those interesting events for a component without the concept
+        of Logging at all.  This makes the component implementation logging
+        system independent which is provided by a container implementation.
+        Each wrapper implementation can provide its own Monitor implementation
+        to interface with the Logging system of the target container.
+      </p>
+      
+      <p>
+        We gain by becoming more container independent but more importantly we
+        are forced to consider what events in a service, NOT its component 
+        implementations, constitutes a noteworthy event.  This throught 
+        provoking aspect is perhaps the most beneficial.
+      </p>
+      
+      <p>
+        So what does this mean in terms of Avalon logging.  Well you'll see
+        wrapper projects targeting Avalon containers with an 
+        Avalon[Component]Monitor which implements the [Component]Monitor 
+        interface.  This monitor implementation is LogEnabled and it handles 
+        writing to logs as it encounters monitoring events for the component.
+        This monitor would be constructed by the wrapper at or after the 
+        LogEnabled lifecycle and used by the POJO which the Merlin component
+        delegates service calls to.
+      </p>
+    </section>
+    
+    <section name="Configuration Beans">
+      <p>
+        Containers are neat because they give component developers a lot of 
+        nice features out of the box and that's what they should do.  The key
+        to maintaining container independency is to abstract away from these
+        features while still taking advantage of them.  This usually translates
+        into a few extra interfaces and classes.
+      </p>
+      
+      <p>
+        One benefit of containers is to provide a means to associate a 
+        configuration with a component.  Most allow for configurations to be 
+        stored in properties files and/or XML files.  Containers read and load
+        the configuration as a part of processing the lifecycles of components.
+      </p>
+      
+      <p>
+        Rather than have POJO component implementations depend directly on 
+        configuration interfaces specific to a container we explicitly define
+        configuration beans.  POJO implementations are then designed to take 
+        configuration beans as constructor arguments if the number of parameters
+        is large and putting so many parameters into a constructor would be
+        too cumbersome.  This configuration bean can also go into the SPI and
+        has the effect of clarifying the configuration data types required.
+      </p>
+    </section>
 
-        <p>
-          A micro kernel or component container is required to run the server.
-          A micro kernel is a peice of code operating as a component container 
-          providing services for that component and running the component 
-          through a set of life-cycles.  Eve is designed to run on any micro 
-          kernel using component wrappers.  Her subsystems and components are 
-          designed as Plain Old Java Objects (POJOs) that can be wrapped to 
-          make them interoperate within different containers.  Eve is slated to 
-          work with both Merlin and PicoContainer, but there are no restrictions
-          to using containers like Loom, Plexus, or Phoenix.
-        </p>
-        
-        <p>
-          Each component within Eve has a public service interface which 
-          declares what that component can do for its clients.  The service
-          interface is kept and packaged separately from any component 
-          implementation.  The separation is achieved by using a different maven
-          project hence build jar for the SPI and the implementations of that
-          service.  An SPI project is often used to contain the service 
-          interface and other interfaces associated with the component.  
-          Providers of the service must implement the interfaces in the SPI.
-        </p>
-        
-        <p>
-          The drive behind this approach has to do with modularity and 
-          classloader schemes.  It is always good to keep 
-          the interfaces separate from any specific implementations.  You can 
-          have many implementations for the same service interface.  Secondly
-          the classloader heirarchy in containers often puts implementation
-          classloaders under a classloader containing the service interface. 
-          This allows containers to manage multiple implementations for the
-          same service without having conflicts.  Also implementations can be
-          created and destroyed in separate classloaders without affecting one
-          another.
-        </p>
-      </subsection>
+    <section name="Dependencies">
+      <p>
+        Within a component based system like Eve, services are interfaces 
+        implemented by components.  Component are implementations.  They
+        obviously depend on their service interfaces.  Hence all component
+        implementation projects including the POJO and container specific 
+        wrappers depend on the project containing the service provider 
+        interfaces or SPI.  Furthermore, every component wrapper besides 
+        depending on the SPI project will depend on the POJO component project
+        which it wraps for use in a target container.  The dependencies between
+        the projects of a service and its components are easily understood and
+        always exist. 
+      </p>
+      
+      <p>
+        Dependencies between components and service are not that simple.  It is
+        very important that developers understand the nature of inter component
+        and service dependencies.  Service interfaces by themselves do not and 
+        should not depend on anything other than perhaps APIs.  Components 
+        should be designed to depend on services and not components implementing
+        the service.  By doing so a component allows the implementation of 
+        dependent services to change without affecting its operation.  The 
+        contract is in the service interface.  Althought this is common 
+        knowledge to most we felt it important enough to reiterate just in case.
+      </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	Tue Feb  3 23:53:53 2004
@@ -25,11 +25,11 @@
         <item name="Eve" href="/index.html">
           <item name="Features" href="/features.html"/>
           <item name="Source Layout" href="/source-layout.html"/>
-          <item name="Components" href="/components.html"/>
+          <item name="Component Design" href="/components.html"/>
           <item name="Building" href="/building.html"/>
           <item name="Deploying" href="/deploying.html"/>
-          <item name="Backend Subsystem" href="/backend/index.html"/>
-          <item name="Frontend Subsystem" href="/frontend/index.html"/>
+          <item name="Backend Design" href="/backend/index.html"/>
+          <item name="Frontend Design" href="/frontend/index.html"/>
         </item>
         <item name="LDAP" href="../ldap/index.html"/>
         <item name="Janus" href="../janus/index.html"/>

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	Tue Feb  3 23:53:53 2004
@@ -8,8 +8,11 @@
   <body>
     <section name="Overview">
       <p>Welcome to the Eve Directory Server Homepage!</p>
+
       <p>
-        Eve is a modular LDAP server written in pure Java.
+        Eve is a modular LDAP server written in pure Java. The Eve server is 
+        being completely designed from the ground up here within the incubator 
+        and will gain from the experience of building the old LDAPd server. 
       </p>
       
       <table>
@@ -29,10 +32,42 @@
         
         <tr>
           <td>
-            <a href="./design/index.html">Design</a>
+            <a href="./source-layout.html">Source Layout</a>
           </td>
           <td>
-            Documentation regarding Eve's design
+            Software configuration management is crittical with large systems.
+            This section documents the layout of the source code repository.
+          </td>
+        </tr>
+        
+        <tr>
+          <td>
+            <a href="./components.html">Component Design</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>
+        
+        <tr>
+          <td>
+            <a href="./building.html">Building</a>
+          </td>
+          <td>
+            Describes how to build Eve from the source.  Should be real simple
+            thanks to Maven.  But this should go off on how the build is 
+            structured as well for developers.
+          </td>
+        </tr>
+        
+        <tr>
+          <td>
+            <a href="./deploying.html">Deploying</a>
+          </td>
+          <td>
+            Configuring, and installing Eve with various kernels may require
+            an entire section to be dedicated to it when the time comes.
           </td>
         </tr>
         
@@ -41,7 +76,7 @@
             <a href="./frontend/index.html">Frontend Design</a>
           </td>
           <td>
-            Server's frontend design documentation
+            Server's frontend subsystem design documentation.
           </td>
         </tr>
         
@@ -50,7 +85,7 @@
             <a href="./backend/index.html">Backend Design</a>
           </td>
           <td>
-            Server's backend design documentation
+            Server's backend subsystem design documentation.
           </td>
         </tr>
         

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	Tue Feb  3 23:53:53 2004
@@ -25,11 +25,11 @@
         <item name="Eve" href="/index.html">
           <item name="Features" href="/features.html"/>
           <item name="Source Layout" href="/source-layout.html"/>
-          <item name="Components" href="/components.html"/>
+          <item name="Component Design" href="/components.html"/>
           <item name="Building" href="/building.html"/>
           <item name="Deploying" href="/deploying.html"/>
-          <item name="Backend Subsystem" href="/backend/index.html"/>
-          <item name="Frontend Subsystem" href="/frontend/index.html"/>
+          <item name="Backend Design" href="/backend/index.html"/>
+          <item name="Frontend Design" href="/frontend/index.html"/>
         </item>
         <item name="LDAP" href="../ldap/index.html"/>
         <item name="Janus" href="../janus/index.html"/>

Mime
View raw message