[patch] phoenix docs
Adam Murdoch <[email protected]>
| Newsgroups | gmane.comp.jakarta.avalon.apps.devel,gmane.comp.jakarta.avalon.devel |
|---|---|
| Message-ID | <[email protected]> |
Hi, This patch adds a bunch of detail to the assembly.xml and blockinfo spec pages. It could probably do with some checking for accuracy - most of the info was gleaned from the code. There's also a tiny fix to guide-punit.xml, to turn it into well-formed xml. -- Adam -- To unsubscribe, e-mail: <mailto:[email protected]> For additional commands, e-mail: <mailto:[email protected]>
docpatch.txt
(text/plain, 25.6 KB)
Index: src/documentation/content/guide-punit.xml
===================================================================
RCS file: /home/cvspublic/jakarta-avalon-phoenix/src/documentation/content/guide-punit.xml,v
retrieving revision 1.2
diff -u -r1.2 guide-punit.xml
--- src/documentation/content/guide-punit.xml 4 Dec 2002 13:48:21 -0000 1.2
+++ src/documentation/content/guide-punit.xml 13 Dec 2002 01:48:08 -0000
@@ -12,7 +12,7 @@
external meta information. As such it could be used for unit testing for a wide range of Avalon-Framework
enabled components. Having said that, usage requires some knowledge of multi component applications and
the order of component lifecycling. PUnit builds on JUnit. You should have testing experience of
- <link href="http://www.junit.org">JUnit<link> before using PUnit.
+ <link href="http://www.junit.org">JUnit</link> before using PUnit.
</p>
</section>
<section><title>Example Usage</title>
Index: src/documentation/content/assemblers/assembly-xml-specification.xml
===================================================================
RCS file: /home/cvspublic/jakarta-avalon-phoenix/src/documentation/content/assemblers/assembly-xml-specification.xml,v
retrieving revision 1.1
diff -u -r1.1 assembly-xml-specification.xml
--- src/documentation/content/assemblers/assembly-xml-specification.xml 18 Nov 2002 14:18:49 -0000 1.1
+++ src/documentation/content/assemblers/assembly-xml-specification.xml 13 Dec 2002 01:48:08 -0000
@@ -1,53 +1,203 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
- <header>
- <title>Specification of assembly.xml </title>
-
- <authors><person name="Peter Donald" email="peter at apache.org"/></authors></header>
- <body>
- <section><title>Introduction</title>
- <p>
- The purpose of the <code>assembly.xml</code> file is to define how the Server
- Application is assembled from it's component Blocks. This requires naming each
- block, specifying the implementation class for each block and wiring together
- blocks. The wiring is done via provides elements. Each provide element maps a
- block instance to a role of a dependency specified in the BlockInfo file. See
- below for a sample assembly.xml file.
- </p>
- <p>
- The <code>assembly.xml</code> can also specify <code>ApplicationListener</code>
- objects that will be created for application. The listeners need a name and
- a classname.
- </p>
- <p>
- In previous versions of Phoenix, configuration data was also stored in the
- assembly file. This is no longer the case (It is now stored in config.xml).
- </p>
- </section>
- <section><title>Sample assembly.xml file</title>
- <source>
+ <header>
+ <title>Specification of assembly.xml </title>
+
+ <authors>
+ <person name="Peter Donald" email="peter at apache.org"/>
+ </authors>
+ </header>
+ <body>
+ <section><title>The Assembly File</title>
+ <p>
+ The <code>assembly.xml</code> file defines how to assemble the
+ application. It defines the blocks that make up the application,
+ and how to connect them together. It also defines the
+ application listeners to include in the application.
+ </p>
+
+ <p>
+ In previous versions of Phoenix, configuration data was also
+ stored in the assembly file. This is no longer the case;
+ Configuration is now stored in a separate
+ <link href="/assemblers/config-xml-specification.html">Configuration File</link>.
+ </p>
+
+ <p>
+ The root element of the assembly file must be an
+ <code><assembly></code> element. The root element
+ must contain a child element for each block and application
+ listener which is part of the application. These elements
+ are described below.
+ </p>
+ </section>
+
+ <section><title>The <block> Element</title>
+ <p>
+ The <code><block></code> element defines a block, and
+ how to provide services to the block. The
+ <code><block></code> element takes the following
+ attributes:
+ </p>
+
+ <table>
+ <tr><th>Attribute</th><th>Description</th></tr>
+ <tr>
+ <td>class</td>
+ <td>
+ The fully-qualified name of the block's implementing class.
+ This class must be public, with a public no-args
+ constructor. There must be a corresponding
+ <link href="/bdg/blockinfo-specification.html">BlockInfo</link>
+ file for the class.
+ </td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>
+ A unique name for the block. This name is used to
+ refer to the block in other parts of the assembly file,
+ and in the configuration file. The block name may
+ only contain letters, digits, '-' and '.'.
+ </td>
+ </tr>
+ </table>
+
+ <section><title>The <provide> Element</title>
+ <p>
+ The <code><provide></code> element defines how to
+ provide a particular service to the block. It connects
+ the block to another block that provides the required service.
+ There must be at least one <code><provide></code>
+ element for each dependency listed in the block's
+ <link href="/bdg/blockinfo-specification.html">BlockInfo</link>
+ file. For array and mapped services, there may be more than
+ one <code><provide></code> element for each
+ dependency. The <code><provide></code> element takes
+ the following attributes:
+ </p>
+
+ <table>
+ <tr><th>Attribute</th><th>Description</th></tr>
+ <tr>
+ <td>alias</td>
+ <td>
+ The key to use for the service, for mapped services.
+ Defaults to the value of the <code>name</code>
+ attribute.
+ </td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>
+ The name of the block to use to provide the service
+ to the target block. This must refer to another
+ block in the same application.
+ </td>
+ </tr>
+ <tr>
+ <td>role</td>
+ <td>
+ The role of the service. This must refer to
+ one of the dependencies listed in the block's
+ BlockInfo file. The service name and version
+ specified by the dependency must match one of the
+ services listed in the provider block's
+ BlockInfo file.
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <section><title>The <proxy> Element</title>
+ <p>
+ The <code><proxy></code> element controls whether
+ Phoenix will wrap the block with a proxy object before
+ supplying it to other blocks. The <code><proxy></code>
+ element takes the following attributes:
+ </p>
+ <table>
+ <tr><th>Attribute</th><th>Description</th></tr>
+ <tr>
+ <td>disable</td>
+ <td>Disables the use of a proxy object. Default is false.</td>
+ </tr>
+ </table>
+ </section>
+ </section>
+
+ <section><title>The <listener> Element</title>
+ <p>
+ The <code><listener></code> element defines an application
+ listener. The <code><listener></code> element takes the
+ following attributes:
+ </p>
+ <table>
+ <tr><th>Attribute</th><th>Description</th></tr>
+ <tr>
+ <td>class</td>
+ <td>
+ The fully qualified name of the listener class.
+ This class must be public and provide a public
+ no-args constructor. It must implement the
+ <code>org.apache.avalon.phoenix.ApplicationListener</code>
+ interface.
+ </td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>
+ A unique name for the listener, which is used to
+ refer to the listener in the configuration file.
+ The name may only contain letters, digits, '-' and '.'.
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <section><title>The <block-listener> Element (Deprecated)</title>
+ <p>
+ The <code><block-listener></code> element defines
+ a block listener. Note that the use of block listeners
+ is deprecated. The <code><block-listener></code> element
+ takes the same attributes as the <code><listener></code>
+ element.
+ </p>
+ </section>
+
+ <section>
+ <title>Sample Assembly File</title>
+ <p>
+ Below is an example assembly file. It defines 2 blocks, called
+ <code>myAuthorizer</code> and <code>myBlock</code>, and a
+ listener. Block <code>myBlock</code> uses the
+ <code>Authorizer</code> service provided by block
+ <code>myAuthorizer</code>.
+ </p>
+
+ <source>
+
<?xml version="1.0"?>
<assembly>
- <listener name="myListener"
- class="com.biz.cornerstone.listeners.MyListener">
- </listener>
-
<block name="myAuthorizer"
class="com.biz.cornerstone.blocks.MyAuthorizer">
</block>
<block name="myBlock"
class="com.biz.cornerstone.blocks.MyBlock">
- <provide name="myAuthorizer"
- role="com.biz.cornerstone.services.Authorizer"/>
+ <provide name="myAuthorizer"
+ role="com.biz.cornerstone.services.Authorizer"/>
</block>
-</assembly>
+ <listener name="myListener"
+ class="com.biz.cornerstone.listeners.MyListener">
+ </listener>
- </source>
- </section>
- </body>
+</assembly>
+ </source>
+ </section>
+ </body>
</document>
Index: src/documentation/content/bdg/blockinfo-specification.xml
===================================================================
RCS file: /home/cvspublic/jakarta-avalon-phoenix/src/documentation/content/bdg/blockinfo-specification.xml,v
retrieving revision 1.1
diff -u -r1.1 blockinfo-specification.xml
--- src/documentation/content/bdg/blockinfo-specification.xml 18 Nov 2002 14:19:01 -0000 1.1
+++ src/documentation/content/bdg/blockinfo-specification.xml 13 Dec 2002 01:48:09 -0000
@@ -1,89 +1,228 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
- <header>
- <title>The BlockInfo Specification</title>
-
- <authors><person name="Peter Donald" email="peter at apache.org"/></authors></header>
- <body>
- <section><title>Block Metadata</title>
- <p>
- The meta-data about each block is stored in a BlockInfo file. The info
- includes details on what version the block is, what <code>Service</code>s
- it depends upon and which <code>Service</code>s it can offer to other Blocks.
- In the future the info will also store such data as the schema for configuring
- the block.
- </p>
-
- <p>
- The BlockInfo file has the same name as the Block except with the extention
- <code>.xinfo</code>. Thus if you were looking up the meta info for a block named
- <code>com.biz.cornerstone.blocks.MyBlock</code> you would look up the resource
- <code>com/biz/cornerstone/blocks/MyBlock.xinfo</code> in the same block jar file that
- the block was packaged in. The BlockInfo file is a simple XML format. An
- example of such a file follows.
- </p>
-
- <source>
+ <header>
+ <title>BlockInfo Specification</title>
+ <authors><person name="Peter Donald" email="peter at apache.org"/></authors></header>
+
+ <body>
+ <section><title>The BlockInfo File</title>
+ <p>
+ The BlockInfo file defines meta-information about a block, such
+ as which services the block depends upon, and which services it
+ can offer to other blocks.
+ </p>
+
+ <p>
+ The BlockInfo file is an XML file. It must be located in the same jar
+ file as the block's implementing class. It must have the same name
+ as the block's class, with the extention <code>.xinfo</code>. Thus,
+ if you were looking up the BlockInfo for a block of class
+ <code>com.biz.cornerstone.blocks.MyBlock</code>, you would look up the
+ resource <code>com/biz/cornerstone/blocks/MyBlock.xinfo</code> in the
+ jar file containing the block.
+ </p>
+
+ <p>
+ Below is an example BlockInfo file:
+ </p>
+ <source>
<?xml version="1.0"?>
<blockinfo>
- <block>
- <version>1.2.3</version>
- </block>
-
- <services>
- <service name="com.biz.cornerstone.services.MyService"
- version="2.1.3" />
- </services>
-
- <dependencies>
- <dependency>
- <role>com.biz.cornerstone.services.Authorizer</role>
- <service name="com.biz.cornerstone.service.Authorizer"
- version="1.2"/>
- </dependency>
- <dependency>
- <!-- note that role is not specified and defaults
- to name of service. The service version is not
- specified and it defaults to "1.0" -->
- <service name="com.biz.cornerstone.service.RoleMapper"/>
- </dependency>
- </dependencies>
+ <block>
+ <version>1.2.3</version>
+ </block>
+
+ <services>
+ <service name="com.biz.cornerstone.services.MyService"
+ version="2.1.3" />
+ </services>
+
+ <dependencies>
+ <dependency>
+ <role>com.biz.cornerstone.services.Authorizer</role>
+ <service name="com.biz.cornerstone.service.Authorizer"
+ version="1.2"/>
+ </dependency>
+ <dependency>
+ <!-- note that role is not specified and defaults
+ to name of service. The service version is not
+ specified and it defaults to "1.0" -->
+ <service name="com.biz.cornerstone.service.RoleMapper"/>
+ </dependency>
+ </dependencies>
</blockinfo>
+ </source>
-
- </source>
- <p>
- You will notice that the information in the BlockInfo file is separated into
- three main sections; <code>block</code>, <code>services</code> and
- <code>dependencies</code>.
- </p>
- <section><title>BlockInfo 'block' Section</title>
- <p>The block section specifies the version of class. In the future this
- section will also specify the configuration schema if the block is
- <code>Configurable</code>.</p>
- </section>
- <section><title>BlockInfo 'services' Section</title>
- <p>The services section documents the services that this block can offer other
- Blocks. The service instances indicate an interface and optionally a version
- (defaults to version 1.0 if not specified). This section is optional and a Block
- can choose to not offer any services.</p>
- </section>
- <section><title>BlockInfo 'dependencies' Section</title>
- <p>The services section documents the services that this block requires to operate.
- Required services are placed in the Blocks ServiceManager under the name
- specified by the <code>role</code> element of dependency. As is documented in the
- <link href="http://jakarta.apache.org/avalon/framework/guide-cop-in-avalon.html">components</link> section, the
- concept of Role is more than just a behavioural contract. A <code>Service</code> is
- a behavioural contract and thus the necessity to support the role element. In most
- cases however the role element and the name attribute of the service will be
- identical. In these cases it is sufficient to just specify service element and role
- will default to name of service.</p>
- </section>
- </section>
- </body>
+ <p>
+ You will notice that the information in the BlockInfo file is separated
+ into three main sections:
+ </p>
+ <ul>
+ <li>The <code><block></code> element, which defines the name and version of the block.</li>
+ <li>The <code><services></code> element, which defines the services the block provides.</li>
+ <li>The <code><dependencies></code> element, which defines the services the block uses.</li>
+ </ul>
+ </section>
+
+ <section><title>The <block> Element</title>
+ <p>
+ The <code><block></code> element specifies the name and version
+ of the block. The <code><block></code> element includes
+ the following nested elements:
+ </p>
+ <table>
+ <tr><th>Element</th><th>Description</th></tr>
+ <tr>
+ <td><code><name></code></td>
+ <td>A descriptive name for the block. Optional.</td>
+ </tr>
+ <tr>
+ <td><code><version></code></td>
+ <td>
+ The version of the block. Must be of the format
+ major.minor.micro, where minor and micro are optional.
+ </td>
+ </tr>
+ <tr>
+ <td><code><schema-type></code></td>
+ <td>
+ The type of configuration schema provided with the block.
+ Possible values depend on the Configuration Validator
+ that Phoenix is using. This value is ignored by the
+ default Configuration Validator. Optional.
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <section><title>The <code><services></code> Element</title>
+ <p>
+ The <code><services></code> element defines the services
+ that the block can offer to other blocks. This element is optional;
+ A block can choose to not offer any services to other blocks.
+ </p>
+ <p>
+ The <code><services></code> element should contain a
+ nested <code><service></code> element for each service
+ that the block provides. The <code><service></code>
+ element takes the following attributes:
+ </p>
+ <table>
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr>
+ <td>name</td>
+ <td>
+ The service name. This is the fully qualified name of
+ the service interface. The block must implement this
+ interface. The service name is also used to identify
+ the service in the BlockInfo files of blocks that use
+ the service (see below).
+ </td>
+ </tr>
+ <tr>
+ <td>version</td>
+ <td>
+ The version of the service. This must be of the form
+ major.minor.micro, where minor and micro are optional.
+ Default value is 1.0.
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <section><title>The <dependencies> Element</title>
+ <p>
+ The <code><dependencies></code> element defines the services
+ that the block requires to operate. Phoenix provides these
+ services to the block using the <code>ServiceManager</code>
+ passed to the block's <code>Serviceable.service()</code> method.
+ </p>
+ <p>
+ The <code><dependencies></code> element should contain
+ a nested <code><dependency></code> element for each
+ service that the block uses. The <code><dependency></code>
+ element takes the following nested elements:
+ </p>
+
+ <section><title>The <service> Element</title>
+ <p>
+ The <code><service></code> element
+ defines the expected service. The service element takes the following
+ attributes:
+ </p>
+ <table>
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr>
+ <td>name</td>
+ <td>
+ The service name. This must be the fully qualified
+ name of the service interface. The object returned
+ by the <code>ServiceManager</code> is guaranteed to
+ be castable to this interface. The service name is
+ also used to identify the service in the BlockInfo
+ file of blocks that provide the service (see above).
+ </td>
+ </tr>
+ <tr>
+ <td>version</td>
+ <td>
+ The expected version of the service. This must be of
+ the form major.minor.micro, where minor and micro are
+ optional. The default value is 1.0.
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <section><title>The <role> Element</title></section>
+ <p>
+ The <code><role></code> element specifies the role that
+ the service plays. This must match the role name that the block
+ supplies when it locates the service using
+ <code>ServiceManager.lookup( role )</code>.
+ The role name is also used in the
+ <link href="/assemblers/assembly-xml-specification.html">Assembly File</link>,
+ to identify the dependency when connecting the block to the
+ services it requires. The <code><role></code> element
+ is optional, and the role name defaults to the service name.
+ </p>
+ </section>
+
+ <section><title>The <management-access-points> Element</title>
+ <p>
+ The <code><management-access-points></code> element
+ defines the management interfaces that the block provides.
+ These interfaces are exported by Phoenix's management system
+ to allow the block to be managed.
+ </p>
+ <p>
+ The <code><management-access-points></code> element must
+ contain a <code><service></code> element for each of the
+ block's management interfaces. The <code><service></code>
+ element takes the following attributes:
+ </p>
+ <table>
+ <tr><th>Name</th><th>Description</th></tr>
+ <tr>
+ <td>name</td>
+ <td>
+ The fully qualified name of the management interface.
+ The block must implement this interface.
+ </td>
+ </tr>
+ <tr>
+ <td>version</td>
+ <td>
+ The version of the management interface. Default value
+ is 1.0
+ </td>
+ </tr>
+ </table>
+ </section>
+ </body>
</document>