mcconnell 2003/06/16 02:39:06
Modified: merlin/merlin-platform/xdocs/resources notebook.xml
roadmap.xml
merlin/merlin-platform/xdocs/starting index.xml
installation.xml
merlin/merlin-platform/xdocs/starting/advanced includes.xml
profiles.xml
merlin/merlin-platform/xdocs/tools ant.xml
merlin/merlin-platform/xdocs/tools/maven meta.xml
Log:
General documentation updates.
Revision Changes Path
1.4 +76 -0
avalon-sandbox/merlin/merlin-platform/xdocs/resources/notebook.xml
Index: notebook.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/resources/notebook.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- notebook.xml 15 Jun 2003 17:43:24 -0000 1.3
+++ notebook.xml 16 Jun 2003 09:39:05 -0000 1.4
@@ -16,6 +16,82 @@
</p>
</subsection>
+
+ <subsection name="Release Preparation">
+
+<p>
+Over the last few months the level of interest and activity in Merlin has been
growing. In addition I have received several requests for a release of Merlin by
people that want to get involved but really need a release before jumping in.
+</p>
+
+<p>Doing a release has several benefits:</p>
+
+ <ul>
+ <li>will facilitate broader feedback from users</li>
+ <li>will facilitate the expansion of the development community</li>
+ <li>will enable classic binary downloads for people without CVS access</li>
+ </ul>
+
+<p>
+Some of the actions that should be taken before a release include the following:
+</p>
+
+ <table>
+ <tr><th>Action</th><th>Status</th></tr>
+ <tr><td>custom contextualization tutorials</td><td>DONE</td></tr>
+ <tr>
+ <td>add documentation concerning the Merlin/Maven plugin</td>
+ <td>DONE</td>
+ </tr>
+ <tr>
+ <td>documentation on configuration/categories targets</td>
+ <td>DONE</td>
+ </tr>
+ <tr>
+ <td>provide solution for the a manifest generation problem that
+ is currently preventing the proper management of
+ extensions</td><td>DONE
+ </td>
+ </tr>
+ <tr>
+ <td>enable meta-info generation tool to switch between xinfo
+ and xtype</td>
+ <td>DONE</td>
+ </tr>
+ <tr>
+ <td>
+ document the repository and relationship to the classloader
+ and include resource tags
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>tutorial on logging categories management</td>
+ <td></td>
+ </tr>
+ <tr><td>dynamic components tutorials</td><td></td></tr>
+ <tr>
+ <td>complete the documentation about the James example
+ (this needs to cover the relationships between types, services,
+ packaged and explicit profiles, blocks, includes, and
+ targets).
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>either release Excalibur Extension or include a fork
+ under the Merlin project</td>
+ <td></td>
+ </tr>
+ <tr><td>test and validation</td><td>ONGOING</td></tr>
+ <tr><td>tag the CVS</td><td></td></tr>
+ <tr><td>vote on a release</td><td></td></tr>
+ </table>
+ </subsection>
+ <subsection name="Voluntees">
+<p>
+Any volunteers out there willing to help with release preparation - please post a
note to the avalon dev or users list. Help can be in all sorts of areas - validating
documentation, packaging, testing, etc.
+</p>
+ </subsection>
</section>
</body>
1.4 +0 -50
avalon-sandbox/merlin/merlin-platform/xdocs/resources/roadmap.xml
Index: roadmap.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/resources/roadmap.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- roadmap.xml 15 Jun 2003 17:43:24 -0000 1.3
+++ roadmap.xml 16 Jun 2003 09:39:05 -0000 1.4
@@ -9,50 +9,6 @@
<body>
<section name="Roadmap">
- <subsection name="Release Preparation">
-
-<p>
-Over the last few months the level of interest and activity in Merlin has been
growing. In addition I have received several requests for a release of Merlin by
people that want to get involved but really need a release before jumping in.
-</p>
-
-<p>Doing a release has several benefits:</p>
-
- <ul>
- <li>will facilitate broader feedback from users</li>
- <li>will facilitate the expansion of the development community</li>
- <li>will enable classic binary downloads for people without CVS access</li>
- </ul>
-
-<p>
-Some of the actions that should be taken before a release include the following:
-</p>
-
- <table>
- <tr><th>Action</th><th>Status</th></tr>
- <tr><td>custom contextualization tutorials</td><td>DONE</td></tr>
- <tr><td>dynamic components tutorials</td><td>PENDING</td></tr>
- <tr><td>complete the documentation about the James
example</td><td>PENDING</td></tr>
- <tr>
- <td>add documentation concerning the Merlin/Maven plugin</td>
- <td>DONE</td>
- </tr>
- <tr>
- <td>provide solution for the a manifest generation problem that
- is currently preventing the proper management of
- extensions</td><td>DONE
- </td>
- </tr>
- <tr>
- <td>either release Excalibur Extension or include a fork
- under the Merlin project</td>
- <td>PENDING</td>
- </tr>
- <tr><td>test and validation</td><td>ONGOING</td></tr>
- <tr><td>tag the CVS</td><td>PENDING</td></tr>
- <tr><td>vote on a release</td><td>PENDING</td></tr>
- </table>
- </subsection>
-
<subsection name="Priority Development Areas">
<table>
<tr>
@@ -81,12 +37,6 @@
<td>Repository Chaining</td><td>Maven style repository chains.</td>
</tr>
</table>
- </subsection>
-
- <subsection name="Voluntees">
-<p>
-Any volunteers out there willing to help with release preparation - please post a
note to the avalon dev or users list. Help can be in all sorts of areas - validating
documentation, packaging, testing, etc.
-</p>
</subsection>
</section>
1.2 +1 -1 avalon-sandbox/merlin/merlin-platform/xdocs/starting/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/starting/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 10 Jun 2003 02:14:25 -0000 1.1
+++ index.xml 16 Jun 2003 09:39:05 -0000 1.2
@@ -16,7 +16,7 @@
<td>Installation instructions including build and verification
procedures.</td>
</tr>
<tr>
- <td><a href="hello/index.html">Using Merlin</a></td>
+ <td><a href="tutorial/index.html">Using Merlin</a></td>
<td>
A short introduction to using Merlin based on a Hello Block example that takes your
though the definition of a block, subsequent deployment, and general aspects
concerning configuration, contextualization, service publication, and service
dependency management.
</td>
1.2 +1 -1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/installation.xml
Index: installation.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/starting/installation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- installation.xml 10 Jun 2003 02:14:25 -0000 1.1
+++ installation.xml 16 Jun 2003 09:39:05 -0000 1.2
@@ -107,7 +107,7 @@
<subsection name="Next Steps">
<p>
Now that you have installed Merlin on your system you can
- proceed to the <a href="./hello/index.html">Using Merlin</a>
+ proceed to the <a href="./tutorial/index.html">Using Merlin</a>
tutorial page.
</p>
</subsection>
1.2 +81 -27
avalon-sandbox/merlin/merlin-platform/xdocs/starting/advanced/includes.xml
Index: includes.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/starting/advanced/includes.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- includes.xml 10 Jun 2003 02:14:27 -0000 1.1
+++ includes.xml 16 Jun 2003 09:39:05 -0000 1.2
@@ -26,11 +26,12 @@
The following block defintion contains:
</p>
<ul>
- <li><p>a component named test1 at the root container level</p></li>
+ <li><p>inclusion of a block named "my-block" containing
+ embedded configuration and logging category overrides</p></li>
<li><p>a container named 'subcontainer', containing:</p>
<ul>
<li>a component</li>
- <li>an include with a supplied configuration directive</li>
+ <li>an include with a external target configuration directive</li>
<li>another include that contains other includes</li>
</ul>
</li>
@@ -52,16 +53,56 @@
</classpath>
</engine>
- <component name="test1" class="tutorial.TestComponent" activation="startup">
- <configuration>
- <source>configuration from block directive</source>
- </configuration>
- </component>
+ <component name="test1" class="tutorial.TestComponent" activation="startup"/>
+
+ <!--
+ Deomonstration of an include the establishes a subsidiary block named
"my-block"
+ based on the block defintion "include.xml". The directives in the included
+ block are qualified by the configuration targets embedded in the targets
+ element.
+ -->
+ <include name="my-block">
+ <source path="include.xml"/>
+ <targets>
+
+ <!--
+ A target itentifies a component relative to the containing block.
+ For example, the following target is referencing a component
+ named "test3" contained with the block "my-block". The target
+ contains a different configuration and an overriding logging
+ category default priority for the component.
+ -->
+
+ <target path="/test3">
+ <configuration>
+ <source>embedded target configuration</source>
+ </configuration>
+ <categories priority="DEBUG"/>
+ </target>
+ </targets>
+ </include>
<container name="subcontainer">
- <component name="test2" class="tutorial.TestComponent" activation="startup"/>
- <include path="include.xml" config="include-config.xml"/>
- <include path="composite.xml"/>
+
+ <component name="test2" class="tutorial.TestComponent"
+ activation="startup"/>
+
+ <!--
+ The following include demonstrates the importing of a
+ target override file from an external source into a
+ container. The imported block will be establish
+ as a child of the containing block.
+ -->
+
+ <include name="include">
+ <source path="include.xml"/>
+ <targets path="include-config.xml"/>
+ </include>
+
+ <include name="composite">
+ <source path="composite.xml"/>
+ </include>
+
</container>
</implementation>
@@ -69,15 +110,19 @@
</block>
]]></source>
<p>
- The above block.xml will create a component hierachy equivalent to the
- following:
+ The above block.xml will create a component hierachy
+ equivalent to the following:
</p>
<source>
test1
+my-block
+my-block.test3
+subcontainer
subcontainer.test2
-subcontainer.inclusion.test2
-subcontainer.composite.test.inclusion.test3
-subcontainer.composite.inclusion.test3
+subcontainer.include
+subcontainer.include.test3
+subcontainer.composite.test.nested
+subcontainer.composite.test.nested.test3
</source>
</subsection>
<subsection name="Sample Configuration">
@@ -91,11 +136,13 @@
<targets>
<!-- classic target configuration override declarations -->
+
<target path="/test1">
<configuration>
<source>config.xml</source>
</configuration>
</target>
+
<target path="/subcontainer/test2">
<configuration>
<source>config.xml</source>
@@ -103,16 +150,10 @@
</target>
<!-- this target will override the config referenced in the include -->
- <target path="/subcontainer/composite/inclusion/test3">
- <configuration>
- <source>config.xml</source>
- </configuration>
- </target>
- <!-- this target sets the configuration on another include -->
- <target path="/subcontainer/inclusion/test3">
+ <target path="/subcontainer/include/test3">
<configuration>
- <source>config.xml</source>
+ <source>using config.xml file</source>
</configuration>
</target>
@@ -137,12 +178,25 @@
components in the assembly.
</p>
<source><![CDATA[
+[INFO ] (sys): initialization: localhost
+[INFO ] (sys): commencing block assembly phase
[INFO ] (test1): source: config.xml
+[INFO ] (sys): Block hierarchy established.
+[INFO ] (sys): commencing decommissioning phase
+[DEBUG ] (my-block.test3): configuration
+[INFO ] (my-block.test3): source: embedded target configuration
+[INFO ] (my-block): container initialization: my-block
[INFO ] (subcontainer.test2): source: config.xml
-[INFO ] (subcontainer.inclusion.test3): source: config.xml
-[INFO ] (subcontainer.composite.test.inclusion.test3): source: include-config.xml
-[INFO ] (subcontainer.composite.inclusion.test3): source: config.xml
-]]></source>
+[INFO ] (subcontainer.include.test3): source: the include-config.xml file
+[INFO ] (subcontainer): container initialization: subcontainer
+[INFO ] (subcontainer.include): container initialization: include
+[INFO ] (subcontainer.composite): container initialization: composite
+[INFO ] (subcontainer.composite.test): container initialization: test
+[INFO ] (subcontainer.composite.test.nested.test3): source: embedded target
+ in a nested include
+[INFO ] (subcontainer.composite.test.nested): container initialization:
+ nested
+[INFO ] (sys): bye]]></source>
</subsection>
</section>
</body>
1.2 +1 -1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/advanced/profiles.xml
Index: profiles.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/starting/advanced/profiles.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- profiles.xml 10 Jun 2003 02:14:28 -0000 1.1
+++ profiles.xml 16 Jun 2003 09:39:05 -0000 1.2
@@ -19,7 +19,7 @@
</subsection>
<subsection name="Creating a Profile">
<p>
-This tutorial extends the interfaces, classes and meta info declared in the <a
href="../hello/dependencies.html">dependencies tutorial</a> by adding a configurable
seed value to the RandomGenerator component. Without the benefit of a profile, users
would be forced to declare a configuration under the block.xml directive. By providing
one or more profiles, we enable Merlin to automatically select a deployment scenario
candidate and use this during the assembly phase.
+This tutorial extends the interfaces, classes and meta info declared in the <a
href="../tutorial/dependencies.html">dependencies tutorial</a> by adding a
configurable seed value to the RandomGenerator component. Without the benefit of a
profile, users would be forced to declare a configuration under the block.xml
directive. By providing one or more profiles, we enable Merlin to automatically select
a deployment scenario candidate and use this during the assembly phase.
</p>
<p>
The RandomGeneratorProvider source and the corresponding profile directive are
presented below.
1.2 +4 -0 avalon-sandbox/merlin/merlin-platform/xdocs/tools/ant.xml
Index: ant.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/tools/ant.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ant.xml 10 Jun 2003 02:14:37 -0000 1.1
+++ ant.xml 16 Jun 2003 09:39:05 -0000 1.2
@@ -28,6 +28,10 @@
<td>force</td><td>false</td>
<td>A boolean flag to force regenerating of the meta-files.
<strong>false</strong> (default) will generate the meta-file if the source is newer
than the exisiting meta-file or if the meta-file does not exist. <strong>true</strong>
will overwrite any existing meta-file irrespective of the modification date.</td>
</tr>
+ <tr>
+ <td>postfix</td><td>false</td>
+ <td>Select between "xinfo" and "xtype" as the meta-info file type that is
generated. The xtype postfix is convinient when generating meta info descriptors that
must cooexist with the Phoenix platform.</td>
+ </tr>
</table>
</subsection>
<subsection name="Nested Elements">
1.2 +41 -2 avalon-sandbox/merlin/merlin-platform/xdocs/tools/maven/meta.xml
Index: meta.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/tools/maven/meta.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- meta.xml 10 Jun 2003 05:10:42 -0000 1.1
+++ meta.xml 16 Jun 2003 09:39:06 -0000 1.2
@@ -51,8 +51,7 @@
<resource>
<directory>${basedir}/target/src</directory>
<includes>
- <include>**/*.xinfo</include>
- <include>**/*.xservice</include>
+ <include>**/*.x*</include>
</includes>
</resource>
</resources>
@@ -79,6 +78,12 @@
in an XML format whereas the 'serial' value generates a serialized
description of the descriptor. Serial format is more efficient. The
XML format is more portable.</p>
+<p>
+Default behaviour:
+</p>
+<source><![CDATA[
+merlin.meta.format="xml"
+]]></source>
</td>
</tr>
<tr>
@@ -87,6 +92,40 @@
<td>
<p>Policy controlling the regeneration of meta descriptors independently
of the descriptor data. This value default to false. </p>
+<p>
+Default behaviour:
+</p>
+<source><![CDATA[
+merlin.meta.force="false"
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>merlin.meta.type.postfix</td>
+ <td>No</td>
+ <td>
+<p>
+Merlin will default to the deneration of XML type descriptors under
+the .xinfo file type. When generating meta-info descriptors targetted
+for deployment in both Merlin and Phoenix, the xinfo type will conflict
+with the Phoenix meta-info descriptor. Merlin provides support for
+generation of meta info under the alternative .xtype. To control the
+type of file generated, you can declare either "xinfo" or "xtype" under
+this property.
+</p>
+<p>
+Default behaviour:
+</p>
+<source><![CDATA[
+merlin.meta.type.postfix="xinfo"
+]]></source>
+<p>
+Alternative xtype behaviour:
+</p>
+<source><![CDATA[
+merlin.meta.type.postfix="xtype"
+]]></source>
+
</td>
</tr>
</table>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
