hivemind-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hls...@apache.org
Subject cvs commit: jakarta-hivemind/xdocs index.xml
Date Fri, 16 Apr 2004 13:16:55 GMT
hlship      2004/04/16 06:16:55

  Modified:    xdocs    index.xml
  Log:
  Clean up some of the concepts described on the introduction page.
  
  Revision  Changes    Path
  1.24      +86 -90    jakarta-hivemind/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-hivemind/xdocs/index.xml,v
  retrieving revision 1.23
  retrieving revision 1.24
  diff -u -r1.23 -r1.24
  --- index.xml	7 Apr 2004 23:40:12 -0000	1.23
  +++ index.xml	16 Apr 2004 13:16:55 -0000	1.24
  @@ -30,15 +30,28 @@
     	
     	<section name="Introduction">
     	
  -  	<p>
  -  	<b>HiveMind</b>	is a services and configuration microkernel. HiveMind allows
you to create
  -  	your application using a service oriented architecture. In HiveMind, you architect your
  -  	application in terms of <em>POJOs</em> (Plain Old Java Objects) and interfaces,
and let the HiveMind framework
  -  	do the busy work of instantiating your services and connecting them together.
  -  	</p>
  +  	<p><b>HiveMind</b>	is a services and configuration microkernel:
     	
  +  	<ul>
  +  		<li><b><a href="services.html">Services</a></b>: HiveMind
services are 
  +  				<em>POJOs</em> (Plain Old Java Objects) that can be easily accessed and
combined. 
  +  				Each service defines a Java interface it implements. HiveMind takes care of
  +  				instantiating and configuring each service just as necessary. HiveMind lets
  +  				services collaborate with each other
  +  				via <a href="ioc.html">dependency injection</a>.
  +  				</li>	
  +  		<li>
  +  		<b><a href="configurations.html">Configuration</a></b>: 
  +  		HiveMind allows you to provide complex configuration data to your services in an XML
  +  		format <em>you</em> define. HiveMind will integrate the contributions of
such data from
  +  		multiple modules and convert the XML into data objects for you. HiveMind configurations
allow for powerful, data-driven solutions which
  +  	combine seemlessly with the service architecture.
  +  		</li>
  +  	</ul>
  +  	</p>
  +  	 	
     	<p>
  -  	In HiveMind, a <a href="services.html">service</a> is an implementation
of a Java interface.  Unlike other
  +  	In HiveMind, a service is an implementation of a Java interface.  Unlike other
       SOAs (Service Oriented Architectures, such
     	as a SOAP, or EJBs), HiveMind is explicitly about combining Java code within a single
JVM. HiveMind
     	uses an XML <a href="descriptor.html">descriptor</a> to describe different
services, their lifecycles, and how they
  @@ -48,15 +61,23 @@
     	
     	
     	<p>
  -  	HiveMind provides powerful tools for <a href="configurations.html">configuring</a>

  -  	services in a decentralized manner; configuration data can be spread across many
  -  	HiveMind modules. HiveMind configurations allow for powerful, data-driven solutions
which
  -  	combine seemlessly with the service architecture.
  +  	HiveMind is organized around <em>modules</em>: individual building blocks,
each providing a particular
  +  	set of services and configurations. Each module is deployed as its own JAR file,
  +  	containing its own XML <a href="descriptor.html">descriptor</a>. At runtime,
  +  	HiveMind combines <em>all</em> the modules and their descriptors together
... 
  +  	seemlessly combining the services specific to
  +  	your application with the services provided by HiveMind and by other third-party libraries.

  +  	</p>
  +  	
  +  	<p>
  +  	HiveMind is designed with particular attention to J2EE. Because J2EE applications are
multi-threaded, everything
  +  	in HiveMind is thread-safe. That's one less thing for you to be concerned about.
     	</p>
     		
  +  		
     	<p>
  -  	HiveMind allows you to create more complex applications, yet keep the individual pieces
(individual services) simple
  -  	and testable. It offloads all the work of instantiating services, configuring them,
and connecting
  +  	HiveMind allows you to create more complex applications, yet keep the individual pieces
(the individual services) simple
  +  	and testable. HiveMind takes responsibility for instantiating services, configuring
them, and connecting
     	them together. It lets you concentrate on best practices: coding to interfaces, not
implementations,  and 
     	designing your code to be easily unit tested.	
     	</p>
  @@ -101,7 +122,7 @@
   </p>
   
   <p>
  -	Several individuals in WebCT's research and development team in addition to Mr. Howard
Lewis Ship 
  +	Several individuals in WebCT's research and development team, in addition to Howard Lewis
Ship, 
   	contributed to the requirements and concepts behind HiveMind's current set of functionality.
These
   	 include
   	 Martin Bayly, Diane Bennett, Bill Bilic, Michael Kerr, Prashant Nayak, Bill Richard and

  @@ -110,36 +131,6 @@
   	
     	</section>
     	
  -     
  -    <section name="Modules">
  -    <p>
  -    HiveMind doesn't have any particular purpose; it isn't an application, it's 
  -    an environment for supporting an application.  	
  -    </p>
  -    	
  -    	
  -    	<p>
  -    	HiveMind combines together a number of modules to form a registry of services
  -    	and configurations.  Each module consists of:
  -    	<ul>
  - 	<li>Configuration points</li>
  - 	<li>Contributions (to configuration points)</li>
  - 	<li>Service points</li>
  - 	<li>Implementation contributions (to service points)</li>
  - 	</ul>
  -    </p>
  -    
  -    <p>
  -    Any module may contribute to any other module, including itself.
  -    </p>
  -    
  -    <p>
  -    Each module has a 
  -    <a href="descriptor.html">HiveMind deployment descriptor</a>, <code>hivemodule.xml</code>.
 This
  -    defines the services and configurations defined by the module and its contributions
to other modules.
  -    </p>
  -    	
  -    </section>
       
       <section name="Registry">
       
  @@ -178,7 +169,7 @@
       </p>
       
       <source><![CDATA[
  -Registry registry = . . .;
  +Registry registry = RegistryBuilder.constructDefaultRegistry();
   MyService service = (MyService) registry.getService("com.mypackage.MyService", MyService.class);
   
   service.perform(...);
  @@ -201,6 +192,13 @@
       <li>Reporting any errors in a useful, verbose fashion</li>
       </ul>	
       </p>
  +    
  +<p>
  +However, a much more common case is for services to collaborate: that's much simpler, since
HiveMind
  +will connect the two services together for you. You'll just need to provide an instance
variable and either
  +a setter method or a constructor argument.	
  +</p>
  +    
       	
       </section>
       
  @@ -209,7 +207,7 @@
       <p>
       An important part of the HiveMind picture is documentation.  Comprehensive documentation
       about a HiveMind application, 
  -    <a href="hivedoc.html">HiveDoc</a>,  can be automatically generated by
the build process.  
  +    <a href="hivedoc.html">HiveDoc</a>,  can be automatically generated by
your build process.  
       This documentation
       lists all modules, all extension points (both service and configuration), all contributions
       (of service constructors, service interceptors and configuration elements) and cross
links
  @@ -222,8 +220,8 @@
       </p>
       
       <p>
  -    HiveMind is used to construct very complex systems using a large number of small parts.
 The
  -    registry documentation is an important tool for developers to understand and debug
  +    HiveMind is used to construct very complex systems using a large number of small parts.
 
  +    HiveDoc is an important tool for developers to understand and debug
       the application.
       </p>
       
  @@ -236,7 +234,7 @@
   and  at the same time,
   make your application more testable. If your applications are like my applications, there
is an awful lot of code
   in place that deals just with creating objects and hooking them together, and reading and
processing configuration
  -data. 
  +files. 
   </p>	
   
   <p>
  @@ -296,6 +294,17 @@
   <a href="jakarta-hivemind/LoggingInterceptor.html">logging interceptor</a>

   to your service. It will consistently log method entry and exit, and log any exceptions
thrown
   by the method.
  +
  +<p>
  +The following descriptor snippet defines a service, provides a core service implementation
  +(using &_create-instance;), and adds method logging (using &_interceptor;):
  +</p>
  +<pre><![CDATA[
  +<service-point id="MyService" interface="com.myco.MyServiceInterface">
  +  <create-instance class="com.myco.impl.MyServiceImpl"/>
  +  <interceptor service-id="hivemind.LoggingInterceptor"/>
  +</service-point>
  +]]></pre>
   </td>
   </tr>
   
  @@ -422,49 +431,36 @@
   </td>
   </tr>
   
  -</table>
  -
  -<subsection name="Testing your Services">
  +<tr>
  +<td>Test your services</td>	
  +<td>
  +In complex environments, such as EJB containers, you will often have to
  +deploy your code and then test it from the outside.  EJB code in particular
  +is hard to test because collaborating EJBs make use of JNDI
  +to access each other. It is very difficult to "stub out" part of
  +the overall application for testing purposes.	
  +</td>
  +<td>
   
  -<p>
  -HiveMind makes it easier to test your code as well.  You service implementations are always
simple JavaBeans that implement
  -a service interface you define. You will often have services work together; for example,
an OrderProcessing service may make
  -use of an EmailSender service.  In HiveMind that looks something like:	
  -</p>
  +Making code testable is a key concern of HiveMind, and shows up
  +in its general testing strategy:
  +<li>Because HiveMind services are simply POJOs, your unit tests can simply
  +instantiate them directly.</li>
  +
  +<li>HiveMind services are always identified by <em>interface</em>,
  +so it's easy to provide a mocked-up implementation of the interface.</li>
  +
  +<li>Services
  +collaborate via <a href="ioc.html">dependency injection</a>, so it's easy for
a 
  +unit test to wire a service to real or mock implementations of collaborating services.</li>
  +<li>Because
  +configuration data is just lists of Java objects, unit tests can easily create objects
  +suitable for testing.</li>
  +</td>
  +</tr>
   
  -<source>
  -public class OrderProcessingImpl implements OrderProcessing
  -{
  -  private EmailSender _sender;
  -  
  -  public void setEmailSender(EmailSender sender)
  -  {
  -    _sender = sender;
  -  }
  -  
  -  public void processOrder(Order order)
  -  {
  -      // ... whatever ...
  -      
  -    _sender.sendEmailForOrder(order);
  -  }
  -}
  -</source>
  -  	
  -<p>
  -HiveMind is responsible for instantiating your service implementation, <code>OrderProcessingImpl</code>,
  -and for setting the <code>emailSender</code> property. Notice how clean the
code paths are, you don't 
  -need to check to see if <code>_sender</code> is null and obtain an instance
from somewhere; the property
  -is simply set before your service method, <code>processOrder()</code>, is invoked.
  -</p>
  +</table>
   
  -<p>
  -When unit testing, you don't have to use HiveMind to create your services: your unit tests
can
  -instantiate <code>OrderProcessingImpl</code> directly,
  -and supply a mock implementation of <code>EmailSender</code> before
  -invoking <code>processOrder()</code>.
  -</p>
  -</subsection>
     	</section>   
      
       
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-cvs-help@jakarta.apache.org


Mime
View raw message