mcconnell 2003/03/29 21:27:49
Modified: merlin/merlin-smp maven.xml
merlin/merlin-smp/xdocs/tools ant.xml maven.xml
Log:
Updating documentation to include tools information (Ant, Maven, Taglibs).
Revision Changes Path
1.2 +0 -1 avalon-sandbox/merlin/merlin-smp/maven.xml
Index: maven.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/maven.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- maven.xml 13 Mar 2003 01:05:23 -0000 1.1
+++ maven.xml 30 Mar 2003 05:27:49 -0000 1.2
@@ -5,7 +5,6 @@
<property name="maven.javadoc.stylesheet"
value="${basedir}/src/etc/stylesheet.css"/>
-
<preGoal name="site">
<attainGoal name="license"/>
</preGoal>
1.2 +138 -1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/ant.xml
Index: ant.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/tools/ant.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ant.xml 29 Mar 2003 13:37:14 -0000 1.1
+++ ant.xml 30 Mar 2003 05:27:49 -0000 1.2
@@ -8,8 +8,145 @@
<body>
<section name="Introduction">
<p>
-Information comming.
+The mata info generator task scans sources files for the present of an avalon.meta
tags and based on the tag set specification, generates either XML or serialized
meta-info descriptors.
</p>
+
+ <subsection name="Parameters">
+<table>
+ <tr>
+ <th>Parameter</th><th>Required</th><th>Value</th>
+ </tr>
+ <tr>
+ <td>destDir</td><td>true</td>
+ <td>The directory into which the generated type and service defintions wil be
created.</td>
+ </tr>
+ <tr>
+ <td>format</td><td>false</td>
+ <td>The output format. May be one of <strong>xml</strong> or
<strong>serial</strong>. The xml format is less compact but more portable. The
serial format is appropriate when usage is know to be in the context of the Avalon
Meta API. The serial format is a serialized representation of the corresponding Task
or Service instance.</td>
+ </tr>
+</table>
+ </subsection>
+ <subsection name="Nested Elements">
+<table>
+ <tr>
+ <th>Element</th><th>Required</th><th>Value</th>
+ </tr>
+ <tr>
+ <td>fileset</td><td>true</td>
+ <td>A fileset containing the defintion of the source files to be included in
the scanning phase.</td>
+ </tr>
+</table>
+ </subsection>
+
+ <subsection name="Ant Example">
+<source><![CDATA[
+ <target name="meta" description="Generates the XML descriptors" depends="build">
+ <mkdir dir="${meta.dir}" />
+ <taskdef name="meta" classname="org.apache.avalon.meta.tools.ant.MetaTask">
+ <classpath refid="project.class.path" />
+ </taskdef>
+ <meta destDir="${meta.dir}" format="xml">
+ <fileset dir="${src}">
+ <include name="**/*.java"/>
+ </fileset>
+ </meta>
+ </target>
+]]></source>
+ </subsection>
+ </section>
+ <section name="Example">
+ <subsection name="Java source with Tag markup">
+<source><![CDATA[
+
+import java.io.File;
+
+import org.apache.avalon.framework.logger.Logger;
+import org.apache.avalon.framework.logger.AbstractLogEnabled;
+import org.apache.avalon.framework.service.Serviceable;
+import org.apache.avalon.framework.service.ServiceManager;
+import org.apache.avalon.framework.service.ServiceException;
+import org.apache.avalon.framework.context.Context;
+import org.apache.avalon.framework.context.Contextualizable;
+import org.apache.avalon.framework.context.ContextException;
+
+/**
+ * An example component containing meta info under javadoc tags.
+ *
+ * @avalon.meta.name secondary-component
+ * @avalon.meta.version 2.4
+ * @avalon.meta.service type="SecondaryService:0.1"
+ * @avalon.meta.lifestyle singleton
+ */
+public class Secondary extends AbstractLogEnabled
+ implements Serviceable, SecondaryService, Contextualizable
+{
+ private Logger m_system = null;
+ private File m_home = null;
+ private PrimaryService m_primary = null;
+
+ /**
+ * Supply of a logging channel to the component.
+ * @param logger the logging channel
+ * @avalon.meta.logger name="system"
+ */
+ public void enableLogging( Logger logger )
+ {
+ super.enableLogging( logger );
+ m_system = logger.getChildLogger( "system" );
+ }
+
+ /**
+ * Supply of the runtime context by the container.
+ * @param context the runtime context
+ * @avalon.meta.entry key="home" type="java.io.File"
+ */
+ public void contextualize( Context context ) throws ContextException
+ {
+ m_home = (File) context.get("home");
+ }
+
+ /**
+ * Supply of dependent services to this component by the container.
+ * @param manager the service manager
+ * @avalon.meta.dependency type="PrimaryService:1.3" key="primary"
+ */
+ public void service( ServiceManager manager ) throws ServiceException
+ {
+ m_primary = (PrimaryService) manager.lookup( "primary" );
+ m_system.info( "resolved primary service reference" );
+ }
+}
+]]></source>
+ </subsection>
+ <subsection name="Generated meta-info descriptor">
+<source><![CDATA[
+<?xml version="1.0" ?>
+<!DOCTYPE type PUBLIC "-//AVALON/Type DTD Version 1.0//EN"
+ "http://avalon.apache.org/dtds/meta/type_1_1.dtd"; >
+
+<type>
+ <info>
+ <name>secondary-component</name>
+ <version>2.4.0</version>
+ <attributes>
+ <attribute name="urn:avalon:lifestyle" value="singleton"/>
+ </attributes>
+ </info>
+ <loggers>
+ <logger name="system"/>
+ </loggers>
+ <context>
+ <entry key="home" type="java.io.File"/>
+ </context>
+ <services>
+ <service type="SecondaryService:0.1.0"/>
+ </services>
+ <dependencies>
+ <dependency key="primary" type="PrimaryService:1.3.0"/>
+ </dependencies>
+</type>
+]]></source>
+ </subsection>
</section>
</body>
</document>
1.2 +82 -1 avalon-sandbox/merlin/merlin-smp/xdocs/tools/maven.xml
Index: maven.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/tools/maven.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- maven.xml 29 Mar 2003 13:37:14 -0000 1.1
+++ maven.xml 30 Mar 2003 05:27:49 -0000 1.2
@@ -8,8 +8,89 @@
<body>
<section name="Introduction">
<p>
-Information comming.
+The Merlin Plugin for Maven provides support for developers in the management of
Maven based projects that leverage the Avalon component model. This plugin wil be
progressively extended with Merlin and related sub-system utilities. Currently the
plugin provides support for a meta info generation process based on javadoc tags
within class and interface source files.
</p>
+ </section>
+ <section name="Plugin Specification">
+ <subsection name="Goals">
+ <table>
+ <tr><th>Goal</th><th>Description</th></tr>
+ <tr>
+ <td>merlin:meta</td>
+ <td>
+ <p>Generates meta info descriptors for service and component types
+ based on javadoc tags within the java source files. Source files
+ are scanned for the presence of an @avalon.version tag and if
+ present, a meta descriptor is generated. If the version tag is
+ within an interface defintion, a new Service defintion is created
+ otherwise a Type defintion is created.</p>
+
+ <p>Meta info generation process includes:</p>
+ <ul>
+ <li>Scan source files for avalon.meta tags</li>
+ <li>Build Type and Service descriptors</li>
+ <li>Externalize descriptors to serial or xml format</li>
+ </ul>
+ <p>Resulting meta info descriptors are placed int the
${basedir}/target/src directory. Typical application scenario is to define a preGoal
to handle meta-info generation under the maven.xml file and inclusion of the output
meta info under the project.xml jar resources.</p>
+<p><i>maven.xml example</i></p>
+<source><![CDATA[
+ <project default="java:jar">
+ <preGoal name="java:jar">
+ <attainGoal name="merlin:meta"/>
+ </preGoal>
+ </project>
+]]></source>
+<p><i>project.xml example</i></p>
+<source><![CDATA[
+ <project>
+ <!-- other stuff -->
+ <build>
+ <!-- more stuff -->
+ <resources>
+ <!-- include the generated metainfo descriptors into you jar file -->
+ <resource>
+ <directory>${basedir}/target/src</directory>
+ <includes>
+ <include>**/*.xinfo</include>
+ <include>**/*.xservice</include>
+ </includes>
+ </resource>
+ </resources>
+ </build>
+ </project>
+]]></source>
+ </td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="Properties">
+ <table>
+ <tr>
+ <th>Property name</th>
+ <th>Optional?</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>merlin.meta.format</td>
+ <td>Yes</td>
+ <td>
+<p>Output format specification. Valid values include 'xml' or 'serial'.
+The xml value instructs the meta generator to create meta descriptions
+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>
+ </td>
+ </tr>
+ <tr>
+ <td>merlin.meta.force</td>
+ <td>Yes</td>
+ <td>
+<p>Policy controlling the regeneration of meta descriptors independently
+of the descriptor data. This value default to false. </p>
+ </td>
+ </tr>
+ </table>
+ </subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
