hivemind-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hls...@apache.org
Subject svn commit: r394433 - /jakarta/hivemind/trunk/support/forrest2maven-xdoc.xdoc.xml
Date Sun, 16 Apr 2006 04:41:04 GMT
Author: hlship
Date: Sat Apr 15 21:41:04 2006
New Revision: 394433

URL: http://svn.apache.org/viewcvs?rev=394433&view=rev
Log:
Reorganize Forrest documentation for easier batch transformation
Create a XSL stylesheet to convert from Forrest to Maven's xdoc format
Convert some of the core framework documentation to Maven xdoc format

Added:
    jakarta/hivemind/trunk/support/forrest2maven-xdoc.xdoc.xml

Added: jakarta/hivemind/trunk/support/forrest2maven-xdoc.xdoc.xml
URL: http://svn.apache.org/viewcvs/jakarta/hivemind/trunk/support/forrest2maven-xdoc.xdoc.xml?rev=394433&view=auto
==============================================================================
--- jakarta/hivemind/trunk/support/forrest2maven-xdoc.xdoc.xml (added)
+++ jakarta/hivemind/trunk/support/forrest2maven-xdoc.xdoc.xml Sat Apr 15 21:41:04 2006
@@ -0,0 +1,476 @@
+<?xml version="1.0" encoding="utf-8"?><!-- 
+   Copyright 2004, 2005 The Apache Software Foundation
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<document>
+   <properties>
+      <title>hivemind.BuilderFactory Service</title>
+   </properties>
+</document>
+<body>
+		
+   <p>The <a href="../hivedocs/service/hivemind.BuilderFactory.html">
+			BuilderFactory</a> service is a service implementation factory ... a
+			service that is used to construct other services.</p>
+		
+   <p>The builder factory takes a single parameter element (usually with nested elements):</p>
+		
+   <source xml:space="preserve">
+&lt;construct
+    class="..." autowire-services="..." log-property="..." messages-property="..."
+    service-id-property="..." initialize-method="..." error-log-property="..."
+    error-handler-property="..." class-resolver-property="..."&gt;
+    
+    &lt;log/&gt;
+    &lt;messages/&gt;
+    &lt;service-id/&gt;
+    &lt;error-handler/&gt;
+    &lt;error-log/&gt;
+    &lt;class-resolver/&gt;
+    &lt;string&gt;  ... &lt;/string&gt;
+    &lt;boolean&gt; ... &lt;/boolean&gt;
+    &lt;configuration&gt; ... &lt;/configuration&gt;
+    &lt;int&gt; ... &lt;/int&gt;
+    &lt;long&gt; ... &lt;/long&gt;
+    &lt;resource&gt; ... &lt;/resource&gt;
+    &lt;service&gt; ... &lt;/service&gt;
+    &lt;object&gt; ... &lt;/object&gt;
+    &lt;null/&gt;
+    
+    &lt;event-listener service-id="..." event-type-name="..."/&gt;
+    &lt;set property="..." value="..."/&gt;
+    &lt;set-configuration property="..." configuration-id="..."/&gt;
+    &lt;set-resource property="..." path="..."/&gt;
+    &lt;set-service property="..." service-id="..."/&gt;
+    &lt;set-object property="..." value="..."/&gt;
+&lt;/construct&gt; </source>
+		<p>The attributes of the <code>construct</code> element are used to specify
+			the implementation class and set common service properties. Nested
+			elements supply the constructor parameters and configure other specific
+			properties of the implementation (the <code>set-...</code> elements).</p>
+      
+      <p><strong>Note:</strong><br/>
+     BuilderFactory is a complex tool, with support for both constructor dependency injection
and
+     property dependency injection. Many of the options are rarely used; the most general
purpose
+     and most frequently used are <a href="#set">set</a>, <a href="#set-object">set-object</a>
+     and <a href="#event-listener">event-listener</a> (along with
+     <a href="#Autowiring">autowiring</a>).
+      </p>
+      
+		<section name="construct">
+			
+			<table>
+				<tr>
+					<th>Attribute</th>
+					<th>Required ?</th>
+					<th>Description</th>
+				</tr>
+        <tr>
+          <td>autowire-services</td>
+          <td>no</td>
+          <td>If true (the default), then the BuilderFactory will attempt to
+            automatically wire services and some common properties to constructor parameters

+            and to properties of the constructed implementation with setter methods (see
notes below).
+            </td>
+        </tr>
+				<tr>
+					<td>class</td>
+					<td>yes</td>
+					<td>The fully qualified name of the class to instantiate.</td>
+				</tr>
+        <tr><td>class-resolver-property</td>
+          <td>no</td>
+            <td>The property to receive the module's
+          <a href="../hivemind/apidocs/org/apache/hivemind/ClassResolver.html">ClassResolver</a>.</td></tr>
+        <tr><td>error-handler-property</td>
+          <td>no</td>
+          <td> The name of a property to recieve the module's 
+            <a href="../hivemind/apidocs/org/apache/hivemind/ErrorHandler.html">ErrorHandler</a>
instance (which is used to report recoverable 
+            errors). </td>
+          </tr>
+        <tr>
+          <td>error-log-property</td>
+          <td>no</td>
+          <td>The name of a property which will be assigned an <a href="../hivemind/apidocs/org/apache/hivemind/ErrorLog.html">ErrorLog</a>
instance for the service. An ErrorLog is 
+            simply a wrapper around a Log and an <a href="../hivemind/apidocs/org/apache/hivemind/ErrorHandler.html">ErrorHandler</a>
as is the preferred approach.</td>
+        </tr>          
+				<tr>
+					<td>initialize-method</td>
+					<td>no</td>
+					<td>The name of a method (public, no parameters) to invoke after the
+						service is constructed, to allow it to perform any final
+						initializion before being put into use.</td>
+				</tr>
+				<tr>
+					<td>log-property</td>
+					<td>no</td>
+					<td>The name of a property which will be assigned a <code>
+						org.apache.commons.logging.Log</code> instance for the service. The
+						Log is created from the complete service id (not the name of the
+						class). If ommitted (and autowiring is disabled), no Log will be assigned.</td>
+				</tr>
+				<tr>
+					<td>messages-property</td>
+					<td>no</td>
+					<td>Allows the <a href="../hivemind/apidocs/org/apache/hivemind/Messages.html">Messages</a>
for the module to be assigned to a
+						property of the instance.</td>
+				</tr>
+				<tr>
+					<td>service-id-property</td>
+					<td>no</td>
+					<td>Allows the service id of the <em>constructed</em> service to be
+						assigned to a property of the service implementation.</td>
+				</tr>
+			</table>
+			<p>The remaining elements are enclosed by the &lt;construct&gt; element,
+				and are used to supply constructor parameters and configure properties
+				of the constructed service implementation.</p>
+		</section>
+    
+    <section name="Autowiring">
+      
+      
+      <p>
+        With <code>autowire-services</code> set to true the BuilderFactory can
automatically both perform
+        constructor based and setter based dependency injection.  It will not only attempt
to inject 
+        services but also certain common properties.  By using standard names (and standard
types), 
+        the need to specify attributes <code>log-property</code>, <code>error-handler-property</code>,

+        etc. is avoided.  Simply declaring a constructor parameter with the correct type
<em>or</em> a 
+        writable property with the correct name <em>and</em> type is sufficient:
+      </p>
+      
+      <table>
+        <tr>
+          <th>Property name</th>
+          <th>Property / parameter type</th>
+        </tr>
+        <tr>
+          <td>classResolver</td>
+          <td><a href="../hivemind/apidocs/org/apache/hivemind/ClassResolver.html">ClassResolver</a></td>
+        </tr>
+        <tr>
+          <td>errorHandler</td>
+          <td><a href="../hivemind/apidocs/org/apache/hivemind/ErrorHandler.html">ErrorHandler</a></td>
+        </tr>
+        <tr>
+          <td>errorLog</td>
+          <td><a href="../hivemind/apidocs/org/apache/hivemind/ErrorLog.html">ErrorLog</a></td>
+        </tr>
+        <tr>
+          <td>log</td>
+          <td>
+            <code>org.apache.commons.logging.Log</code>
+          </td>
+        </tr>
+        <tr>
+          <td>messages</td>
+          <td><a href="../hivemind/apidocs/org/apache/hivemind/Messages.html">Messages</a></td>
+          <td/>
+        </tr>
+        <tr>
+          <td>serviceId</td>
+          <td>String</td>
+        </tr>
+      </table>
+      
+      <p><strong>Note:</strong><br/>
+        The service id (last entry in above table) will <em>only</em> be automatically
injected through a writable property
+        (i.e. <code>setServiceId(String)</code>).  This because a constructor
parameter of type String
+        is far too common.
+      </p>
+      
+      <p>
+        As noted the BuilderFactory will also inject services into the constructed service
implementation. 
+        Through every constructor parameter and writable property whose type is an interface
(with the exception 
+        of the common parameters / properties listed above) and hasn't been set otherwise
the BuilderFactory will 
+        attempt to inject a service.  This attempt may fail if there is <em>no</em>
visible service or <em>more than 
+        one</em> visible service implementing the given interface.  (Visibility is
checked with respect to the module 
+        declaring the constructed service's implementation.)
+      </p>
+      
+      <p>
+        The action taken if the service injection fails (due to one of the reasons given
above) depends on the type 
+        of dependency injection.  For constructor based dependency injection the BuilderFactory
will try using a 
+        different constructor (see selection details below).  If no "working" constructor
is found an error 
+        is logged.  For setter based dependency injection the BuilderFactory will log an
error immedeately upon failed injection.
+      </p>
+      
+      <p>
+        Constructor based dependency injection is enabled with the <code>autowire-services</code>
attribute but can be 
+        overridden by declaring any constructor parameter elements (see next section).  The
constructor being used for
+        the constructor based dependency injection has to meet all of the following criteria:
+      </p>
+
+      <ul>
+        <li>the constructor is declared as <code>public</code></li>
+        <li>all parameter types are interfaces (including the common types listed above)</li>
+        <li>no two parameters are of the same type</li>
+      </ul>
+
+      <p>
+        All constructors of the service implementation class meeting these criteria (the
default constructor is 
+        considered as one of these) are ordered by length (given by the number of parameters)
and the first of these for which 
+        every parameter type either has a matching common property or there is exactly one
corresponding visible service 
+        available will be invoked.  If no such constructor can be found an error is logged.
+      </p>
+
+      <p>
+        Autowiring may be  complicated by the fact that one module may define a service point
that will tangentially affect the
+        construction of a service in another module (simply by implementing the same service
interface).  In this situation, 
+        service autowiring can be turned off, by setting the <code>autowire-services</code>
attribute to false.
+      </p>
+      
+      <p>
+       Once all properties have been set (possibly by autowiring), an initializer method
will be invoked.  If the 
+       <code>initialize-method</code> attribute is <em>not</em> specified,
and the service implementation includes a 
+       public method <code>initializeService()</code> (no parameters, returns
void), then <code>initializeService()</code> 
+       will be invoked as the initializer.
+      </p>
+      
+    </section>
+    
+		<section name="Constructor Parameter Elements">
+			
+			<p>The following table summarizes the elements which can be used to
+				specify constructor parameters for the class to instantiate. These
+				elements can be mixed freely with the properties configuring elements.
+				It is important to know that the number, type, and order of the
+				constructor parameter elements determine the constructor that will be
+				used to instantiate the implementation.</p>
+			<table>
+				<tr>
+					<th>Element</th>
+					<th>Matched Parameter Type</th>
+					<th>Passed Parameter Value</th>
+				</tr>
+        <tr>
+          <td>error-handler</td>
+          <td><a href="../hivemind/apidocs/org/apache/hivemind/ErrorHandler.html">ErrorHandler</a></td>
+          <td>The module's ErrorHandler, user to report recoverable errors.</td>
+        </tr>
+        <tr>
+          <td>error-log</td>
+          <td><a href="../hivemind/apidocs/org/apache/hivemind/ErrorLog.html">ErrorLog</a></td>
+          <td>The service's ErrorLog, used to report recoverable errors (this is preferred

+			over using a Log and an <a href="../hivemind/apidocs/org/apache/hivemind/ErrorHandler.html">ErrorHandler</a>).</td>
+        </tr>        
+				<tr>
+					<td>log</td>
+					<td>org.apache.commons.logging.Log</td>
+					<td>The Log is created from the complete service id (not the name of
+						the class) of the created service.</td>
+				</tr>
+				<tr>
+					<td>messages</td>
+					<td><a href="../hivemind/apidocs/org/apache/hivemind/Messages.html">Messages</a></td>
+					<td>The <a href="../hivemind/apidocs/org/apache/hivemind/Messages.html">Messages</a>
object of the invoking module.</td>
+				</tr>
+        <tr>
+          <td>object</td>
+          <td><em>variable</em></td>
+          <td>As determined by the object translator, this is decidedly free-form.
See <a href="site:hivemind.ObjectProviders">hivemind.ObjectProviders</a>.</td>
+        </tr>
+        <tr>
+          <td>null</td>
+          <td><em>any reference type</em></td>
+          <td>Always simply <code>null</code>.</td>
+        </tr>
+				<tr>
+					<td>service-id</td>
+					<td>java.lang.String</td>
+					<td>The service id of the <em>constructed</em> service.</td>
+				</tr>
+				<tr>
+					<td>string</td>
+					<td>java.lang.String</td>
+					<td>This element's content.</td>
+				</tr>
+				<tr>
+					<td>boolean</td>
+					<td>boolean</td>
+					<td>This element's content. Must be either "true" or "false".</td>
+				</tr>
+				<tr>
+					<td>configuration</td>
+					<td>java.util.List <em>or</em> java.util.Map</td>
+					<td>The List / Map of the elements of the configuration specified by this
+						element's content as a configuration id. The id can either by a
+						simple id for a configuration within the same module as the
+						constructed service, or a complete id.</td>
+				</tr>
+				<tr>
+					<td>int</td>
+					<td>int</td>
+					<td>This element's content parsed as an integer value.</td>
+				</tr>
+				<tr>
+					<td>long</td>
+					<td>long</td>
+					<td>This element's content parsed as a long value.</td>
+				</tr>
+				<tr>
+					<td>resource</td>
+					<td><a href="../hivemind/apidocs/org/apache/hivemind/Resource.html">Resource</a></td>
+					<td>This element's content parsed as a path to a <a href="../hivemind/apidocs/org/apache/hivemind/Resource.html">Resource</a>,
which
+						is relative to the contributing module's deployment descriptor. If
+						available, a localized version of the Resource will be selected.</td>
+				</tr>
+				<tr>
+					<td>service</td>
+					<td>interface corresponding to specified service</td>
+					<td>The implementation of the service with the id given in this
+						element's content. The id can either be a simple id for a service
+						within the same module as the constructed service, or a complete id.</td>
+				</tr>
+			</table>
+		</section>
+		<section name="Service Property Configuring Elements">
+			
+			<subsection name="event-listener">
+				
+				<table>
+					<tr>
+						<th>Attribute</th>
+						<th>Description</th>
+					</tr>
+					<tr>
+						<td>service-id</td>
+						<td>The service which produces events. The service must provide, in
+							its service interface, the necessary add and remove listener
+							methods.</td>
+					</tr>
+					<tr>
+						<td>name</td>
+						<td>The name of an event set to be registered. If not specified, all
+							applicable event sets are used.</td>
+					</tr>
+				</table>
+				<p>If the name attribute is not specified, then BuilderFactory will
+					register for all applicable event sets. For each event set provided by
+					the specified service, BuilderFactory will check to see if the service
+					instance being constructed implements the corresponding listener
+					interface ... if so, the constructed service instance is added as a
+					listener. When the name attribute is specified, the constructed
+					service instance is registered as a listener of just that single type.</p>
+				<p>Event notifications go directly to the constructed service instance;
+					they don't go through any proxies or interceptors for the service. The
+					service <em>instance</em> must implement the listener interface, the
+					constructed service's service interface <em>does not</em> have to
+					extend the listener interface. In other words, event notifications are
+					"behind the scenes", not part of the public API of the service.</p>
+				<p>It is perfectly acceptible to include multiple &lt;event-listener&gt;
+					elements for a number of different event producing services.</p>
+				<p>It is not enough for the event producer service to have an add
+					listener method (i.e., <code>
+					addPropertyChangeListener(PropertyChangeListener)</code>). To be
+					recognized as an event set, there must also be a corresponding remove
+					listener method (i.e., <code>
+					removePropertyChangeListener(PropertyChangeListener)</code>), even
+					though BuilderFactory does not make use of the remove method. This is
+					an offshoot of how the JavaBeans API defines event sets.</p>
+			</subsection>
+			<subsection name="set">
+				
+				<table>
+					<tr>
+						<th>Attribute</th>
+						<th>Description</th>
+					</tr>
+					<tr>
+						<td>property</td>
+						<td>The name of the property to set.</td>
+					</tr>
+					<tr>
+						<td>value</td>
+						<td>A value to assigned to the property. The value will be converted
+							to an appropriate type for the property.</td>
+					</tr>
+				</table>
+			</subsection>
+			<subsection name="set-configuration">
+				
+				<table>
+					<tr>
+						<th>Attribute</th>
+						<th>Description</th>
+					</tr>
+					<tr>
+						<td>property</td>
+						<td>The name of the property to set.</td>
+					</tr>
+					<tr>
+						<td>configuration-id</td>
+						<td>The id of a configuration, either a simple id for a
+							configuration within the same module as the constructed service,
+							or a complete id. The property will be assigned a <code>List</code>
+							or <code>Map</code> of the elements of the configuration.</td>
+					</tr>
+				</table>
+			</subsection>
+      <subsection name="set-object">
+        
+          <table>
+            <tr><th>Attribute</th> <th>Description</th></tr>
+            <tr>
+              <td>property</td>
+              <td>The name of the property to set.</td>
+            </tr>
+            <tr>
+              <td>value</td>
+              <td>The <em>selector</em> used to find an object value. 
The selector consists of a prefix (such as 
+                "service" or "configuration"), a colon, and a <em>locator</em>
whose interpretation is defined by 
+                the prefix.  For example, <code>service:MyService</code>.  See
<a href="site:hivemind.ObjectProviders">hivemind.ObjectProviders</a>.</td>
+            </tr>
+          </table>
+      </subsection>
+			<subsection name="set-resource">
+				
+				<table>
+					<tr>
+						<th>Attribute</th>
+						<th>Description</th>
+					</tr>
+					<tr>
+						<td>property</td>
+						<td>The name of the property to set.</td>
+					</tr>
+					<tr>
+						<td>path</td>
+						<td>The path to a <a href="../hivemind/apidocs/org/apache/hivemind/Resource.html">Resource</a>,
relative to the contributing
+							module's deployment descriptor. If available, a localized version
+							of the Resource will be selected.</td>
+					</tr>
+				</table>
+			</subsection>
+			<subsection name="set-service">
+				
+				<table>
+					<tr>
+						<th>Attribute</th>
+						<th>Description</th>
+					</tr>
+					<tr>
+						<td>property</td>
+						<td>The name of the property to set.</td>
+					</tr>
+					<tr>
+						<td colspan="col3" rowspan="row3" id="foo">service-id</td>
+						<td id="bar">The id of a service, either a simple id for a service within the
+							same module as the constructed service, or a complete id. The
+							property will be assigned the service.</td>
+					</tr>
+				</table>
+			</subsection>
+		</section>
+	</body>
\ No newline at end of file



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


Mime
View raw message