hlship 2004/08/17 05:33:23
Modified: src/documentation/content/xdocs index.xml configurations.xml
dependencies.xml
Log:
Fix typos and reformat parts of the documentation.
Revision Changes Path
1.16 +101 -116
jakarta-hivemind/src/documentation/content/xdocs/index.xml
Index: index.xml
===================================================================
RCS file:
/home/cvs/jakarta-hivemind/src/documentation/content/xdocs/index.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- index.xml 6 Aug 2004 14:16:41 -0000 1.15
+++ index.xml 17 Aug 2004 12:33:22 -0000 1.16
@@ -168,31 +168,23 @@
of small parts. HiveDoc is an important tool
for developers to
understand and debug the application.</p>
</section>
- <section>
- <title>Why should you use HiveMind?</title>
- <p>The concept behind HiveMind, and most other
microkernels, is to reduce
- the amount of code in your application 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 files.</p>
- <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, and how everything is
- hooked together within and between modules.</p>
- <p>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>
- <table>
- <tr>
- <th>Task</th>
- <th>Typical Approach</th>
- <th>HiveMind Approach</th>
- </tr>
- <tr>
- <td>Log method entry and exit</td>
- <td>
- <source>
- <![CDATA[
+
+ <section>
+ <title>Why should you use HiveMind?</title>
+ <p>The concept behind HiveMind, and most other dependency-injection
microkernels, is to reduce the amount of code
+ in your application 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 files.</p>
+ <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, and how everything is hooked
+ together within and between modules.</p>
+ <p>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>
+ <section>
+ <title>Task: Log method entry and exit</title>
+ <section>
+ <title>Typical Approach</title>
+ <source> <![CDATA[
public String myMethod(String param)
{
if (LOG.isDebugEnabled())
@@ -204,28 +196,29 @@
LOG.debug("myMethod() returns " + result);
return result;
-}]]>
- </source>
- <p>This approach doesn't do a
good or consistent job when a method
- has multiple return
points. It also creates 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 <link
href="site:hivemind.LoggingInterceptor">
- logging interceptor</link> 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> <source><![CDATA[
+}]]> </source>
+ <p>This approach doesn't do a good or consistent job when a method
has multiple return points. It also
+ creates 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>
+ </section>
+ <section>
+ <title>HiveMind Approach</title>
+ <p>Let HiveMind add a <link
href="site:hivemind.LoggingInterceptor"> logging interceptor</link> to your
+ service. It will consistently log method entry and exit, and log
any exceptions thrown by the method.</p>
+ <p>The following descriptor snippet defines a service, provides a
core service implementation (using
+ &_create-instance;), and adds method logging (using
&_interceptor;):</p>
+ <source><![CDATA[
<service-point id="MyService" interface="com.myco.MyServiceInterface">
<create-instance class="com.myco.impl.MyServiceImpl"/>
<interceptor service-id="hivemind.LoggingInterceptor"/>
-</service-point>]]> </source> </td>
- </tr>
- <tr>
- <td>Reference another service</td>
- <td>
- <source><![CDATA[
+</service-point>]]> </source>
+ </section>
+ </section>
+ <section>
+ <title>Task: Reference another service</title>
+ <section>
+ <title>Typical Approach</title>
+ <source><![CDATA[
private SomeOtherService _otherService;
public String myMethod(String param)
@@ -237,18 +230,17 @@
. . .
}]]> </source>
- <p>How the other service is
looked up is specified to the
- environment; it might
be a JNDI lookup for an EJB. For other
- microkernels, such as
Avalon, there will be calls to a specific
- API.</p>
- <p>In addition, this code is
not thread-safe; multiple threads could
- execute it
simultaneously, causing unwanted (and possibly
- destructive) multiple
lookups of the other service.</p>
- </td>
- <td>Let HiveMind assign the other
service as a property. This is <link
-
href="http://www.martinfowler.com/articles/injection.html";>
- dependency injection</link>.
HiveMind can inject dependencies using
- JavaBeans properties or
constructor arguments. <source><![CDATA[
+ <p>How the other service is looked up is specified to the
environment; it might be a JNDI lookup for an EJB.
+ For other microkernels, such as Avalon, there will be calls to a
specific API.</p>
+ <p>In addition, this code is not thread-safe; multiple threads
could execute it simultaneously, causing
+ unwanted (and possibly destructive) multiple lookups of the
other service.</p>
+ </section>
+ <section>
+ <title>HiveMind Approach</title>
+ <p>Let HiveMind assign the other service as a property. This is
<link
+ href="http://www.martinfowler.com/articles/injection.html";>
dependency injection</link>. HiveMind can
+ inject dependencies using JavaBeans properties or constructor
arguments.</p>
+ <source><![CDATA[
private SomeOtherService _otherService;
public void setOtherService(SomeOtherService otherService)
@@ -261,27 +253,27 @@
_otherService.doSomething(. . .);
. . .
-}]]> </source> <p>HiveMind uses a system of proxies to defer creation of
- services until actually 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>
- </tr>
- <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>
- <source><![CDATA[
+}]]> </source>
+ <p>HiveMind uses a system of proxies to defer creation of services
until actually 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>
+ </section>
+ </section>
+ <section>
+ <title>Task: Read configuration data</title>
+ <section>
+ <title>Typical Approach</title>
+ <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 content is often inefficient,
+ incompletely tested, and lacking the kind of error detection
built into HiveMind.</p>
+ </section>
+ <section>
+ <title>HiveMind Approach</title>
+ <source><![CDATA[
private List _configuration;
public void setConfiguration(List configuration)
@@ -299,44 +291,37 @@
item.doStuff(. . .);
}
}]]> </source>
- <p>HiveMind will set the
<code>configuration</code> property from a
- <link
href="site:configurations">configuration point</link> you
- specify. 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.</p>
- <p>The type and number of
extension points and how and when your
- code makes use of them
is entirely up to you, configured in the
- module deployment
descriptor.</p>
- </td>
- </tr>
- <tr>
- <td>Test your services</td>
- <td>
- <p>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.</p>
- </td>
- <td>
- <p>Making code testable is a
key concern of HiveMind, and shows up
- in its general testing
strategy:</p>
- <ul>
- <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 <link href="ioc.html">dependency
-
injection</link>, 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>
- </ul>
- </td>
- </tr>
- </table>
- </section>
+ <p>HiveMind will set the <code>configuration</code> property from
a <link
+ href="site:configurations">configuration point</link> you
specify. 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.</p>
+ <p>The type and number of extension points and how and when your
code makes use of them is entirely up to
+ you, configured in the module deployment descriptor.</p>
+ </section>
+ </section>
+ <section>
+ <title>Task: Test your services</title>
+ <section>
+ <title>Typical Approach</title>
+ <p>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.</p>
+ </section>
+ <section>
+ <title>HiveMind Approach</title>
+ <p>Making code testable is a key concern of HiveMind, and shows up
in its general testing strategy:</p>
+ <ul>
+ <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 <link href="ioc.html">dependency
injection</link>, 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>
+ </ul>
+ </section>
+ </section>
+ </section>
</body>
</document>
1.8 +1 -1
jakarta-hivemind/src/documentation/content/xdocs/configurations.xml
Index: configurations.xml
===================================================================
RCS file:
/home/cvs/jakarta-hivemind/src/documentation/content/xdocs/configurations.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- configurations.xml 6 Aug 2004 14:16:41 -0000 1.7
+++ configurations.xml 17 Aug 2004 12:33:22 -0000 1.8
@@ -250,7 +250,7 @@
inside HiveMind, which uses the
schema and rules to validate and
convert the XML contributions
into Java objects.</p>
<p>You can omit the schema, in which
case the elements are left as XML
- (instances of &api.Element; and
your code is responsible for walking
+ (instances of &api.Element;)
and your code is responsible for walking
the elements and attributes ...
but why bother? Far easier to let
HiveMind do the conversions and
validations.</p>
</li>
1.5 +5 -1
jakarta-hivemind/src/documentation/content/xdocs/dependencies.xml
Index: dependencies.xml
===================================================================
RCS file:
/home/cvs/jakarta-hivemind/src/documentation/content/xdocs/dependencies.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- dependencies.xml 6 Aug 2004 14:16:41 -0000 1.4
+++ dependencies.xml 17 Aug 2004 12:33:22 -0000 1.5
@@ -50,7 +50,7 @@
<td>
<link href="http://www.easymock.org/";>EasyMock testing
framework</link>
</td>
- <td>Only needed by &api.HiveMindTestCase;, which exists as the basis
of your own tests.</td>
+ <td>Only needed by &api.HiveMindTestCase;, which exists as the basis
for your own tests.</td>
</tr>
<tr>
<td>jboss-j2ee-3.2.1.jar</td>
@@ -84,6 +84,10 @@
service.</td>
</tr>
</table>
+
+ <p> Typically, all you need is the HiveMind libraries, Javassist, ORO and
commons-logging. Your EJB container will
+ provide the <code>javax.ejb</code> classes. Obviously, you should
include Spring if your are using Spring, and
+ EasyMock if you are writing tests using the
<code>HiveMindTestCase</code> base class. </p>
<p>
In most cases, HiveMind has been built against a "handy" version; in all
likelyhood you can vary
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
