hlship 2003/06/11 11:43:12
Modified: hivemind/xdocs descriptor.xml intro.xml navigation.xml
hivemind/common links.xml
Added: hivemind/xdocs configuration.xml
Log:
Add documentation about configuration.
Revision Changes Path
1.4 +3 -3 jakarta-commons-sandbox/hivemind/xdocs/descriptor.xml
Index: descriptor.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/descriptor.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- descriptor.xml 9 Jun 2003 22:23:07 -0000 1.3
+++ descriptor.xml 11 Jun 2003 18:43:12 -0000 1.4
@@ -549,9 +549,9 @@
</tr>
<tr>
<td colspan="2">
- <a href="#xml">xml</a>
+ <a href="#set-xml">set-xml</a>
</td>
- <td>0..n.</td>
+ <td>0..n</td>
<td>Sets a property of the object to the root
element of a parsed XML
file. The property must be type <a
href="apidocs/org/apache/commons/hivemind/IElement.html">IElement</a>.</td>
</tr>
1.2 +8 -3 jakarta-commons-sandbox/hivemind/xdocs/intro.xml
Index: intro.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/intro.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- intro.xml 30 May 2003 20:52:02 -0000 1.1
+++ intro.xml 11 Jun 2003 18:43:12 -0000 1.2
@@ -1,5 +1,9 @@
<?xml version="1.0"?>
<!-- $Id$ -->
+<!DOCTYPE document [
+ <!ENTITY % common-links SYSTEM "../common/links.xml">
+ %common-links;
+ ]>
<document>
<properties>
@@ -94,7 +98,8 @@
</p>
<p>
- Each module has a HiveMind deployment descriptor, <code>hivemind.xml</code>.
This
+ Each module has a
+ <a href="descriptor.html">HiveMind deployment descriptor</a>,
<code>hivemodule.xml</code>. This
defines the services and configurations defined by the module, its
contributions,
and its dependencies on other modules.
</p>
@@ -169,7 +174,7 @@
</p>
<p>
- Modules and extension points include a <code><documentation></code>
element which is
+ Modules and extension points include a &description; element which is
incorporated into the documentation set.
</p>
1.4 +1 -0 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- navigation.xml 10 Jun 2003 17:58:20 -0000 1.3
+++ navigation.xml 11 Jun 2003 18:43:12 -0000 1.4
@@ -7,6 +7,7 @@
</menu>
<menu name="Reference">
<item name="Services" href="/services.html"/>
+ <item name="Configurations" href="/configuration.html"/>
<item name="Module Descriptor" href="/descriptor.html"/>
<item name="Ant Tasks" href="/ant/index.html" collapse="true">
<item name="ManifestClassPath"
href="/ant/ManifestClassPath.html"/>
1.1 jakarta-commons-sandbox/hivemind/xdocs/configuration.xml
Index: configuration.xml
===================================================================
<?xml version="1.0"?>
<!-- $Id: configuration.xml,v 1.1 2003/06/11 18:43:12 hlship Exp $ -->
<!DOCTYPE document [
<!ENTITY % common-links SYSTEM "../common/links.xml">
%common-links;
]>
<document>
<properties>
<title>HiveMind Configurations</title>
<author email="[EMAIL PROTECTED]">Howard M. Lewis Ship</author>
</properties>
<body>
<section name="Introduction">
<p>
A central concept in HiveMind is <em>configurations</em>. Once you have a set of
services, its natural to want to configure those services. In HiveMind, a
configuration
is a list of <em>elements</em>. Each element is contributed by a module ... any
module may make
contributes to any service extension point.
</p>
</section>
<section name="Defining a Service Extension Point">
<p>
A module may include &configuration; elements to define new configuration extension
points.
</p>
<p>
Contributions to an extension point are not simply strings; when defining
an extension point, the type of element is also specified. All contributions to the
extension point must
be assignable to the specified type (which is the name of a Java class or interface).
</p>
<p>
If a contribution is invalid (not assignable), then a runtime error is logged and
the contribution is ignored.
The runtime error will identify the exact location (the file, line number and column
number)
of the contribution so you can go fix it.
</p>
<p>
The descriptor elements for contributing to a configuration extension point supports
many different element types:
<ul>
<li>simple literals (&value;)</li>
<li>Computed values (&expression;)</li>
<li>Constructed objects (&create-instance; and &factory;)</li>
<li>Parsed contents of XML files (&xml;)</li>
<li>References to HiveMind services (&service-ref;)</li>
</ul>
</p>
<p>
A configuration extension point may also specify the expected, or allowed, number of
contributions:
<ul>
<li>Zero or one</li>
<li>Zero or more</li>
<li>At least one</li>
<li>Exactly one</li>
</ul>
</p>
<p>
At runtime, the number of actual contributions is checked against the constraint and
an error occurs
if the number doesn't match.
</p>
</section>
<section name="Accessing Configurations">
<p>Like services, configurations are meant to be easy to access.</p>
<source><![CDATA[
IRegistry registry = HiveMind.getDefault();
List elements = registry.getConfiguration("com.myco.MyConfig");
int count = elements.size();
for (int i = 0; i < count; i++)
{
MyElement element = (MyElement) elements.get(i);
. . .
}
]]></source>
<p>
The list of elements is always returned as an unmodifiable list. An empty list may
be returned.
</p>
<p>
The order of the elements in the list is not defined. If order is important, you
should create
a new (modifiable) list from the returned list and sort it.
</p>
</section>
<section name="Lazy Loading">
<p>
At application startup, all the module deployment descriptors are located and parsed
and in-memory
objects created. Validations (such as having the correct number of contributions)
occur at this stage.
</p>
<p>
The element list for a configuration extension point is not created until the
first call to <code>IRegistry.getConfiguration()</code> for that configuration
extension point.
</p>
<p>
In most cases, the element list is retained for future invocations of
<code>getConfiguration()</code>.
This is controlled by the <code>cache-elements</code> attribute of the
&configuration; element. Set
<code>cache-elements</code> to <code>false</code> for configuration extension points
that will be read just once.
</p>
<p>
There may be side effects of accessing the element list for a configuration
extension point: new services
may be instantiated (&service-ref;), objects may be created (&create-instance; or
&factory;) ... even
XML documents may be read and parsed (&xml;). Again, these events occur only when a
configuration extension point
is first accessed (or on each access if the extension point doesn't cache its
elements).
</p>
</section>
<section name="Substitution Variables">
<p>
The information provided by HiveMind module descriptors is entirely static, but in
some cases, some aspects of
the configuration should be dynamic. For example, a database URL or an e-mail
address may not be known until runtime
(a sophisticated application may have an installer which collects this information).
</p>
<p>
HiveMind supports this notion through <em>substitution variables</em>. These are
references to values
that are supplied at runtime. Substitution variables can appear inside literal
values and OGNL expressions (in
a module descriptor). In addition, when the &xml; element reads an external XML
file, substitution variables
in attribute and inside element content are expanded.
</p>
<p>
Example:
</p>
<source><![CDATA[
<contribute-configuration configuration-id="com.myco.MyConfig">
<value>dir/foo.txt</value>
<value>${config.dir}/${config.file}</value>
</contribute-configuration>
]]></source>
<p>
This example contributes two strings to the <code>com.myco.MyConfig</code>
configuration
extension point. The first is literal text. The second is constructed from two
variables (not the use
of Ant-like syntax).
</p>
<subsection name="Variable Sources">
<p>
This begs the question: where do variable values come from? The answser is: its
application dependent.
HiveMind itself defines a configuration extension point for this purpose:
<code>org.apache.commons.hivemind.VariableSource</code>. Contributions
to this extension point are of type
<a
href="apidocs/org/apache/commons/hivemind/VariableSourceContribution.html">VariableSourceContribution</a>.
The contribution consists of an order number (used to sort the contributions into
an order to query) and a
variable source (of type
<a
href="apidocs/org/apache/commons/hivemind/IVariableSource.html">IVariableSource</a>).
</p>
<p>
So, you need to create an implementation of this interface. You can either
contribute it as a POJO (using &create-instance;)
or define a complete service and contribute it using &service-ref;.
</p>
</subsection>
</section>
<section name="Frequently Asked Questions">
<ul>
<li><strong>Are the any default implementations of IVariableSource?</strong>
<p>
Not yet, but I'm sure there will be.
</p>
</li>
<li><strong>Why contribute objects? Why not just strings, or just
XML?</strong>
<p>
The whole point of HiveMind is to reduce code clutter. When configuration
data is just strings
(in a .properties file) or just XML, that puts a lot of burden on the
developer who
<em>reads</em> the configuration to then massage it into useful objects. That
kind of ad-hoc
code is notoriously buggy; in HiveMind it is almost entirely absent. Instead,
all the XML parsing
occurs inside HiveMind, which typically creates and configures objects based
on the XML (with exceptional
error reporting).
</p>
<p>
You can still limit yourself to strings, and you can even store configuration
data as
XML (that you must interpret yourself), but the path of least resistance it
to use &create-instance; and nested &set; elements to create the objects to be
contributed.
</p>
</li>
</ul>
</section>
</body>
</document>
1.4 +4 -2 jakarta-commons-sandbox/hivemind/common/links.xml
Index: links.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/common/links.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- links.xml 9 Jun 2003 22:23:08 -0000 1.3
+++ links.xml 11 Jun 2003 18:43:12 -0000 1.4
@@ -1,7 +1,7 @@
<!-- $Id$ -->
-<!ENTITY _module '<code><code><module></code></code>'>
+<!ENTITY _module '<code><module></code>'>
<!ENTITY module '<a href="descriptor.html#module">&_module;</a>'>
<!ENTITY _service '<code><service></code>'>
@@ -67,3 +67,5 @@
<!ENTITY _contribute-configuration '<code><contribute-configuration></code>'>
<!ENTITY contribute-configuration '<a
href="descriptor.html#contribute-configuration">&_contribute-configuration;</a>'>
+<!ENTITY _description '<code><description></code>'>
+<!ENTITY description '<a href="descriptor.html#description">&_description;</a>'>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
