You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hivemind.apache.org by hl...@apache.org on 2004/05/26 21:34:16 UTC
cvs commit: jakarta-hivemind/src/documentation/content/xdocs index.xml bootstrap.xml configurations.xml case1.xml interceptors.xml services.xml
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 {@link
- 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 {@link 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: hivemind-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-cvs-help@jakarta.apache.org