commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hls...@apache.org
Subject cvs commit: jakarta-commons-sandbox/hivemind/src/test/hivemind/test/external TestExternalParser.java
Date Fri, 06 Jun 2003 21:56:30 GMT
hlship      2003/06/06 14:56:30

  Modified:    hivemind/xdocs descriptor.xml services.xml
               hivemind/src/test/hivemind/test/config
                        TestConfiguration.java
               hivemind .classpath project.xml
               hivemind/src/test/hivemind/test HiveMindTestCase.java
               hivemind/common links.xml
               hivemind/src/test/hivemind/test/external
                        TestExternalParser.java
  Added:       hivemind/src/test/hivemind/test/config ValueVariables.xml
               hivemind project.properties
  Log:
  Allow runtime variables inside the <value> and <set> elements.
  Finish documenting the HiveMind module deployment descriptor.
  Link to Tapestry 3.0-beta-1a.
  
  Revision  Changes    Path
  1.2       +799 -283  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.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- descriptor.xml	4 Jun 2003 03:05:49 -0000	1.1
  +++ descriptor.xml	6 Jun 2003 21:56:29 -0000	1.2
  @@ -1,45 +1,25 @@
   <?xml version="1.0"?>
   <!-- $Id$ -->
   <!DOCTYPE document [
  -	
  -<!ENTITY % common-links SYSTEM "../common/links.xml">
  -
  -%common-links;
  -  
  -]>
  -
  +	<!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>
  -
  +	<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[
  +		<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"
  @@ -49,249 +29,785 @@
     . . .
   </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>
  -  
  -  
  +		</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>
  +		<section name="contribute-service">
  +			<p>The &_contribute-service; element contributes a core implementation or
  +				interceptor to a service extension point.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>service-id</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The fully qualified id of the service extension point to
  +						contribute to.</td>
  +				</tr>
  +				<tr>
  +					<th colspan="2">Element</th>
  +					<th>Count</th>
  +					<th>Description</th>
  +				</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>
  +		<section name="configuration">
  +			<p>The &_configuration; element defines a configuration 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>element-type</td>
  +					<td>class name</td>
  +					<td>yes</td>
  +					<td>The fully qualified name of a Java class or interface. All
  +						contributions to the extension point must be assignable to the
  +						specified type.</td>
  +				</tr>
  +				<tr>
  +					<td>count</td>
  +					<td>
  +						<code>unbounded | 0..1 | 1 | 1..n</code>
  +					</td>
  +					<td>no</td>
  +					<td>The number of contributions allowed: <ul> <li><b>unbounded</b> 
  +						(default): any number</li> <li><b>0..1</b>: optional</li> <li><b>1</b>
  +						: required</li> <li><b>1..n</b>: at least one</li> </ul> </td>
  +				</tr>
  +				<tr>
  +					<td>cache-elements</td>
  +					<td>boolean</td>
  +					<td>no</td>
  +					<td>If true (the default), then the list of elements created from the
  +						contributions are cached and reused on subsequent accesses. If
  +						false, then the list of elements is created fresh on each access to
  +						the configuration extension point.</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 configuration extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#expression">expression</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Evaluates an OGNL expression and adds the result as a contribution
  +						to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#value">value</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Includes a literal value as a contribution to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#service-ref">service-ref</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Obtains a service as a contribution to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#xml">xml</a>
  +					</td>
  +					<td>0..n.</td>
  +					<td>Reads an XML file and assigns the root element, as an instance of
  +						IElement. The configuation extension point must also be type
  +						IElement.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#create-instance">create-instance</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Creates an element as a contribution to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#factory">factory</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Uses a factory service to create an instance as a contribution to
  +						the extension point.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="contribute-configuration">
  +			<p>The &_contribute-configuration; element contributes elements to an
  +				existing configuration extension point.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>configuration-id</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The fully qualified id of the service extension point to
  +						contribute to.</td>
  +				</tr>
  +				<tr>
  +					<th colspan="2">Element</th>
  +					<th>Count</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#expression">expression</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Evaluates an OGNL expression and adds the result as a contribution
  +						to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#value">value</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Includes a literal value as a contribution to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#service-ref">service-ref</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Obtains a service as a contribution to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#xml">xml</a>
  +					</td>
  +					<td>0..n.</td>
  +					<td>Reads an XML file and assigns the root element, as an instance of
  +						IElement. The configuation extension point must also by type
  +						IElement.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#create-instance">create-instance</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Creates an element as a contribution to the extension point.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#factory">factory</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Uses a factory service to create an instance as a contribution to
  +						the extension point.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="create-instance">
  +			<p> &_create-instance; instantiates an object from a class name, and then
  +				configures the new object. The object may be contributed to a service
  +				extension point or configuration extension point.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>class</td>
  +					<td>class name</td>
  +					<td>yes</td>
  +					<td>Fully qualified class name to instantiate.</td>
  +				</tr>
  +				<tr>
  +					<th colspan="2">Element</th>
  +					<th>Count</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#set-expression">set-expression</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Evaluates an OGNL expression and assigns its value to a property
  +						of the object</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#set">set</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Sets a property of the object to a literal value.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#setservice-ref">set-service-ref</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Sets a property of the object by looking up a service.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#xml">xml</a>
  +					</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 IElement.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#set-create">set-create</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Sets a property of the object to a newly created (and configured)
  +						object.</td>
  +				</tr>
  +				<tr>
  +					<td colspan="2">
  +						<a href="#set-factory">set-factory</a>
  +					</td>
  +					<td>0..n</td>
  +					<td>Sets a property of the object to a newly created (and configured)
  +						object obtained from a factory service.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="set-create"> <p> &_set-create; instantiates an object from a
  +			class name, and then configures the new object. The object is then
  +			assigned to a property.</p> <p>&_set-create; contains the same elements as&create-instance;</p>
  +			. <table> <tr> <th>Attribute</th> <th>Type</th> <th>Required ?</th> <th>
  +			Description</th> </tr> <tr> <td>property</td> <td>string</td> <td>yes</td>
  +			<td>The name of the property to be updated to the newly created object.</td></tr>
  +			<tr> <td>class</td> <td>class name</td> <td>yes</td> <td>Fully qualified
  +			class name to instantiate.</td> </tr> </table> </section>
  +		<section name="factory">
  +			<p> &_factory; instantiates an object obtains a factory instance and has
  +				the factory create a new instance, which is configured.</p>
  +			<p>&_factory; contains the same elements as &create-instance;.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>property</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The name of the property to be updated to the newly created
  +						object.</td>
  +				</tr>
  +				<tr>
  +					<td>service-id</td>
  +					<td>service id</td>
  +					<td>yes</td>
  +					<td>Fully qualified service id. The service must implement the
  +						interface IFactory.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="set-factory">
  +			<p> &_set-factory; instantiates an object obtained from a factory instance
  +				and has the factory create a new instance, which is configured.</p>
  +			<p>&_set-factory; contains the same elements as &create-instance;.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>service-id</td>
  +					<td>service id</td>
  +					<td>yes</td>
  +					<td>Fully qualified service id. The service must implement the
  +						interface IFactory.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="interceptor">
  +			<p>&_interceptor; contributes an interceptor factory to a service
  +				extension point. An interceptor factory is a service which implements
  +				the IInterceptorFactory interface.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>service-id</td>
  +					<td>service id</td>
  +					<td>yes</td>
  +					<td>Fully qualified id of the interceptor factory service.</td>
  +				</tr>
  +				<tr>
  +					<td>order</td>
  +					<td>number</td>
  +					<td>no</td>
  +					<td>A numeric value used to set the order in which interceptors are
  +						applied. Lowest orders go first; the default value is 0.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="expression">
  +			<p>&_expression; is used to evaluate an OGNL expression and assign its
  +				value as a contribution to a configuration extension point.</p>
  +			<p>The body of the &_expression; tag contains the OGNL expression to
  +				evaluate.</p>
  +			<p>The OGNL expression is evaluated when the element list is constructed;
  +				this occurs on first demand (or on every demand, if the configuration
  +				extension point does not cache its element list).</p>
  +			<p>The contributing module is the root object for the expression (meaning
  +				properties of the module may be used, including <code>repository</code> 
  +				to access the HiveMind repository).</p>
  +		</section>
  +		<section name="set-expression">
  +			<p>&_set-expression; is similar to &expression;, but is used to update a
  +				property of an object.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>property</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The name of the property to be updated.</td>
  +				</tr>
  +				<tr>
  +					<td>expression</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The OGNL expression to evaluate. The result is assigned to the
  +						property.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="value">
  +			<p>&_value; is used to contribute a literal value to a configuration
  +				extension point. Simple conversions from string to boolean or a numeric
  +				type occur automatically. Variable references in the value are expanded.</p>
  +			<p>The body of the &_value; element is the literal value to contribute.</p>
  +		</section>
  +		<section name="set">
  +			<p>&_set; sets a property of an object to a literal value. Internally, it
  +				is processed similar to &value;.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>property</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The name of the property to be updated.</td>
  +				</tr>
  +				<tr>
  +					<td>value</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The literal value to assign to the property.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="service-ref">
  +			<p>&_service-ref; is used to contribute a service instance to a
  +				configuration extension point.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>service-id</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The fully qualified id of the service to be contributed.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="set-service-ref">
  +			<p>&_set-service-ref; is used update a property value to a service
  +				instance.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>property</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The name of the property to be updated.</td>
  +				</tr>
  +				<tr>
  +					<td>service-id</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The fully qualified id of the service to be contributed.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="xml">
  +			<p> &_xml; reads an XML file and parses it into a light-wieght DOM. An
  +				instance of IElement, representing the root element of the XML file, is
  +				contributed to the configuration.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>path</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The path, relative to the contributing module's descriptor, of the
  +						XML file to read.</td>
  +				</tr>
  +			</table>
  +		</section>
  +		<section name="set-xml">
  +			<p> &_set-xml; updates a property of an object to the root element of an
  +				XML file.</p>
  +			<table>
  +				<tr>
  +					<th>Attribute</th>
  +					<th>Type</th>
  +					<th>Required ?</th>
  +					<th>Description</th>
  +				</tr>
  +				<tr>
  +					<td>property</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The name of the property to be updated.</td>
  +				</tr>
  +				<tr>
  +					<td>path</td>
  +					<td>string</td>
  +					<td>yes</td>
  +					<td>The path, relative to the contributing module's descriptor, of the
  +						XML file to read. The root element of the XML file, represented as
  +						an instance of IElement, is assigned to the property.</td>
  +				</tr>
  +			</table>
  +		</section>
   	</body>
  -</document>
  \ No newline at end of file
  +</document>
  
  
  
  1.3       +142 -262  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.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- services.xml	4 Jun 2003 03:05:49 -0000	1.2
  +++ services.xml	6 Jun 2003 21:56:29 -0000	1.3
  @@ -1,162 +1,92 @@
   <?xml version="1.0"?>
   <!-- $Id$ -->
   <!DOCTYPE document [
  -	
  -<!ENTITY % common-links SYSTEM "../common/links.xml">
  -
  -%common-links;
  -  
  -]>
  +	<!ENTITY % common-links SYSTEM "../common/links.xml">
  +	%common-links;
  +	]>
   <document>
  -
  -  <properties>
  -    <title>HiveMind Services</title>
  -    <author email="hlship@apache.org">Howard M. Lewis Ship</author>
  -  </properties>
  -
  -  <body>
  - 
  - 		<section name="Introduction">
  - 			
  - 		<p>
  - 		In HiveMind, a service is simply an object that implements an interface.  You
  - 		supply the interface (in a module).  You supply the core implementation of the
  - 		interface (in the same module, or in a different module).  At runtime,
  - 		HiveMind puts it all together.	
  - 		</p>	
  - 		
  - 		<p>
  - 		HiveMind services are singletons: shared instances.  Much like a Java servlet,
  - 		a HiveMind service implementation must be thread-safe.  You should not store
  - 		any state inside a service.
  - 		</p>
  - 			
  - 		</section>
  -
  -	  <section name="Defining Services">
  -	  	
  -	  <p>
  -	  A service definition begins with a Java interface.  Any interface will
  -	  do, HiveMind doesn't care, and there's no base HiveMind interface.	
  -	  </p>
  -	  
  -	  <p>
  -	  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). 
  -	  An example is provided later in this document.
  -	  </p>
  -	  
  -	  <p>
  -	  A service definition may include <em>service contributions</em>, or may leave that
  -	  for another module.
  -	  </p>
  -	  
  -	  <p>
  -	  Ultimately, a service will consist of a core implementation (a Java object that
  -	  implements the service interface) and, optionally, any number of interceptors.
  -	  Interceptors sit between the core implementation and the client, and add functionality
  -	  to the core implementation such as logging, security, transaction demarkation or
  -	  performance monitoring.	
  -	  </p>
  -	  
  -	  </section>
  -	  
  -	  <section name="Contributing to Services">
  -	  
  -	  <p>
  -	  Any module may contribute to any service extension point.  A
  -	  <code>&lt;contribute-service&gt;</code> element contains these contributions.
  -	  Contributions take three forms:
  -	  <ul>
  -	    <li>Instance Creators</li>	
  -	    <li>Instance Factories</li>
  -	    <li>Interceptors</li>
  -	  </ul>
  -	  </p>
  -	  
  -	  <subsection name="Factory Contributions">
  -	  
  -	  <p>
  -	  A factory contribution is used to instantiate a Java class as the core implementation
  -	  instance for the service.  This instance may be configured as well (by setting properties
  -	  of the instance).
  -	  </p>
  -	  	
  -	  <p>
  -	  There are two forms of service constructors: instance creators and instance factories.	
  -	  </p>
  -	  
  -	  <p>
  -	  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>&lt;factory&gt;</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.
  -	  </p>
  -	  
  -	  <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.
  -	  </p>
  -	  	
  -	  </subsection>
  -	  
  -	  <subsection name="Interceptor Contributions">
  -	  
  -	  <p>
  -	  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>
  -	  
  -	  <p>
  -	  An interceptor factory knows how to create an object that implements an arbitrary interface,
  -	  adding the functionality of that interface.  For example, a logging interceptor factory would create 
  -	  an object instance that logged entry and exit to each method.  The factory shouldn't care
  -	  what the interface itself is ... it should adapt to whatever interface it defined by
  -	  the service extension point it will create an instance for.
  -	  </p>
  -	  	
  -	  	<p>
  -	  Interceptor factories
  -	  can be implemented using dynamic proxies (a feature introduced in JDK 1.3), or by dynamic
  -	  bytecode enhancement.	
  -	  </p>
  -	  
  -	  <p>
  -	  A service extension point may have any number of interceptor contributions.  If the order
  -	  in which interceptors are applied is important, then the optional <code>order</code>	
  -	  attribute can be specified; it is used to sort the interceptors into the order
  -	  in which they will be applied.  The default order is 0.  Low numbers are executed first,
  -	  and are therefore "closer" to the core instance.  Larger numbers are executed later, and
  -	  are "closer" to the client code.  So you might use an order of 200 for a logging interceptor, and an order
  -	  of 100 for a performance monitor interceptor.  The logging interceptor will execute before the
  -	  performance monitor, and so won't affect its timing.
  -
  -	  </p>
  -	  
  -	  	
  -	  </subsection>
  -	  
  -	  </section>
  -	  <section name="A short example">
  -	  	
  -	  <p>
  -	  As an example, let's create an interface with a single method, used to
  -	  add together two numbers.	
  -	  </p>
  -	  
  -<source><![CDATA[
  +	<properties>
  +		<title>HiveMind Services</title>
  +		<author email="hlship@apache.org">Howard M. Lewis Ship</author>
  +	</properties>
  +	<body>
  +		<section name="Introduction">
  +			<p>In HiveMind, a service is simply an object that implements an
  +				interface. You supply the interface (in a module). You supply the core
  +				implementation of the interface (in the same module, or in a different
  +				module). At runtime, HiveMind puts it all together.</p>
  +			<p>HiveMind services are singletons: shared instances. Much like a Java
  +				servlet, a HiveMind service implementation must be thread-safe. You
  +				should not store any state inside a service.</p>
  +		</section>
  +		<section name="Defining Services">
  +			<p>A service definition begins with a Java interface. Any interface will
  +				do, HiveMind doesn't care, and there's no base HiveMind interface.</p>
  +			<p>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).
  +				An example is provided later in this document.</p>
  +			<p>A service definition may include <em>service contributions</em>, or may
  +				leave that for another module.</p>
  +			<p>Ultimately, a service will consist of a core implementation (a Java
  +				object that implements the service interface) and, optionally, any
  +				number of interceptors. Interceptors sit between the core implementation
  +				and the client, and add functionality to the core implementation such as
  +				logging, security, transaction demarkation or performance monitoring.</p>
  +		</section>
  +		<section name="Contributing to Services">
  +			<p>Any module may contribute to any service extension point. A &lt;
  +				contribute-service&gt; element contains these contributions.
  +				Contributions take three forms: <ul> <li>Instance Creators</li> <li>
  +				Instance Factories</li> <li>Interceptors</li> </ul> </p>
  +			<subsection name="Factory Contributions">
  +				<p>A factory contribution is used to instantiate a Java class as the
  +					core implementation instance for the service. This instance may be
  +					configured as well (by setting properties of the instance).</p>
  +				<p>There are two forms of service constructors: instance creators and
  +					instance factories.</p>
  +				<p>An instance creator is represented by a &create-instance; element. It
  +					includes a class attribute, the Java class to instantiate.</p>
  +				<p>An instance factory is represented by a &factory; element. It
  +					includes a service-id attribute. This is the fully qualfied id of a
  +					factory service, a service which implements the
  +					org.apache.commons.hivemind.IFactory interface.</p>
  +				<p>In both cases, the properties of the core instance may be configured
  +					using enclosed &set;, &set-expression;, &set-create;, &set-factory;
  +					&set-service-ref; and &set-xml;
  +					elements.</p>
  +			</subsection>
  +			<subsection name="Interceptor Contributions">
  +				<p>An interceptor contribution is represented by a &interceptor; 
  +					element. The service-id attribute identifies an interceptor factory
  +					service: a service that implements the
  +					org.apache.commons.hivemind.IInterceptorFactory interface.</p>
  +				<p>An interceptor factory knows how to create an object that implements
  +					an arbitrary interface, adding the functionality of that interface.
  +					For example, a logging interceptor factory would create an object
  +					instance that logged entry and exit to each method. The factory
  +					shouldn't care what the interface itself is ... it should adapt to
  +					whatever interface it defined by the service extension point it will
  +					create an instance for.</p>
  +				<p>Interceptor factories can be implemented using dynamic proxies (a
  +					feature introduced in JDK 1.3), or by dynamic bytecode enhancement.</p>
  +				<p>A service extension point may have any number of interceptor
  +					contributions. If the order in which interceptors are applied is
  +					important, then the optional order attribute can be specified; it is
  +					used to sort the interceptors into the order in which they will be
  +					applied. The default order is 0. Low numbers are executed first, and
  +					are therefore "closer" to the core instance. Larger numbers are
  +					executed later, and are "closer" to the client code. So you might use
  +					an order of 200 for a logging interceptor, and an order of 100 for a
  +					performance monitor interceptor. The logging interceptor will execute
  +					before the performance monitor, and so won't affect its timing.</p>
  +			</subsection>
  +		</section>
  +		<section name="A short example">
  +			<p>As an example, let's create an interface with a single method, used to
  +				add together two numbers.</p>
  +			<source><![CDATA[
   package com.myco.mypackage;
   
   public interface IAdder
  @@ -164,20 +94,14 @@
     public int add(int arg1, int arg2);
   }
   ]]></source>
  -	  	
  -	  <p>
  -	  We've followed the convention of putting a leading 'I' in our interface names but,
  -	  again, HiveMind doesn't care.	We could define many methods, and the methods could
  -	  throw exceptions.  Once more, HiveMind doesn't care.
  -	  </p>
  -	  
  -	  <p>We need to create a module to contain this service.  We'll create a simple
  -	  	HiveMind deployment descriptor.  This is an XML file, named
  -	  	<code>hivemind.xml</code>, that
  -	  	must be included in the module's META-INF directory.
  -	  	</p>
  -	  	
  -<source><![CDATA[
  +			<p>We've followed the convention of putting a leading 'I' in our interface
  +				names but, again, HiveMind doesn't care. We could define many methods,
  +				and the methods could throw exceptions. Once more, HiveMind doesn't
  +				care.</p>
  +			<p>We need to create a module to contain this service. We'll create a
  +				simple HiveMind deployment descriptor. This is an XML file, named
  +				hivemind.xml, that must be included in the module's META-INF directory.</p>
  +			<source><![CDATA[
   <?xml version="1.0" encoding="UTF-8"?>
   <module
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  @@ -187,11 +111,9 @@
     <service id="Adder" interface="com.myco.mypackage.IAdder"/>
   </module>
   ]]></source>
  -	  	
  -	  <p>For this example, we'll create a second module that provides the implementation.  First
  -	  we'll define the implementation class.</p>
  -	  
  -<source><![CDATA[
  +			<p>For this example, we'll create a second module that provides the
  +				implementation. First we'll define the implementation class.</p>
  +			<source><![CDATA[
   package com.myco.mypackage.impl;
   
   import com.myco.mypackage.IAdder;
  @@ -204,12 +126,9 @@
     }
   }
   ]]></source>
  -	  	
  -	  <p>
  -	  That's what we meant by a POJO.	We'll create a second module to provide this implementation.
  -	  </p>	
  -	  
  -<source><![CDATA[
  +			<p>That's what we meant by a POJO. We'll create a second module to provide
  +				this implementation.</p>
  +			<source><![CDATA[
   <?xml version="1.0" encoding="UTF-8"?>
   <module
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  @@ -221,29 +140,15 @@
       <create-instance class="com.myco.mypackage.impl.AdderImpl"/>
     </contribute-service>
   </module>]]></source>
  -	  
  -
  -    <p>
  -    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>
  -    
  -    <p>
  -    The runtime code to access the service is very streamlined:	
  -    </p>
  -    
  -<source>
  -IRegistry registry = HiveMind.getDefault();
  -IAdder service = (IAdder) registry.getService("com.myco.mypackage.Adder", IAdder.class);	
  -
  -int sum = service.add(4, 7);
  -</source>
  -
  -	<p>
  -	Another module may provide an interceptor:	
  -	</p>
  -
  -<source><![CDATA[
  +			<p>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>
  +			<p>The runtime code to access the service is very streamlined:</p>
  +			<source>IRegistry registry = HiveMind.getDefault(); IAdder service =
  +				(IAdder) registry.getService("com.myco.mypackage.Adder", IAdder.class);
  +				int sum = service.add(4, 7);</source>
  +			<p>Another module may provide an interceptor:</p>
  +			<source><![CDATA[
   <?xml version="1.0" encoding="UTF-8"?>
   <module
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  @@ -256,62 +161,37 @@
       <interceptor service-id="com.myco.interceptors.Logging"/>
     </contribute-service>
   </module>]]></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 the AdderImpl class, it will get an instance of
  -	  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>
  -	  
  -	  </section>
  -  
  -  <section name="Frequently Asked Questions">
  -  
  -  <ul>
  -  	<li><strong>Why do I pass the interface class to <code>getService()</code></strong>?
  -  	
  -  	<p>
  -  	
  -  	This is to add an additional level of error checking and reporting.  HiveMind knows, 
  -  	from the module descriptors, 	the interface provided by the service extension point, but
  -  	it can't tell if <em>you</em> know that.  By passing in the interface you'll cast
  -  	the returned service to, HiveMind can verify that you won't get a ClassCastException.
  -  	Instead, it throws an exception with more details (the service extension point id, the actual
  -  	interface provided, and the interface you passed it).
  -  		</p>
  -  		
  -  	</li>	
  -  	
  -  	<li><strong>What if no module provides a core implementation of the service?</strong>
  -  		
  -  
  -  		<p>
  -  		If the service is optional, then <code>getService()</code> will return null.  For
  -  		optional services, you are required to check for null.
  -  		</p>
  -  		
  -  		<p>
  -  		For required services, HiveMind checks for a factory contribution when the registry
  -  		is constructed.  If a required service extension point has no
  -  		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.
  -  		</p>
  -  		</li>
  -  </ul>
  -
  -  	
  -  </section>
  -  
  -
  -
  -  </body>
  +			<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
  +				the AdderImpl class, it will get an instance of 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>
  +		</section>
  +		<section name="Frequently Asked Questions">
  +			<ul>
  +				<li><strong>Why do I pass the interface class to getService()</strong>? 
  +					<p>This is to add an additional level of error checking and reporting.
  +					HiveMind knows, from the module descriptors, the interface provided by
  +					the service extension point, but it can't tell if <em>you</em> know
  +					that. By passing in the interface you'll cast the returned service to,
  +					HiveMind can verify that you won't get a ClassCastException. Instead,
  +					it throws an exception with more details (the service extension point
  +					id, the actual interface provided, and the interface you passed it).</p></li>
  +				<li>
  +					<strong>What if no module provides a core implementation of the
  +						service?</strong>
  +					<p>If the service is optional, then getService() will return null. For
  +						optional services, you are required to check for null.</p>
  +					<p>For required services, HiveMind checks for a factory contribution
  +						when the registry is constructed. If a required service extension
  +						point has no contribution, an error is logged (identifying the
  +						extension point id). In addition, getService() will throw an
  +						ApplicationRuntimeException. So, if a service is required, you don't
  +						have to check for null.</p>
  +				</li>
  +			</ul>
  +		</section>
  +	</body>
   </document>
  
  
  
  1.5       +41 -21    jakarta-commons-sandbox/hivemind/src/test/hivemind/test/config/TestConfiguration.java
  
  Index: TestConfiguration.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/src/test/hivemind/test/config/TestConfiguration.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- TestConfiguration.java	4 Jun 2003 23:52:48 -0000	1.4
  +++ TestConfiguration.java	6 Jun 2003 21:56:29 -0000	1.5
  @@ -65,6 +65,8 @@
   
   import org.apache.commons.hivemind.HiveMind;
   import org.apache.commons.hivemind.IRegistry;
  +import org.apache.commons.hivemind.impl.RegistryBuilder;
  +import org.apache.commons.hivemind.parse.DescriptorParser;
   import org.apache.tapestry.ILocation;
   import org.apache.tapestry.IResourceLocation;
   
  @@ -301,25 +303,43 @@
           // The <create-instance> is on line 9,
           // the <set-location> is on line 11.
       }
  -    
  -	public void testCacheEnabled() throws Exception
  -	{
  -		IRegistry r = buildRegistry("CacheEnabled.xml");
  -		List c1 = r.getConfiguration("hivemind.test.config.CacheEnabled");
  -		List c2 = r.getConfiguration("hivemind.test.config.CacheEnabled");
  -		
  -		assertEquals(2, c1.size());
  -		assertSame(c1, c2);
  -	}
  -	
  -	public void testCacheDisabled() throws Exception
  -	{
  -		IRegistry r = buildRegistry("CacheDisabled.xml");
  -		List c1 = r.getConfiguration("hivemind.test.config.CacheDisabled");
  -		List c2 = r.getConfiguration("hivemind.test.config.CacheDisabled");	
  -		
  -		assertEquals(2, c1.size());
  -		assertEquals(false, c1 == c2);
  -		assertEquals(c1, c2);
  -	}
  +
  +    public void testCacheEnabled() throws Exception
  +    {
  +        IRegistry r = buildRegistry("CacheEnabled.xml");
  +        List c1 = r.getConfiguration("hivemind.test.config.CacheEnabled");
  +        List c2 = r.getConfiguration("hivemind.test.config.CacheEnabled");
  +
  +        assertEquals(2, c1.size());
  +        assertSame(c1, c2);
  +    }
  +
  +    public void testCacheDisabled() throws Exception
  +    {
  +        IRegistry r = buildRegistry("CacheDisabled.xml");
  +        List c1 = r.getConfiguration("hivemind.test.config.CacheDisabled");
  +        List c2 = r.getConfiguration("hivemind.test.config.CacheDisabled");
  +
  +        assertEquals(2, c1.size());
  +        assertEquals(false, c1 == c2);
  +        assertEquals(c1, c2);
  +    }
  +
  +    public void testValueVariables() throws Exception
  +    {
  +        RegistryBuilder b = new RegistryBuilder();
  +        DescriptorParser p = new DescriptorParser();
  +
  +        b.processModule(_resolver, p.parse(getMasterModuleLocation()));
  +        b.processModule(_resolver, p.parse(getLocation("ValueVariables.xml")));
  +
  +        IRegistry r = b.constructRegistry();
  +
  +        List l = r.getConfiguration("hivemind.test.config.Dogs");
  +        assertEquals(1, l.size());
  +
  +        String dog = (String) l.get(0);
  +
  +        assertEquals("Dino", dog);
  +    }
   }
  
  
  
  1.1                  jakarta-commons-sandbox/hivemind/src/test/hivemind/test/config/ValueVariables.xml
  
  Index: ValueVariables.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!-- $Id: ValueVariables.xml,v 1.1 2003/06/06 21:56:29 hlship Exp $ -->
  <module
  	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://jakarta.apache.org/commons/hivemind/schema/HiveMind_1.0.xsd"
  	id="hivemind.test.config" 
  	version="1.0.0">
  	<contribute-configuration configuration-id="org.apache.commons.hivemind.VariableSource">
  	  <create-instance class="org.apache.commons.hivemind.VariableSourceContribution">
  	    <set-create property="source" class="hivemind.test.external.PropertiesVariableSource"/>
  	  </create-instance>	
  	</contribute-configuration>
    <configuration id="Dogs" element-type="java.lang.String">
  		<value>${dog}</value>
    </configuration>
  </module>
  
  
  1.2       +1 -2      jakarta-commons-sandbox/hivemind/.classpath
  
  Index: .classpath
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/.classpath,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- .classpath	30 May 2003 20:52:01 -0000	1.1
  +++ .classpath	6 Jun 2003 21:56:29 -0000	1.2
  @@ -15,9 +15,8 @@
       <classpathentry kind="var" path="MAVEN_REPOS_DIR/commons-logging/jars/commons-logging-1.0.1.jar"/>
       <classpathentry kind="var" path="MAVEN_REPOS_DIR/commons-lang/jars/commons-lang-1.0.jar"/>
       <classpathentry kind="var" path="MAVEN_REPOS_DIR/xerces/jars/xerces-2.2.1.jar"/>
  -    <classpathentry kind="lib"
  -        path="C:/workspace/jakarta-tapestry/lib/tapestry-3.0-beta-1.jar" sourcepath="C:/workspace/jakarta-tapestry/framework/src"/>
       <classpathentry kind="var" path="MAVEN_REPOS_DIR/servletapi/jars/servletapi-2.3.jar"/>
       <classpathentry kind="var" path="MAVEN_REPOS_DIR/xml-apis/jars/xml-apis-1.0.b2.jar"/>
  +    <classpathentry kind="var" path="MAVEN_REPOS_DIR/jakarta-tapestry/jars/tapestry-3.0-beta-1a.jar"/>
       <classpathentry kind="output" path="bin"/>
   </classpath>
  
  
  
  1.4       +21 -10    jakarta-commons-sandbox/hivemind/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/project.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- project.xml	4 Jun 2003 21:46:04 -0000	1.3
  +++ project.xml	6 Jun 2003 21:56:29 -0000	1.4
  @@ -25,15 +25,13 @@
     </description>
   
     <url>http://jakarta.apache.org/commons/hivemind</url>
  -  <issueTrackingUrl>
  -    http://nagoya.apache.org/scarab/servlet/scarab/
  -  </issueTrackingUrl>
  +  <issueTrackingUrl>http://issues.apache.org/bugzilla</issueTrackingUrl>
     <siteAddress>jakarta.apache.org</siteAddress>
     <siteDirectory>
  -    /www/jakarta.apache.org/commons/hivemind
  +   /www/jakarta.apache.org/commons/sandbox/hivemind/
     </siteDirectory>
     <distributionDirectory>
  -    /www/jakarta.apache.org/builds/commons/hivemind
  +		/www/jakarta.apache.org/builds/jakarta-commons-sandbox/hivemind/
     </distributionDirectory>
   
     <repository>
  @@ -45,13 +43,28 @@
       </url>
     </repository>
   
  +  <mailingLists>
  +    <mailingList>
  +      <name>Commons User List</name>
  +      <subscribe>commons-user-subscribe@jakarta.apache.org</subscribe>
  +      <unsubscribe>commons-user-unsubscribe@jakarta.apache.org</unsubscribe>
  +      <archive>http://archives.apache.org/eyebrowse/SummarizeList?listName=commons-user@jakarta.apache.org</archive>
  +    </mailingList>
  +    <mailingList>
  +      <name>Commons Developer List</name>
  +      <subscribe>commons-dev-subscribe@jakarta.apache.org</subscribe>
  +      <unsubscribe>commons-dev-unsubscribe@jakarta.apache.org</unsubscribe>
  +      <archive>http://archives.apache.org/eyebrowse/SummarizeList?listName=commons-dev@jakarta.apache.org</archive>
  +    </mailingList>
  +  </mailingLists>
  +  
     <developers>
   
       <developer>
         <name>Howard M. Lewis Ship</name>
         <id>hlship</id>
         <email>hlship@apache.org</email>
  -      <role>Troublemaker</role>
  +      <roles>Troublemaker</roles>
       </developer>
   	</developers>
   
  @@ -78,7 +91,7 @@
       <dependency>
       	<id>jakarta-tapestry</id>
       	<artifactId>tapestry</artifactId>
  -    	<version>3.0-beta-1</version>
  +    	<version>3.0-beta-1a</version>
       	<url>http://jakarta.apache.org/tapestry/</url>
       </dependency>
       
  @@ -184,8 +197,6 @@
     </build>
     
     <reports>
  -    <report>maven-checkstyle-plugin</report>
  -    <report>maven-jdepend-plugin</report>
       <report>maven-javadoc-plugin</report>
       <report>maven-jxr-plugin</report>
       <report>maven-junit-report-plugin</report>  
  
  
  
  1.1                  jakarta-commons-sandbox/hivemind/project.properties
  
  Index: project.properties
  ===================================================================
  # $Id: project.properties,v 1.1 2003/06/06 21:56:29 hlship Exp $
  
  maven.username=hlship
  
  
  1.5       +13 -1     jakarta-commons-sandbox/hivemind/src/test/hivemind/test/HiveMindTestCase.java
  
  Index: HiveMindTestCase.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/src/test/hivemind/test/HiveMindTestCase.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- HiveMindTestCase.java	4 Jun 2003 23:52:48 -0000	1.4
  +++ HiveMindTestCase.java	6 Jun 2003 21:56:30 -0000	1.5
  @@ -57,6 +57,7 @@
   
   package hivemind.test;
   
  +import java.io.File;
   import java.net.URL;
   
   import junit.framework.AssertionFailedError;
  @@ -170,6 +171,17 @@
       protected void unreachable()
       {
           throw new AssertionFailedError("This code should be unreachable.");
  +    }
  +
  +    /**
  +    	 * Returns the location of the module deployment descriptor for the HiveMind library
  +    	 * itself.  Because the tests may be run inside an IDE, this is resolved using
  +    	 * the filesystem (expecting the current directory to be the project root directory).
  +    	 */
  +    protected IResourceLocation getMasterModuleLocation() throws Exception
  +    {
  +        File f = new File("src/META-INF/hivemodule.xml");
  +        return new URLResourceLocation(f.toURL());
       }
   
   }
  
  
  
  1.2       +45 -14    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.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- links.xml	4 Jun 2003 03:08:26 -0000	1.1
  +++ links.xml	6 Jun 2003 21:56:30 -0000	1.2
  @@ -1,38 +1,69 @@
  -<!ENTITY _module '<code>&lt;module&gt;</code>'>
  +<!-- $Id$ -->
  +
  +
  +<!ENTITY _module '&lt;module&gt;'>
   <!ENTITY module '<a href="descriptor.html#module">&_module;</a>'>
   
  -<!ENTITY _service '<code>&lt;service&gt;</code>'>
  +<!ENTITY _service '&lt;service&gt;'>
   <!ENTITY service '<a href="descriptor.html#service">&_service;</a>'>
   
  -<!ENTITY _create-instance '<code>&lt;create-instance&gt;</code>'>
  +<!ENTITY _create-instance '&lt;create-instance&gt;'>
   <!ENTITY create-instance '<a href="descriptor.html#create-instance">&_create-instance;</a>'>
   
  -<!ENTITY _factory '<code>&lt;factory&gt;</code>'>
  +<!ENTITY _factory '&lt;factory&gt;'>
   <!ENTITY factory '<a href="descriptor.html#factory">&_factory;</a>'>
   
  -<!ENTITY _set '<code>&lt;set&gt;</code>'>
  +<!ENTITY _set '&lt;set&gt;'>
   <!ENTITY set '<a href="descriptor.html#set">&_set;</a>'>
   
  -<!ENTITY _set-expression '<code>&lt;set-expression&gt;</code>'>
  +<!ENTITY _set-expression '&lt;set-expression&gt;'>
   <!ENTITY set-expression '<a href="descriptor.html#set-expression">&_set-expression;</a>'>
   
  -<!ENTITY _set-create '<code>&lt;set-create&gt;</code>'>
  +<!ENTITY _set-create '&lt;set-create&gt;'>
   <!ENTITY set-create '<a href="descriptor.html#set-create">&_set-create;</a>'>
   
  -<!ENTITY _set-factory '<code>&lt;set-factory&gt;</code>'>
  +<!ENTITY _set-factory '&lt;set-factory&gt;'>
   <!ENTITY set-factory '<a href="descriptor.html#set-factory">&_set-factory;</a>'>
   
  -<!ENTITY _interceptor '<code>&lt;interceptor&gt;</code>'>
  +<!ENTITY _interceptor '&lt;interceptor&gt;'>
   <!ENTITY interceptor '<a href="descriptor.html#interceptor">&_interceptor;</a>'>
   
  -<!ENTITY _meta '<code>&lt;meta&gt;</code>'>
  +<!ENTITY _meta '&lt;meta&gt;'>
   <!ENTITY meta '<a href="descriptor.html#meta">&_meta;</a>'>
   
  -<!ENTITY _description '<code>&lt;description&gt;</code>'>
  +<!ENTITY _description '&lt;description&gt;'>
   <!ENTITY description '<a href="descriptor.html#description">&_description;</a>'>
   
  -<!ENTITY _dependency '<code>&lt;dependency&gt;</code>'>
  +<!ENTITY _dependency '&lt;dependency&gt;'>
   <!ENTITY dependency '<a href="descriptor.html#dependency">&_dependency;</a>'>
   
  -<!ENTITY _library '<code>&lt;library&gt;</code>'>
  -<!ENTITY library '<a href="descriptor.html#library">&_library;</a>'>
  \ No newline at end of file
  +<!ENTITY _library '&lt;library&gt;'>
  +<!ENTITY library '<a href="descriptor.html#library">&_library;</a>'>
  +
  +<!ENTITY _configuration '&lt;configuration&gt;'>
  +<!ENTITY configuration '<a href="descriptor.html#configuration">&_configuration;</a>'>
  +
  +<!ENTITY _expression '&lt;expression&gt;'>
  +<!ENTITY expression '<a href="descriptor.html#expression">&_expression;</a>'>
  +
  +<!ENTITY _value '&lt;value&gt;'>
  +<!ENTITY value '<a href="descriptor.html#value">&_value;</a>'>
  +
  +<!ENTITY _service-ref '&lt;service-ref&gt;'>
  +<!ENTITY service-ref '<a href="descriptor.html#service-ref">&_service-ref;</a>'>
  +
  +<!ENTITY _set-service-ref '&lt;set-service-ref&gt;'>
  +<!ENTITY set-service-ref '<a href="descriptor.html#set-service-ref">&_set-service-ref;</a>'>
  +
  +<!ENTITY _xml '&lt;xml&gt;'>
  +<!ENTITY xml '<a href="descriptor.html#xml">&_xml;</a>'>
  +
  +<!ENTITY _set-xml '&lt;set-xml&gt;'>
  +<!ENTITY set-xml '<a href="descriptor.html#set-xml">&_set-xml;</a>'>
  +
  +<!ENTITY _contribute-service '&lt;contribute-service&gt;'>
  +<!ENTITY contribute-service '<a href="descriptor.html#contribute-service">&_contribute-service;</a>'>
  +
  +
  +<!ENTITY _contribute-configuration '&lt;contribute-configuration&gt;'>
  +<!ENTITY contribute-configuration '<a href="descriptor.html#contribute-configuration">&_contribute-configuration;</a>'>
  
  
  
  1.4       +3 -4      jakarta-commons-sandbox/hivemind/src/test/hivemind/test/external/TestExternalParser.java
  
  Index: TestExternalParser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/src/test/hivemind/test/external/TestExternalParser.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- TestExternalParser.java	4 Jun 2003 23:52:49 -0000	1.3
  +++ TestExternalParser.java	6 Jun 2003 21:56:30 -0000	1.4
  @@ -61,6 +61,7 @@
   import hivemind.test.config.MockRegistry;
   
   import java.io.File;
  +import java.net.MalformedURLException;
   import java.net.URL;
   import java.util.List;
   import java.util.Locale;
  @@ -255,11 +256,9 @@
       public void testXMLVariables() throws Exception
       {
           RegistryBuilder b = new RegistryBuilder();
  -        File f = new File("src/META-INF/hivemodule.xml");
  -        IResourceLocation l = new URLResourceLocation(f.toURL());
           DescriptorParser dp = new DescriptorParser();
   
  -        b.processModule(_resolver, dp.parse(l));
  +        b.processModule(_resolver, dp.parse(getMasterModuleLocation()));
           b.processModule(_resolver, dp.parse(getLocation("XMLVariables.xml")));
   
           IRegistry r = b.constructRegistry();
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message