hlship 2003/06/03 20:05:49
Modified: hivemind/xdocs services.xml navigation.xml
Added: hivemind/xdocs descriptor.xml
Log:
Add docs on services and the module descriptor.
Revision Changes Path
1.2 +21 -12 jakarta-commons-sandbox/hivemind/xdocs/services.xml
Index: services.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/services.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- services.xml 30 May 2003 20:52:02 -0000 1.1
+++ services.xml 4 Jun 2003 03:05:49 -0000 1.2
@@ -1,5 +1,12 @@
<?xml version="1.0"?>
<!-- $Id$ -->
+<!DOCTYPE document [
+
+<!ENTITY % common-links SYSTEM "../common/links.xml">
+
+%common-links;
+
+]>
<document>
<properties>
@@ -34,7 +41,7 @@
</p>
<p>
- A module descriptor may include a <code><service></code> element
+ A module descriptor may include &service; element
to define a <em>service extension point</em>. A service extension point
establishes an id for the service, defines the interface for the service,
and indicates whether the service is optional or required (required is the
default).
@@ -82,12 +89,12 @@
</p>
<p>
- An instance creator is represented by a <code>>create-instance></code>
element.
+ An instance creator is represented by a &create-instance; element.
It includes a <code>class</code> attribute, the Java class to instantiate.
</p>
<p>
- An instance factory is represented by a <code>>factory></code>
element.
+ An instance factory is represented by a <code><factory></code>
element.
It includes a <code>service-id</code> attribute. This is the fully qualfied
id
of a factory service, a service which implements the
<code>org.apache.commons.hivemind.IFactory</code> interface.
@@ -96,10 +103,10 @@
<p>
In both cases, the properties of the core instance may be configured using
enclosed
- <code><set></code>
- <code><set-expression></code>
- <code><set-create></code> and
- <code><set-factory></code> elements.
+ <code>&set;</code>,
+ <code>&set-expression;</code>,
+ <code>&set-create;</code> and
+ <code>&set-factory;</code> elements.
</p>
</subsection>
@@ -107,7 +114,7 @@
<subsection name="Interceptor Contributions">
<p>
- An interceptor contribution is represented by a
<code><interceptor></code> element.
+ An interceptor contribution is represented by a &interceptor; element.
The <code>service-id</code> attribute identifies an interceptor factory
service: a service
that implements the
<code>org.apache.commons.hivemind.IInterceptorFactory</code> interface.
</p>
@@ -217,7 +224,7 @@
<p>
- Its not absolutely required, but it is good form to explicitly state
dependencies. Here,
+ Its not absolutely required, but it is good form, to explicitly state
dependencies. Here,
the module supplying the implementation is dependent on the module supplying
the interface.
</p>
@@ -258,7 +265,7 @@
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 the AdderImpl class, it will get
an instance of
- the interceptor, which internal invokes methods on the AdderImpl instance.
Because
+ the interceptor, which internally invokes methods on the AdderImpl instance.
Because
we code against interfaces instead of implementations, the client code
neither knows
nor cares about this.
</p>
@@ -293,7 +300,7 @@
<p>
For required services, HiveMind checks for a factory contribution when
the registry
is constructed. If a required service extension point has no
- contribution, and error is logged (identifying the extension point
id). In addition,
+ contribution, an error is logged (identifying the extension point id).
In addition,
<code>getService()</code>
will throw an ApplicationRuntimeException. So, if a service is
required, you don't
have to check for null.
@@ -303,6 +310,8 @@
</section>
+
+
</body>
</document>
1.2 +2 -1 jakarta-commons-sandbox/hivemind/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 30 May 2003 20:52:02 -0000 1.1
+++ navigation.xml 4 Jun 2003 03:05:49 -0000 1.2
@@ -1,12 +1,13 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="HiveMind">
- <title>Commons - HiveMind</title>
+ <title>HiveMind</title>
<body>
<menu name="Overview">
<item name="Introduction" href="/intro.html"/>
</menu>
<menu name="Reference">
<item name="Services" href="/services.html"/>
+ <item name="Module Descriptor" href="/descriptor.html"/>
</menu>
</body>
</project>
1.1 jakarta-commons-sandbox/hivemind/xdocs/descriptor.xml
Index: descriptor.xml
===================================================================
<?xml version="1.0"?>
<!-- $Id: descriptor.xml,v 1.1 2003/06/04 03:05:49 hlship Exp $ -->
<!DOCTYPE document [
<!ENTITY % common-links SYSTEM "../common/links.xml">
%common-links;
]>
<document>
<properties>
<title>HiveMind Module Descriptor</title>
<author email="[EMAIL PROTECTED]">Howard M. Lewis Ship</author>
</properties>
<body>
<section name="Purpose">
<p>
The purpose of the module descriptor is to provide
a runtime and compile-time descriptor of a module:
its dependencies, services, configurations and contributions.
</p>
<p>
The descriptor is named <code>hivemodule.xml</code>
and is stored in the META-INF directory of the module.
</p>
<p>
The descriptor is defined using XML schema.
</p>
<p>
Although not absolutely required, it is best if the schema is attached
to the document, as shown below:
</p>
<source><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<module
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:noNamespaceSchemaLocation="http://jakarta.apache.org/commons/hivemind/schema/HiveMind_1.0.xsd";
id=". . ."
version="1.0.0">
. . .
</module>
]]></source>
</section>
<section name="module">
<p>
The &_module; element is the root element.
</p>
<table>
<tr>
<th>Attribute</th> <th>Type</th> <th>Required ?</th>
<th>Description</th>
</tr>
<tr>
<td>id</td>
<td>string</td>
<td>yes</td>
<td>The id should be a dotted sequence, like a package name. In
general,
the module id should <em>be</em> the package name.</td>
</tr>
<tr>
<td>version</td>
<td>version number</td>
<td>yes</td>
<td>The version of the module as a dotted sequence of three numbers.
Example: "1.0.0"</td>
</tr>
<tr>
<td>class</td>
<td>class name</td>
<td>no</td>
<td>The name of a Java class to instantiate as the module. The class
must
implement the
<code>org.apache.commons.hivemind.IModule</code> interface; in
addition,
the framework currently requires that the class derive from
<code>org.apache.commons.hivemind.impl.BaseModule</code>.
Specifying a class
is optional; it is useful to put code common to a HiveMind
module
into the module class.
</td>
</tr>
<tr><th colspan="2">Element</th> <th>Count</th>
<th>Description</th></tr>
<tr>
<td colspan="2"><a href="#description">description</a></td>
<td>0..1</td>
<td>Optional description of the module.</td>
</tr>
<tr>
<td colspan="2"><a href="#meta">meta</a></td>
<td>0..n</td>
<td>Meta-data about the module.</td>
</tr>
<tr>
<td colspan="2"><a href="#dependency">dependency</a></td>
<td>0..n</td>
<td>Dependencies on other modules.</td>
</tr>
<tr>
<td colspan="2"><a href="#library">library</a></td>
<td>0..n</td>
<td>Dependencies on other libraries.</td>
</tr>
<tr>
<td colspan="2"><a href="#service">service</a></td>
<td>0..n</td>
<td>Defines a service extension point.</td>
</tr>
<tr>
<td colspan="2"> <a href="#configuration">configuration</a>
</td>
<td>0..n</td>
<td>Defines a configuration extension point.</td>
</tr>
<tr>
<td colspan="2"><a
href="#contribute-service">contribute-service</a></td>
<td>0..n</td>
<td>Contributes to a service extension point.</td>
</tr>
<tr>
<td colspan="2"><a
href="#contribute-configuration">contribute-configuration</a></td>
<td>0..n</td>
<td>Contributes to a configuration extension point.</td>
</tr>
</table>
</section>
<section name="description">
<p>
The &_description; element provides a user-readable description as the content
of the element.
</p>
</section>
<section name="meta">
<p>
The &_meta; element is used to supply meta-data about the module. HiveMind
does not use
this information, but it is available to the application (and to the build
process).
</p>
<table>
<tr>
<th>Attribute</th> <th>Type</th> <th>Required ?</th>
<th>Description</th>
</tr>
<tr>
<td>key</td> <td>string</td> <td>yes</td>
<td>The key used to identify the meta-data value.</td>
</tr>
<tr>
<td>value</td> <td>string</td> <td>yes</td>
<td>The meta-data value.</td>
</tr>
</table>
</section>
<section name="dependency">
<p>
The &_dependency; element identifies a dependency on another module. A
dependency may
be on a specific version of a module.
</p>
<table>
<tr>
<th>Attribute</th> <th>Type</th> <th>Required ?</th>
<th>Description</th>
</tr>
<tr>
<td>module-id</td> <td>string</td> <td>yes</td>
<td>The id of the module which this module is dependent upon.</td>
</tr>
<tr>
<td>version</td> <td>version number</td> <td>no</td>
<td>
The version number of the module which is required. The default is
'*', which matches any
version. The version number may also be a specific version number
(i.e., "1.0.0") or
may end in a '+' to indicate any later version (i.e., "1.0.5+").
</td>
</tr>
</table>
</section>
<section name="library">
<p>The &_library; element identifies an external library and version required by
this module.
</p>
<table>
<tr>
<th>Attribute</th> <th>Type</th> <th>Required ?</th>
<th>Description</th>
</tr>
<tr>
<td>id</td> <td>string</td> <td>yes</td>
<td>The base name of the library jar.</td>
</tr>
<tr>
<td>version</td> <td>string</td> <td>yes</td>
<td>
The version portion of the library jar. The jar is named:
<code><i>id</i>-<i>version</i>.jar</code>
</td>
</tr>
<tr>
<td>export</td> <td>boolean</td> <td>no</td>
<td>
If true, then the library is exported with the module; the library
will be added
to the classpath of any other module which depends on this module.
The default
is false, appropriate when the classes in the library are only needed
by
the module itself.
</td>
</tr>
</table>
</section>
<section name="service">
<p>The &_service; element defines a service extension point.</p>
<table>
<tr>
<th>Attribute</th> <th>Type</th> <th>Required ?</th>
<th>Description</th>
</tr>
<tr>
<td>id</td> <td>string</td> <td>yes</td>
<td>The simple id of the service extension point. The fully qualified
id for the
extension point is created by prefixing with the module's id
(and a dot).</td>
</tr>
<tr>
<td>interface</td> <td>class name</td> <td>yes</td>
<td>The fully qualified name of the Java interface supplied by this
service extension point.</td>
</tr>
<tr>
<td>required</td> <td>boolean</td> <td>no</td>
<td>If true (the default), then a factory contribution must be made to
the extension point.
If false, then the service provided by the extension point is
optional.</td>
</tr>
<tr><th colspan="2">Element</th> <th>Count</th>
<th>Description</th></tr>
<tr>
<td colspan="2"><a href="#description">description</a></td>
<td>0..1</td>
<td>Description of this service extension point.</td>
</tr>
<tr>
<td colspan="2"><a href="#create-instance">create-instance</a></td>
<td>0..1</td>
<td>Provides a core implementation instance for the service.</td>
</tr>
<tr>
<td colspan="2"><a href="#factory">factory</a></td>
<td>0..1</td>
<td>Obtains a core implementation instance from a factory service.</td>
</tr>
<tr>
<td colspan="2"><a href="#interceptor">interceptor</a></td>
<td>0..n</td>
<td>Adds an interceptor to the service.</td>
</tr>
</table>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
