You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by hl...@apache.org on 2003/06/04 05:05:49 UTC
cvs commit: jakarta-commons-sandbox/hivemind/xdocs descriptor.xml services.xml navigation.xml
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="hlship@apache.org">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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org