hlship 2003/10/21 08:14:29
Modified: hivemind/xdocs index.xml ioc.xml filter.xml
Log:
More documentation improvements. Ready, Knut?
Revision Changes Path
1.18 +78 -91 jakarta-commons-sandbox/hivemind/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/index.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- index.xml 29 Sep 2003 16:16:35 -0000 1.17
+++ index.xml 21 Oct 2003 15:14:29 -0000 1.18
@@ -13,66 +13,38 @@
<body>
- <section name="Purpose">
+ <section name="Introduction">
<p>
- The purpose of HiveMind is to impose a little bit of order onto applications
of all types: anything
- from standalone applications all the way to enterprise applications deployed
as EARs
- inside an application server.
- </p>
-
- <p>
- HiveMind allows you to create a data-driven, service-oriented architecture. A
HiveMind
- application is broken up into small, individually testable services (which are
primarily
- stateless singleton objects). The HiveMind framework is responsible for
- creating each service just as it is needed. You get the benefits of a service
oriented architecture
- without the complexity of J2EE stateless session beans.
- HiveMind allows you to break apart your application into tiny,
- easily tested (and easily reused)
- services, and create the full application simply by combining and configuring
- the services.
- </p>
-
- <p>
- The service architecture is complemented by a configuration framework which
allow many
- independent modules to work together to define the configuration data used by
services.
- </p>
-
- <p>
- Using HiveMind means writing less code; code that you would ordinarily write
- for reading configuration files ... gone. Code for managing singleton service
objects ... gone.
- The use of <em>interceptors</em> means that much repetetive coding
also dissappears.
- For example, you can have a service automatically
- log method entry and exit using
- an <a href="commons-hivemind/LoggingInterceptor.html">interceptor</a> rather
than in your own code.
+ <b>HiveMind</b> is a services and configuration microkernel. HiveMind allows
you to create
+ your application using a service oriented architecture.
</p>
<p>
- In addition, a key HiveMind concept is <em>plugability</em>: a clean
- separation of interface and implementation is enforced. All code inside
HiveMind
- must code against interfaces, because the implementations are dynamically
- located or even dynamically assembled.
+ In HiveMind, a <a href="services.html">service</a> is an implementation of a
Java interface. Unlike other SOAs (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
+ are combined. HiveMind takes care of thread-safe, just-in-time creation of
singleton service objects
+ so your code doesn't have to.
</p>
<p>
- HiveMind is exhaustively tested and focused entirely on developer productivity.
- HiveMind uses <em>line precise error reporting</em>: this means that when
errors occur,
- even runtime errors long after module deployment descriptors have been parsed,
HiveMind will report the
- exact location of the source of an error (simply put, each runtime object is
"tagged" with
- the location - file and line - of the XML element it was created from). This
means that the
- vast majority of common errors not only report themselves consistently but
even tell you
- where to make the fix!
+ 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.
</p>
-
+
<p>
- In summary, HiveMind is a tightly written, highly dynamic
<strong>microkernel</strong> based
- on proven open-source technologies. It is a superior way to architect an
application,
- one that supports very aggresive refactoring and a very fine granulatity to
your solution.
+ 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
+ them together. It lets you concentrate on best practices: coding to
interfaces, not implementations and
+ designing your code to be easily unit tested.
</p>
-
-
+
</section>
+
<section name="Status">
@@ -90,6 +62,18 @@
A third sub-project, for contributed code and services, will be created soon.
</p>
+ <p>
+ A temporary <a href="http://jakarta.apache.org/~hlship/hivemind/";>download
location</a>
+ has been set up, but that code is almost always out of date with respect to
this documentation.
+ The transition from alpha-2 to alpha-3 is especially painful, because the
content of the
+ HiveMind module deployment descriptor changed.
+ </p>
+
+ <p>
+ As an early adopter, you should be ready to download and install
+ <a href="http://maven.apache.org";>Maven</a>, and get
+ the HiveMind source via anonymous CVS.
+ </p>
</section>
@@ -110,7 +94,7 @@
<p>
Configuration points are used for configuration information. Each
configuration point is a list of elements,
also accessible
- using a unique id. The elements of an configuration point
+ using a unique id. The elements of a configuration point
are provided by contributions
that appear in many modules, which is the basis for
allowing multiple modules to work together to form
@@ -157,14 +141,14 @@
<section name="Registry">
<p>
- The registry is the central element of HiveMind. A registry is always
+ The Registry is the central element of HiveMind. A Registry is always
a singleton instance.
</p>
<p>
- The registry is constructed when the application initializes. All HiveMind
- module descriptors are located and parsed, and the overall registry is
constructed
- from the contents. The registry is validated and any errors are logged.
+ The Registry is constructed when the application initializes. All HiveMind
+ module descriptors are located and parsed, and the Registry is constructed
+ from the combined contents. The Registry is validated and any errors are
logged.
</p>
<p>
@@ -178,8 +162,9 @@
<p>Coding using HiveMind is designed to be as succinct and painless as
possible.
Since services are, ultimately, simple objects (POJOs -- plain old java
objects) within
the same JVM, all the complexity of J2EE falls away ... no more JNDI lookups,
no more
- RemoteExceptions, no more home and remote interfaces. Of course, you can still
use HiveMind to front
- your EJBs, in which case the POJO is responsible for performing the JNDI lookup
and
+ RemoteExceptions, no more home and remote interfaces. Of course, you can still
use HiveMind to
+ <a href="commons-hivemind-lib/EJBProxyFactory.html">front
+ your EJBs</a>, in which case the POJO is responsible for performing the JNDI
lookup and
so forth (which in itself has a lot of value), before forwarding the request to
the EJB.
</p>
@@ -197,7 +182,7 @@
<p>
You code is responsible for:
<ul>
- <li>Obtaining a reference to the registry singleton</li>
+ <li>Obtaining a reference to the Registry singleton</li>
<li>Knowing the complete id of the service to access</li>
<li>Passing in the interface class</li>
</ul>
@@ -219,7 +204,9 @@
<p>
An important part of the HiveMind picture is documentation. Comprehensive
documentation
- about a HiveMind application is automatically generated by the build process.
This documentation
+ about a HiveMind application,
+ <a href="hivedoc.html">HiveDoc</a>, can be automatically generated by the
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
all extension points to their contributions.
@@ -236,11 +223,6 @@
the application.
</p>
- <p>The <a href="commons-hivemind/sample-registry/index.html">HiveMind module
descriptor documentation</a>
- gives a general idea of what the documentation looks like, using a hypothetical
- collection of module descriptors.
- </p>
-
</section>
<section name="Why should you use HiveMind?">
@@ -256,11 +238,11 @@
<p>
HiveMind moves virtually all of that logic into the framework, driven by the module
deployment descriptors.
Inside the descriptor, you describe your services, your configuration data
(extension points),
-and how everything is hooked together.
+and how everything is hooked together within and between modules.
</p>
<p>
-HiveMind can do all the busy work for you; using HiveMind makes it
+HiveMind can do all the grunt work for you; using HiveMind makes it
so that <em>the easiest approach is also the correct approach.</em>
</p>
@@ -297,11 +279,19 @@
return result;
}
</pre>
+
+<p>
+This approach doesn't do a good or consistent job when a method has multiple return
points.
+It also creates a many more branch points within the code ... basically, a lot of
clutter. Finally,
+it doesn't report on exceptions thrown from within the method.
+</p>
+
</td>
<td>
Let HiveMind add a
<a href="commons-hivemind/LoggingInterceptor.html">logging interceptor</a>
-to your service.
+to your service. It will consistently log method entry and exit, and log any
exceptions thrown
+by the method.
</td>
</tr>
@@ -338,7 +328,6 @@
<td>
Let HiveMind assign the other service as a property.
-
<pre>
private SomeOtherService _otherService;
@@ -357,7 +346,9 @@
<p>
HiveMind uses a system of proxies to defer creation of services until actually
-needed; HiveMind is also completely thread-safe.
+needed. The proxy object assigned to the otherService property will cause the actual
+service implementation to be instantiated and configured the first time
+a service method is invoked ... and all of this is done in a thread-safe manner.
</p>
</td>
@@ -366,10 +357,25 @@
<tr>
<td>Read configuration data.</td>
<td>
+ <p>
Find a properties file or XML file (on the classpath?
in the filesystem?) and read it, then write
code to intepret the raw data and possibly convert
it to Java objects.
+</p>
+
+<p>
+The lack of a standard approach means that data-driven solutions are often
+more trouble than they are worth, leading to code bloat and a loss of
+flexibility.
+</p>
+
+<p>
+Even when XML files are used for configuration, the code that reads
+the contents is often inefficient, incompletely tested, and lacking
+the kind of error detection built into HiveMind.
+</p>
+
</td>
<td>
<pre>
@@ -396,7 +402,7 @@
HiveMind will set the <code>configuration</code>
property from a
<a href="configurations.html">configuration point</a> you specify.
-The objects in the list are constructed from extension point
+The objects in the list are constructed from configuration point
contributions and converted, by HiveMind, into objects. As with
services, a thread-safe, just-in-time conversion takes place.
@@ -412,10 +418,11 @@
</table>
+<subsection name="Testing your Services">
<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, and OrderProcessing service may make
+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>
@@ -446,34 +453,14 @@
</p>
<p>
-When unit testing, you don't have to use HiveMind to create your objects: your unit
tests can
+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>
- <section name="What's In A Name?">
-
- <p>
- The vision of HiveMind is that of a bee hive or ant colony (or, if you are so
inclined, the
- Borg Collective). Each bee or ant is very limited and, if inspected closely,
- appears to behave reactively or erratically ... without any sense of purpose.
- </p>
-
- <p>
- Taken as a whole, though, bee hives, ant colonies
- and Borg Collectives are efficient and organized, complete with a definate
purpose. Likewise,
- the functionality of a HiveMind application is also an <em>emergent
property</em>.
- Thus the name of this project is not only catchy, its mneumonic and appropriate!
- </p>
-
- </section>
</body>
</document>
1.17 +32 -1 jakarta-commons-sandbox/hivemind/xdocs/ioc.xml
Index: ioc.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/ioc.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- ioc.xml 6 Oct 2003 18:22:30 -0000 1.16
+++ ioc.xml 21 Oct 2003 15:14:29 -0000 1.17
@@ -31,6 +31,32 @@
</p>
<p>
+There are three different implementation pattern types for IoC:
+<table>
+ <tr>
+ <td>type-1</td>
+ <td>Services are provided with an object from which they can look up
dependencies (other services). This
+ is the pattern used by Avalon.</td>
+ </tr>
+ <tr>
+ <td>type-2</td>
+ <td>
+ Dependent services are assigned via JavaBeans properties.
+ The <a href="http://www.springframework.org/";>Spring</a>
framework uses this approach.
+ </td>
+ </tr>
+ <tr>
+ <td>type-3</td>
+ <td>
+ Dependent services are provided using a constructor and are
not exposed as JavaBeans properties.
+ This is favored by
+ <a href="http://www.springframework.org/";>Picocontainer</a>.
+ </td>
+ </tr>
+</table>
+</p>
+
+<p>
HiveMind is a much looser system than Avalon. HiveMind doesn't have an explicit
assembly stage; it wires together
all the modules it can find at runtime. HiveMind is responsible for creating
services (including core implementations
and interceptors). It is quite possible to create service factories that do very
container-like things,
@@ -38,6 +64,11 @@
<a href="commons-hivemind/BuilderFactory.html">BuilderFactory</a>
does just that, instantiating an object to act as the core service implementation,
then setting
properties of the object, some of which are references to services and
configuration point element data.
+</p>
+
+<p>
+In HiveMind, you are free to mix and match type-2 and type-3, setting some (or all)
dependencies via a constructor and some (or all)
+via JavaBeans properties.
</p>
<p>
1.2 +2 -2 jakarta-commons-sandbox/hivemind/xdocs/filter.xml
Index: filter.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/filter.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- filter.xml 16 Oct 2003 22:30:29 -0000 1.1
+++ filter.xml 21 Oct 2003 15:14:29 -0000 1.2
@@ -11,7 +11,7 @@
</properties>
<body>
-<section name="Introduction">
+<section name="Using HiveMind with Servlets">
<p>
HiveMind includes a feature to streamline the use of HiveMind within a web
application: a
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
