hlship 2004/05/26 12:34:15
Modified: src/documentation/content/xdocs index.xml bootstrap.xml
configurations.xml case1.xml interceptors.xml
services.xml
Log:
Fix formatting errors in source code.
Revision Changes Path
1.3 +2 -2
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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 26 May 2004 16:58:43 -0000 1.2
+++ index.xml 26 May 2004 19:34:15 -0000 1.3
@@ -202,7 +202,7 @@
service-point (id=MyService interface=com.myco.MyServiceInterface)
{
create-instance (class=com.myco.impl.MyServiceImpl)
- <strong>interceptor (service-id=hivemind.LoggingInterceptor)</strong>
+ interceptor (service-id=hivemind.LoggingInterceptor)
}]]> </source> </td>
</tr>
<tr>
1.3 +9 -4
jakarta-hivemind/src/documentation/content/xdocs/bootstrap.xml
Index: bootstrap.xml
===================================================================
RCS file:
/home/cvs/jakarta-hivemind/src/documentation/content/xdocs/bootstrap.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- bootstrap.xml 26 May 2004 16:58:44 -0000 1.2
+++ bootstrap.xml 26 May 2004 19:34:15 -0000 1.3
@@ -64,9 +64,14 @@
hivemodule.sdl</code>. This file is in <link
href="site:sdl">Simple Data
Language</link> format (though equivalent XML
is supported if the file
is named <code>hivemodule.xml</code>).</p>
- <source>module (id=hivemind.examples version="1.0.0") {
service-point
- (id=Adder interface=hivemind.examples.Adder) {
create-instance
- (class=hivemind.examples.impl.AdderImpl) }
}</source>
+ <source><![CDATA[
+module (id=hivemind.examples version="1.0.0")
+{
+ service-point (id=Adder interface=hivemind.examples.Adder)
+ {
+ create-instance (class=hivemind.examples.impl.AdderImpl)
+ }
+}]]></source>
<p>Here we've chosen to have the module id,
<code>hivemind.examples</code>
, match the package name but that is not an
absolute requirement.</p>
</section>
1.2 +21 -8
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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- configurations.xml 26 May 2004 16:58:43 -0000 1.1
+++ configurations.xml 26 May 2004 19:34:15 -0000 1.2
@@ -117,14 +117,23 @@
<p>In addition, it is common for multiple
configuration points to share
the exact same schema. By assigning an
id attribute to a &_schema;
element, you may reference the same
schema for multiple configuration
- points. For example, the
hivemind.FactoryDefaults and
- hivemind.ApplicationDefaults
configuration points use the same schema.
+ points. For example, the
&hivemind.FactoryDefaults; and
+ &hivemind.ApplicationDefaults;
configuration points use the same schema.
The hivemind module deployment
descriptor accomplishes this by
defining a schema for one configuration
point, then referencing it
from another:</p>
- <source>configuration-point
(id=FactoryDefaults) { schema (id=defaults)
- { element (name=default) { . . . } } }
configuration-point
- (id=ApplicationDefaults) { schema
(ref-id=defaults) }</source>
+ <source><![CDATA[
+
+schema (id=Defaults)
+{
+ element (name=default)
+ {
+ . . .
+ }
+}
+
+configuration-point (id=FactoryDefaults schema-id=Defaults)
+]]></source>
<p>Like service points and configuration
points, schemas may be
referenced within a single module using
an unqualified id, or
referenced between modules using a
fully qualified id (that is,
@@ -197,8 +206,12 @@
Substitution symbols can appear inside literal
values ... both as XML
attributes, and as character data inside XML
elements.</p>
<p>Example:</p>
- <source>contribution
(configuration-id=com.myco.MyConfig) { value {
- "dir/foo.txt" } value {
"${config.dir}/${config.file}" } }</source>
+ <source><![CDATA[
+contribution (configuration-id=com.myco.MyConfig)
+{
+ value { "dir/foo.txt" }
+ value { "${config.dir}/${config.file}" }
+}]]></source>
<p>This example contributes two elements to the
<code>com.myco.MyConfig</code>
configuration point. The first contribution is
simply the text <code>
dir/foo.txt</code>. In the second contribution,
the content contains
1.3 +224 -202
jakarta-hivemind/src/documentation/content/xdocs/case1.xml
Index: case1.xml
===================================================================
RCS file:
/home/cvs/jakarta-hivemind/src/documentation/content/xdocs/case1.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- case1.xml 26 May 2004 16:58:43 -0000 1.2
+++ case1.xml 26 May 2004 19:34:15 -0000 1.3
@@ -16,65 +16,65 @@
limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
- "./dtd/document-v12.dtd" [
- <!ENTITY % common-links SYSTEM "links.ent">
- %common-links;
- ]>
+ "./dtd/document-v12.dtd" [
+ <!ENTITY % common-links SYSTEM "links.ent">
+ %common-links;
+ ]>
<document>
- <header>
- <title>Case Study #1: Application Startup / Shutdown</title>
- </header>
- <body>
- <note>This case study is based on work done for my prior
employer, who has
- not (yet) given approval to mention the project by
name. The package names
- and module ids have been changed, and some minor
changes and
- simplifications have been made. The actual name of the
product has been
- disguised as <em>Panorama</em>.</note>
- <p>The Panorama product is a fairly large J2EE web application
deployed into
- BEA WebLogic. Panorama consists of well over six
thousand classes, divided
- into a large number of tools and services. Panorama has
been a production
- project for several years, long before HiveMind was
available. HiveMind's
- introduction into Panorama (on something of a trial
basis) was to cleanup
- the startup and shutdown process for the
application.</p>
- <p>Panorama runs inside BEA WebLogic as an enterprise
application; however,
- it is still logically a number of subsystems, many of
which require some
- form of startup or shutdown logic. For example, the
Panorama Help service
- caches help data stored in the database; the Panorama
Mail tool sets up
- periodic database cleanup jobs. All told, there are
over 40 startup tasks,
- and a handful of shutdown tasks.</p>
- <p>Prior to HiveMind, a single EJB was the focus of all this
startup and
- shutdown activity. A small WebLogic startup class would
invoke the EJB,
- and the EJB implementation would invoke static methods
on many other
- classes (some of which would lookup other EJBs and
invoke methods on
- them). This approach had grown quite unwieldy,
especially in light of
- efforts to improve and modularize the Panorama build
process. HiveMind was
- brought in to rationalize this aspect of Panorama, with
the goal being to
- make the fewest possible changes to existing code.</p>
- <p>An important aspect of startup and shutdown is the order of
operations;
- there are dependencies between different tasks that
must be honored in
- terms of which task is executed first.</p>
- <section>
- <title>Overview</title>
- <p>The appropriate place to build the registry for an
EAR is from the web
- application; it has the widest view of
available classes; the web
- application classloader has visibility to the
web application and its
- libraries, all the EJBs deployed in the
application, and the system
- classloader.</p>
- <p>The overall approach is to provide HiveMind module
deployment
- descriptors for the various tools and services
of Panorama; each module
- contributes tasks to a Startup or Shutdown
configuration point.</p>
- <p>A WebLogic shutdown class is still used and the
original EJB still
- exists to allow an orderly shutdown.
Ultimately, this is required due to
- class loader issues; the EJB will have
visibility to the HiveMind
- library, but the startup class may not.</p>
- </section>
- <section>
- <title>Module panorama.framework.startup</title>
- <p>The <code>panorama.framework.startup</code>
("initialization and
- shutdown") module contains the services and
configuration points for
- startup and shutdown. It also contains Java
classes corresponding to
- task contributions.</p>
- <source><![CDATA[
+ <header>
+ <title>Case Study #1: Application Startup / Shutdown</title>
+ </header>
+ <body>
+ <note>This case study is based on work done for my prior employer, who
has
+ not (yet) given approval to mention the project by name. The package
names
+ and module ids have been changed, and some minor changes and
+ simplifications have been made. The actual name of the product has been
+ disguised as <em>Panorama</em>.</note>
+ <p>The Panorama product is a fairly large J2EE web application deployed
into
+ BEA WebLogic. Panorama consists of well over six thousand classes,
divided
+ into a large number of tools and services. Panorama has been a
production
+ project for several years, long before HiveMind was available.
HiveMind's
+ introduction into Panorama (on something of a trial basis) was to
cleanup
+ the startup and shutdown process for the application.</p>
+ <p>Panorama runs inside BEA WebLogic as an enterprise application;
however,
+ it is still logically a number of subsystems, many of which require
some
+ form of startup or shutdown logic. For example, the Panorama Help
service
+ caches help data stored in the database; the Panorama Mail tool sets up
+ periodic database cleanup jobs. All told, there are over 40 startup
tasks,
+ and a handful of shutdown tasks.</p>
+ <p>Prior to HiveMind, a single EJB was the focus of all this startup and
+ shutdown activity. A small WebLogic startup class would invoke the EJB,
+ and the EJB implementation would invoke static methods on many other
+ classes (some of which would lookup other EJBs and invoke methods on
+ them). This approach had grown quite unwieldy, especially in light of
+ efforts to improve and modularize the Panorama build process. HiveMind
was
+ brought in to rationalize this aspect of Panorama, with the goal being
to
+ make the fewest possible changes to existing code.</p>
+ <p>An important aspect of startup and shutdown is the order of
operations;
+ there are dependencies between different tasks that must be honored in
+ terms of which task is executed first.</p>
+ <section>
+ <title>Overview</title>
+ <p>The appropriate place to build the registry for an EAR is from the
web
+ application; it has the widest view of available classes; the web
+ application classloader has visibility to the web application and its
+ libraries, all the EJBs deployed in the application, and the system
+ classloader.</p>
+ <p>The overall approach is to provide HiveMind module deployment
+ descriptors for the various tools and services of Panorama; each
module
+ contributes tasks to a Startup or Shutdown configuration point.</p>
+ <p>A WebLogic shutdown class is still used and the original EJB still
+ exists to allow an orderly shutdown. Ultimately, this is required
due to
+ class loader issues; the EJB will have visibility to the HiveMind
+ library, but the startup class may not.</p>
+ </section>
+ <section>
+ <title>Module panorama.framework.startup</title>
+ <p>The <code>panorama.framework.startup</code> ("initialization and
+ shutdown") module contains the services and configuration points for
+ startup and shutdown. It also contains Java classes corresponding to
+ task contributions.</p>
+ <source><![CDATA[
module (id=panorama.framework.startup version="1.0.0")
{
description { "Module for startup and shutdown code within Panorama." }
@@ -198,36 +198,36 @@
}
}]]> </source>
- <p>Notes:</p>
- <ul>
- <li>Extension points, configurations, schemas
and services can be
- specified in any order.</li>
- <li>We use the simplest possible interface for
the Startup and Shutdown
- services:
<code>java.lang.Runnable</code>.</li>
- </ul>
- <section>
- <title>Startup configuration point</title>
- <p>The Startup configuration point and the
Startup service are closely
- bound together; the former contains
contributions from all sorts of
- modules. The service uses those
contributions and executes tasks based
- on them.</p>
- <p>The schema for the Startup configuration
point allows a <code><
- task></code> to be contributed. A
task always has an <code>order</code>
- attribute (used to sort all the
contributed elements into an execution
- order) and a <code>title</code>
attribute (used in output).</p>
- <p>The task to execute is specified in one of
three ways:</p>
- <ul>
- <li>As a Java class implementing the
<code>
-
com.panorama.framework.startup.service.Executable</code> interface
- (using the <code>class</code>
attribute)</li>
- <li>As a HiveMind service, implementing
the service (using the <code>
- service-id</code>
attribute)</li>
- <li>As a public static method of a
class (using the enclosed <code><
- invoke-static></code>
element)</li>
- </ul>
- <p>The <code>Executable</code> interface is
similar to the <code>
- java.lang.Runnable</code> interface:</p>
- <source><![CDATA[
+ <p>Notes:</p>
+ <ul>
+ <li>Extension points, configurations, schemas and services can be
+ specified in any order.</li>
+ <li>We use the simplest possible interface for the Startup and
Shutdown
+ services: <code>java.lang.Runnable</code>.</li>
+ </ul>
+ <section>
+ <title>Startup configuration point</title>
+ <p>The Startup configuration point and the Startup service are
closely
+ bound together; the former contains contributions from all sorts of
+ modules. The service uses those contributions and executes tasks
based
+ on them.</p>
+ <p>The schema for the Startup configuration point allows a <code><
+ task></code> to be contributed. A task always has an
<code>order</code>
+ attribute (used to sort all the contributed elements into an
execution
+ order) and a <code>title</code> attribute (used in output).</p>
+ <p>The task to execute is specified in one of three ways:</p>
+ <ul>
+ <li>As a Java class implementing the <code>
+ com.panorama.framework.startup.service.Executable</code>
interface
+ (using the <code>class</code> attribute)</li>
+ <li>As a HiveMind service, implementing the service (using the
<code>
+ service-id</code> attribute)</li>
+ <li>As a public static method of a class (using the enclosed
<code><
+ invoke-static></code> element)</li>
+ </ul>
+ <p>The <code>Executable</code> interface is similar to the <code>
+ java.lang.Runnable</code> interface:</p>
+ <source><![CDATA[
package com.panorama.framework.startup.service;
/**
@@ -236,50 +236,72 @@
*/
public interface Executable
{
- /**
- * Invoked to execute some kind of behavior and possible throw an
exception.
- * The caller is responsible for catching and reporting the exception.
- */
- public void execute() throws Exception;
+ /**
+ * Invoked to execute some kind of behavior and possible throw an
exception.
+ * The caller is responsible for catching and reporting the exception.
+ */
+ public void execute() throws Exception;
}]]> </source>
- <p>Adding <code>throws Exception</code> to the
method signature allows
- the caller to be responsible for
exception reporting, which simplifies
- the task implementations. Shortly,
we'll see how the application's
- master servlet invokes the Startup
service.</p>
- <p>The Shutdown configuration point and service
are effectively clones
- of the Startup configuration point and
schema.</p>
- </section>
- <section>
- <title>Task class</title>
- <p>The Task class is used to hold the
information collected by the
- Startup configuration point.</p>
- <source><![CDATA[ package
com.panorama.framework.startup.service; import
- org.apache.hivemind.Orderable; /** *
Configuration element for the
-
<code>panorama.framework.startup.Startup</code> or * <code>
-
panorama.framework.startup.Shutdown</code> * configuration points.
- Each element has a title, * an [EMAIL
PROTECTED]
-
com.panorama.framework.startup.service.Executable} * object, and an
- order * (used to sort the Tasks into an
order of execution). */ public
- class Task implements Orderable,
Executable { private int _order;
- private String _title; private
Executable _executable; public void
- execute() throws Exception {
_executable.execute(); } public int
- getOrder() { return _order; } public
String getTitle() { return
- _title; } public void setOrder(int i) {
_order = i; } public void
- setTitle(String string) { _title =
string; } public Executable
- getExecutable() { return _executable; }
public void
- setExecutable(Executable executable) {
_executable = executable; } }]]></source>
- <p>Task implements <code>Executable</code>,
simply delegating to its
- <code>executable</code> property. In
addition, it implements <link
-
href="&apiroot;/Orderable.html">Orderable</link>, which simply defines
- the <code>order</code> property (but
simplifies sorting of the
- elements).</p>
- </section>
- <section>
- <title>Startup service</title>
- <p>The Startup and Shutdown services are very
similar: similar enough
- that a single class, properly
configured, can be the service
- implementation for either service.</p>
- <source><![CDATA[
+ <p>Adding <code>throws Exception</code> to the method signature
allows
+ the caller to be responsible for exception reporting, which
simplifies
+ the task implementations. Shortly, we'll see how the application's
+ master servlet invokes the Startup service.</p>
+ <p>The Shutdown configuration point and service are effectively
clones
+ of the Startup configuration point and schema.</p>
+ </section>
+ <section>
+ <title>Task class</title>
+ <p>The Task class is used to hold the information collected by the
+ Startup configuration point.</p>
+ <source><![CDATA[
+package com.panorama.framework.startup.service;
+
+import org.apache.hivemind.Orderable;
+
+/**
+ * Configuration element for the
<code>panorama.framework.startup.Startup</code> or
+ * <code>panorama.framework.startup.Shutdown</code>
+ * configuration points. Each element has a title,
+ * an [EMAIL PROTECTED] com.panorama.framework.startup.service.Executable}
+ * object, and an order
+ * (used to sort the Tasks into an order of execution).
+ */
+
+public class Task implements Orderable, Executable
+{
+ private int _order;
+ private String _title;
+ private Executable _executable;
+
+ public void execute() throws Exception
+ {
+ _executable.execute();
+ }
+
+ public int getOrder() { return _order; }
+
+ public String getTitle() { return _title; }
+
+ public void setOrder(int i) { _order = i; }
+
+ public void setTitle(String string) { _title = string; }
+
+ public Executable getExecutable() { return _executable; }
+
+ public void setExecutable(Executable executable) { _executable =
executable; }
+}]]></source>
+ <p>Task implements <code>Executable</code>, simply delegating to its
+ <code>executable</code> property. In addition, it implements <link
+ href="&apiroot;/Orderable.html">Orderable</link>, which simply
defines
+ the <code>order</code> property (but simplifies sorting of the
+ elements).</p>
+ </section>
+ <section>
+ <title>Startup service</title>
+ <p>The Startup and Shutdown services are very similar: similar enough
+ that a single class, properly configured, can be the service
+ implementation for either service.</p>
+ <source><![CDATA[
package com.panorama.framework.startup.service;
import java.util.List;
@@ -391,23 +413,23 @@
}
}]]> </source>
- <p>HiveMind has a static convienience method,
<code>sortOrderables()</code>
- , used to sort a list of Orderable
objects into order, which is used
- here. Remember that the contributions
to the Startup (and Shutdown)
- configuration points are made from
multiple modules and there's no way
- to predict in what order those
contributions will show up in the
- <code>tasks</code> property, which is
why explicit sorting is
- necessary.</p>
- <p>At one time, there was a discussion about
using a thread pool to
- allow execution of some of the tasks in
parallel. That's a premature
- optimization: even with over forty
startup tasks, startup still only
- takes about forty seconds.</p>
- </section>
- <section>
- <title>StaticTask class</title>
- <p>The StaticTask class allows an arbitrary
public static method of a
- class to be treated like an
<code>Executable</code>.</p>
- <source><![CDATA[
+ <p>HiveMind has a static convienience method,
<code>sortOrderables()</code>
+ , used to sort a list of Orderable objects into order, which is
used
+ here. Remember that the contributions to the Startup (and Shutdown)
+ configuration points are made from multiple modules and there's no
way
+ to predict in what order those contributions will show up in the
+ <code>tasks</code> property, which is why explicit sorting is
+ necessary.</p>
+ <p>At one time, there was a discussion about using a thread pool to
+ allow execution of some of the tasks in parallel. That's a
premature
+ optimization: even with over forty startup tasks, startup still
only
+ takes about forty seconds.</p>
+ </section>
+ <section>
+ <title>StaticTask class</title>
+ <p>The StaticTask class allows an arbitrary public static method of a
+ class to be treated like an <code>Executable</code>.</p>
+ <source><![CDATA[
package com.panorama.framework.startup.service;
import java.lang.reflect.InvocationTargetException;
@@ -487,18 +509,18 @@
}
}]]> </source>
- <p>The class implements <link
href="&apiroot;/Locatable.html">Locatable</link>
- , which is used in method
<code>isNull()</code> when reporting errors;
- the location will be the location of
the <invoke-static> element
- the StaticTask instance was created
from.</p>
- </section>
- </section>
- <section>
- <title>Other Modules</title>
- <p>Other modules, in their HiveMind module deployment
descriptors, make
- contributions into the Startup and Shutdown
configuration points of the
- <code>panorama.framework.startup</code> module.
For example:</p>
- <source><![CDATA[
+ <p>The class implements <link
href="&apiroot;/Locatable.html">Locatable</link>
+ , which is used in method <code>isNull()</code> when reporting
errors;
+ the location will be the location of the <invoke-static>
element
+ the StaticTask instance was created from.</p>
+ </section>
+ </section>
+ <section>
+ <title>Other Modules</title>
+ <p>Other modules, in their HiveMind module deployment descriptors, make
+ contributions into the Startup and Shutdown configuration points of
the
+ <code>panorama.framework.startup</code> module. For example:</p>
+ <source><![CDATA[
module (id=panorama.coreservice.mail version="1.0.0")
{
contribution (configuration-id=panorama.framework.startup.Startup)
@@ -506,10 +528,10 @@
task (title=Mail order=2600
class=com.panorama.coreservice.mail.startup.MailStartup)
}
}]]> </source>
- <p>Here, the Mail service contributes an instance of
class <code>
- MailStartup</code>. Other modules take
advantage of the <
- invoke-static> element:</p>
- <source><![CDATA[
+ <p>Here, the Mail service contributes an instance of class <code>
+ MailStartup</code>. Other modules take advantage of the <
+ invoke-static> element:</p>
+ <source><![CDATA[
module (id=panorama.coreservice.garbagecollection version="1.0.0")
{
contribution (configuration-id=panorama.framework.startup.Startup)
@@ -520,13 +542,13 @@
}
}
}]]> </source>
- </section>
- <section>
- <title>Other Modules</title>
- <p>The master servlet for the web application is
responsible for
- constructing the registry and storing it so
that other code may access
- it.</p>
- <source><![CDATA[
+ </section>
+ <section>
+ <title>Application Startup</title>
+ <p>The master servlet for the web application is responsible for
+ constructing the registry and storing it so that other code may
access
+ it.</p>
+ <source><![CDATA[
public void init() throws ServletException
{
LOG.info("*** Bootstrapping HiveMind Registry ***");
@@ -564,14 +586,14 @@
}
}
]]></source>
- <p>After building the registry, the servlet uses the
Startup service to
- indirectly execute all the startup tasks.</p>
- </section>
- <section>
- <title>Handling Shutdown</title>
- <p>We take advantage of a WebLogic extension to know
when the application
- server is being shut down.</p>
- <source><![CDATA[
+ <p>After building the registry, the servlet uses the Startup service to
+ indirectly execute all the startup tasks.</p>
+ </section>
+ <section>
+ <title>Handling Shutdown</title>
+ <p>We take advantage of a WebLogic extension to know when the
application
+ server is being shut down.</p>
+ <source><![CDATA[
package com.panorama.framework.startup;
import javax.naming.InitialContext;
@@ -611,8 +633,8 @@
}
}]]> </source>
- <p>The implementation of the initshut EJB is similarily
straight-forward:</p>
- <source><![CDATA[
+ <p>The implementation of the initshut EJB is similarily
straight-forward:</p>
+ <source><![CDATA[
package com.panorama.framework.startup.ejb;
import java.rmi.RemoteException;
@@ -666,24 +688,24 @@
LOG.info("**** Panorama shutdown complete ****");
}
}]]> </source>
- </section>
- <section>
- <title>Summary</title>
- <p>This case study has shown how easy it is to leverage
HiveMind for a
- complex task. A monolithic EJB was broken down
into tiny, agile
- contributions to a configuration point. The
startup and shutdown logic
- is kept close to the contributing modules, in
those modules' HiveMind
- deployment descriptors. Contributions are in
expressive, easily readable
- XML.</p>
- <p>A single class is used to implement multiple,
similar services, just by
- configuring it as needed. Links between
different aspects of the system
- (such as the servlet initialization code and
the Startup service) are
- kept simple and agile.</p>
- <p>The small amount of code necessary to orchestrate
all this is fully
- tested in a unit test suite.</p>
- <p>The end result: an agile, easily extended system.
HiveMind has provided
- the tools and environment to support an
elegant, data-driven solution
- ... replacing the old, code-heavy EJB
implementation.</p>
- </section>
- </body>
+ </section>
+ <section>
+ <title>Summary</title>
+ <p>This case study has shown how easy it is to leverage HiveMind for a
+ complex task. A monolithic EJB was broken down into tiny, agile
+ contributions to a configuration point. The startup and shutdown
logic
+ is kept close to the contributing modules, in those modules' HiveMind
+ deployment descriptors. Contributions are in expressive, easily
readable
+ XML.</p>
+ <p>A single class is used to implement multiple, similar services,
just by
+ configuring it as needed. Links between different aspects of the
system
+ (such as the servlet initialization code and the Startup service) are
+ kept simple and agile.</p>
+ <p>The small amount of code necessary to orchestrate all this is fully
+ tested in a unit test suite.</p>
+ <p>The end result: an agile, easily extended system. HiveMind has
provided
+ the tools and environment to support an elegant, data-driven solution
+ ... replacing the old, code-heavy EJB implementation.</p>
+ </section>
+ </body>
</document>
1.2 +34 -18
jakarta-hivemind/src/documentation/content/xdocs/interceptors.xml
Index: interceptors.xml
===================================================================
RCS file:
/home/cvs/jakarta-hivemind/src/documentation/content/xdocs/interceptors.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- interceptors.xml 26 May 2004 16:58:43 -0000 1.1
+++ interceptors.xml 26 May 2004 19:34:15 -0000 1.2
@@ -144,12 +144,17 @@
deployment descriptor. The
AbstractServiceInterceptorFactory base
class expects two properties to be set
when the service is
constructed, <code>serviceId</code> and
<code>factory</code>:</p>
- <source>service-point (id=NullInterceptor
-
interface=org.apache.hivemind.ServiceInterceptorFactory) {
- invoke-factory
(service-id=hivemind.BuilderFactory) { construct
- (class=com.example.impl.NullInterceptor
service-id-property="
- serviceId) { set-service
(property=factory
- service-id=hivemind.ClassFactory) } }
}</source>
+ <source><![CDATA[
+service-point (id=NullInterceptor
interface=org.apache.hivemind.ServiceInterceptorFactory)
+{
+ invoke-factory (service-id=hivemind.BuilderFactory)
+ {
+ construct (class=com.example.impl.NullInterceptor
service-id-property=serviceId)
+ {
+ set-service (property=factory service-id=hivemind.ClassFactory)
+ }
+ }
+}]]></source>
</section>
</section>
<section>
@@ -194,11 +199,17 @@
<title>Creating the infrastructure</title>
<p>The method
<code>createInfrastructure()</code> is used to add fields
and constructors to the interceptor
class.</p>
- <source>protected void
createInfrastructure(InterceptorStack stack,
- ClassFab classFab) { Class topClass =
stack.peek().getClass();
- classFab.addField("_inner", topClass);
classFab.addConstructor( new
- Class[] { Log.class, topClass }, null,
"{ super($1); _inner = $2; }");
- }</source>
+ <source><![CDATA[
+protected void createInfrastructure(InterceptorStack stack, ClassFab
classFab)
+{
+ Class topClass = stack.peek().getClass();
+
+ classFab.addField("_inner", topClass);
+
+ classFab.addConstructor( new Class[] { Log.class, topClass },
+ null,
+ "{ super($1); _inner = $2; }");
+}]]></source>
<p>Since, when a interceptor is created, the
inner object has already
been created, we can use its <em>actual
type</em> for the <code>_inner</code>
field. This results in a much more
efficient method invocation than if
@@ -208,12 +219,17 @@
<title>Instantiating the Instance</title>
<p>The method
<code>instantiateInterceptor()</code> is used to create a
new instance from the fully fabricated
class.</p>
- <source>protected Object
instantiateInterceptor(InterceptorStack stack,
- Class interceptorClass) throws
Exception { Object stackTop =
- stack.peek(); Class topClass =
stackTop.getClass(); Log log =
-
LogFactory.getLog(stack.getServiceExtensionPointId()); Constructor c =
- interceptorClass.getConstructor(new
Class[] { Log.class, topClass });
- return c.newInstance(new Object[] {
log, stackTop }); }</source>
+ <source><![CDATA[
+protected Object instantiateInterceptor(InterceptorStack stack, Class
interceptorClass) throws Exception
+{
+ Object stackTop = stack.peek();
+ Class topClass = stackTop.getClass();
+ Log log = LogFactory.getLog(stack.getServiceExtensionPointId());
+
+ Constructor c = interceptorClass.getConstructor(new Class[] { Log.class,
topClass });
+
+ return c.newInstance(new Object[] { log, stackTop });
+}]]></source>
<p>This implementation gets the top object from
the stack (the inner
object for this interceptor) and the
correct <code>Log</code> instance
(based on the service extension point
id ... for the service being
1.2 +23 -10
jakarta-hivemind/src/documentation/content/xdocs/services.xml
Index: services.xml
===================================================================
RCS file:
/home/cvs/jakarta-hivemind/src/documentation/content/xdocs/services.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- services.xml 26 May 2004 16:58:44 -0000 1.1
+++ services.xml 26 May 2004 19:34:15 -0000 1.2
@@ -201,8 +201,11 @@
simple HiveMind deployment descriptor. This is
an SDL file, named
hivemodule.sdl, that must be included in the
module's META-INF
directory.</p>
- <source>module (id=com.myco.mypackage version="1.0.0")
{ service-point
- (id=Adder interface=com.myco.mypackage.Adder)
}</source>
+ <source><![CDATA[
+module (id=com.myco.mypackage version="1.0.0")
+{
+ service-point (id=Adder interface=com.myco.mypackage.Adder)
+}]]></source>
<p>The complete id for this service is
<code>com.myco.mypackage.Adder</code>
, formed from the module id and the service id.
Commonly, the service id
will exactly match the complete name of the
service interface, but this
@@ -226,9 +229,14 @@
]]></source>
<p>That's what we meant by a POJO. We'll create a
second module to provide
this implementation.</p>
- <source>module (id=com.myco.mypackage.impl
version="1.0.0") {
- implementation
(service-id=com.myco.mypackage.Adder) { create-instance
- (class=com.myco.mypackage.impl.AdderImpl) }
}</source>
+ <source><![CDATA[
+module (id=com.myco.mypackage.impl version="1.0.0")
+{
+ implementation (service-id=com.myco.mypackage.Adder)
+ {
+ create-instance (class=com.myco.mypackage.impl.AdderImpl)
+ }
+}]]></source>
<p>The runtime code to access the service is very
streamlined:</p>
<source><![CDATA[
Registry registry = . . .
@@ -236,9 +244,14 @@
int sum = service.add(4, 7);
]]></source>
<p>Another module may provide an interceptor:</p>
- <source>module (id=com.myco.anotherpackage
version="1.0.0") {
- implementation
(service-id=com.myco.mypackage.Adder) { interceptor
- (service-id=hivemind.LoggingInterceptor) }
}</source>
+ <source><![CDATA[
+module (id=com.myco.anotherpackage version="1.0.0")
+{
+ implementation (service-id=com.myco.mypackage.Adder)
+ {
+ interceptor (service-id=hivemind.LoggingInterceptor)
+ }
+}]]></source>
<p>Here the Logging interceptor is applied to the
service extension point.
The interceptor will be inserted between the
client code and the core
implementation. The client in the code example
won't get an instance of
@@ -357,7 +370,7 @@
<title>Services and Events</title>
<p>It is fairly common that some services will produce
events and other
services will consume events. The use of the
&hivemind.BuilderFactory;
- to construct a service simplifies this, using
the <code><
+ to construct a service simplifies this, using
the <code><
event-listener></code> element. The
BuilderFactory can register a
<em>core service implementation</em> (not the
service itself!) as a <em>
listener</em> of events produced by some other
service.</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
