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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
