mcconnell 2003/08/30 13:43:01
Modified: merlin maven.xml
merlin/merlin-platform/tutorials/dependencies/manual
README.txt
merlin/merlin-platform/xdocs/starting/tutorial
navigation.xml
merlin/merlin-platform/xdocs/starting/tutorial/config
navigation.xml
merlin/merlin-platform/xdocs/starting/tutorial/context
navigation.xml
Added: merlin/merlin-platform/xdocs/starting/tutorial/dependencies
auto.xml index.xml manual.xml navigation.xml
Log:
Updates to the documetation and tutorials to cover automatic and manual dependency
management.
Revision Changes Path
1.49 +1 -1 avalon-sandbox/merlin/maven.xml
Index: maven.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/merlin/maven.xml,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- maven.xml 30 Aug 2003 18:36:54 -0000 1.48
+++ maven.xml 30 Aug 2003 20:43:01 -0000 1.49
@@ -150,8 +150,8 @@
<zipfileset dir="${basedir}/merlin-platform/target/docs" prefix="docs"/>
</ant:zip>
- <ant:echo>Building tutorial kit: ${tutorial.name}.zip</ant:echo>
<j:set var="tutorial.name" value="${maven.final.name}-tutorial-${timestamp}"/>
+ <ant:echo>Building tutorial kit: ${tutorial.name}.zip</ant:echo>
<ant:zip zipfile="${maven.build.dir}/${tutorial.name}.zip">
<zipfileset dir="${basedir}/merlin-platform/target/tutorials"
prefix="tutorial"/>
</ant:zip>
1.2 +3 -3
avalon-sandbox/merlin/merlin-platform/tutorials/dependencies/manual/README.txt
Index: README.txt
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/tutorials/dependencies/manual/README.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- README.txt 28 Aug 2003 17:26:40 -0000 1.1
+++ README.txt 30 Aug 2003 20:43:01 -0000 1.2
@@ -7,13 +7,13 @@
The manual dependencies tutorial covers additional information dealing
with the explict control over dependency binding. In this example we
-have HelloComponent with a dependency on to services of the same type. If we
-depended on class merlin auto-assembly we would not necessarily get the
+have HelloComponent with a dependency on two services of the same type. If we
+depended on classic merlin auto-assembly we would not necessarily get the
desired result. In such a situation, Merlin provides support for
overriding the auto assembly process though explicit dependency directives
included inside a <component/> tag.
-In the block.xml we have three component direectives:
+In the block.xml we have three component directives:
<component name="gloria" class="tutorial.IdentifiableComponent"/>
<component name="nancy" class="tutorial.IdentifiableComponent"/>
1.2 +1 -1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/navigation.xml
Index: navigation.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 10 Jun 2003 02:14:34 -0000 1.1
+++ navigation.xml 30 Aug 2003 20:43:01 -0000 1.2
@@ -23,7 +23,7 @@
<item name="Configurations" href="/starting/tutorial/config/index.html"/>
<item name="Contextualization"
href="/starting/tutorial/context/index.html"/>
<item name="Services" href="/starting/tutorial/services.html"/>
- <item name="Dependencies" href="/starting/tutorial/dependencies.html"/>
+ <item name="Dependencies"
href="/starting/tutorial/dependencies/index.html"/>
</item>
<item name="Advanced Features" href="/starting/advanced/index.html"/>
<item name="Examples" href="/starting/examples/index.html"/>
1.3 +1 -1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/config/navigation.xml
Index: navigation.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/config/navigation.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- navigation.xml 23 Aug 2003 02:23:31 -0000 1.2
+++ navigation.xml 30 Aug 2003 20:43:01 -0000 1.3
@@ -25,7 +25,7 @@
</item>
<item name="Contextualization"
href="/starting/tutorial/context/index.html"/>
<item name="Services" href="/starting/tutorial/services.html"/>
- <item name="Dependencies" href="/starting/tutorial/dependencies.html"/>
+ <item name="Dependencies"
href="/starting/tutorial/dependencies/index.html"/>
</item>
<item name="Advanced Features" href="/starting/advanced/index.html"/>
<item name="Examples" href="/starting/examples/index.html"/>
1.2 +1 -1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/context/navigation.xml
Index: navigation.xml
===================================================================
RCS file:
/home/cvs/avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/context/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 10 Jun 2003 02:14:36 -0000 1.1
+++ navigation.xml 30 Aug 2003 20:43:01 -0000 1.2
@@ -27,7 +27,7 @@
<item name="Context Casting"
href="/starting/tutorial/context/casting.html"/>
</item>
<item name="Services" href="/starting/tutorial/services.html"/>
- <item name="Dependencies" href="/starting/tutorial/dependencies.html"/>
+ <item name="Dependencies"
href="/starting/tutorial/dependencies/index.html"/>
</item>
<item name="Advanced Features" href="/starting/advanced/index.html"/>
<item name="Examples" href="/starting/examples/index.html"/>
1.1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/dependencies/auto.xml
Index: auto.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Service</title>
<authors>
<person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Managing Dependencies">
<p>
A component type can declare dependencies on services provided by
other components. Merlin will ensure that dependencies are resolved
prior to creation of the dependent component. Dependencies are
declared in the component xinfo resource and supplied by Merlin to
the component using the Avalon Serviceable interface.
</p>
<p>
Resource supporting this tutorial are contained in the
turorials/dependencies package.
</p>
</subsection>
<subsection name="Adding a Serviceable method implementation">
<p>
The following code fragment is the implementation of the
Serviceable interface under the HelloComponent.java source.
</p>
<p><i>
Note the use of the @avalon.dependency tag.
</i></p>
<p><i>HelloComponent.java</i></p>
<source>
package tutorial;
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.activity.Initializable;
import org.apache.avalon.framework.activity.Disposable;
/**
* The HelloComponent is dependent on a RandomGenerator service.
* @avalon.component version="1.0" name="simple" lifestyle="singleton"
*/
public class HelloComponent extends AbstractLogEnabled
implements Initializable, Serviceable, Disposable
{
RandomGenerator m_random = null;
Identifiable m_identifiable = null;
/**
* Servicing of the component by the container during
* which service dependencies declared under the component
* can be resolved using the supplied service manager.
*
* @param manager the service manager
* @avalon.dependency type="tutorial.RandomGenerator:1.0"
* key="random"
* @avalon.dependency type="tutorial.Identifiable"
*/
public void service( ServiceManager manager )
throws ServiceException
{
m_random = (RandomGenerator) manager.lookup( "random" );
m_identifiable =
(Identifiable) manager.lookup( Identifiable.class.getName() );
}
public void initialize()
{
getLogger().info( "initialization" );
getLogger().info( "received random value: " + m_random.getRandom() );
getLogger().info( "using identifiable: " + m_identifiable.getIdentity() );
}
public void dispose()
{
getLogger().info( "disposal" );
}
}
</source>
</subsection>
<subsection name="Declaring the service dependency">
<p>
In this example we are automatically generating the xinfo descriptors
using the builtin meta-info generation goal based on the presence of
dependency tags.
</p>
<source><![CDATA[
* @avalon.dependency type="tutorial.RandomGenerator:1.0"
* key="random"
* @avalon.dependency type="tutorial.Identifiable"
]]></source>
<p>
The generated xinfo for the hello component is shown below.
</p>
<p><i>HelloComponent.xinfo</i></p>
<source><![CDATA[
<type>
<info>
<name>simple</name>
<version>1.0.0</version>
<lifestyle>singleton</lifestyle>
</info>
<dependencies>
<dependency key="random" type="tutorial.RandomGenerator" version="1.0.0"/>
<dependency type="tutorial.Identifiable"/>
</dependencies>
</type>
]]></source>
</subsection>
<subsection name="Executing the demo">
<p>
Build and run the tutorial.
</p>
<source>
$ maven
$ merlin target\classes -execute
</source>
<p>
In the logging output we see that Merlin has automatically
locating both RandomGeneratorProvider and IdentifiableComponent
and provided these to the consumer. The HelloComponent
implementation has logged the result of accessing and using
both services.
</p>
<source>
[INFO ] (tutorial.random): initialization
[INFO ] (tutorial.simple): contextualize
[INFO ] (tutorial.hello): initialization
[INFO ] (tutorial.random): processing request
[INFO ] (tutorial.hello): received random value: 359973592
[INFO ] (tutorial.hello): using identifiable: /tutorial/simple
[INFO ] (tutorial.hello): disposal
[INFO ] (tutorial.random): disposal
</source>
</subsection>
<subsection name="Next Topic">
<p>
The <a href="manual.html">next topic</a> shows how you can
override Merlin's automatic dependency resolution by declaring
named suppliers for particular dependencies.
</p>
</subsection>
</section>
</body>
</document>
1.1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/dependencies/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Dependencies</title>
<authors>
<person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Dependency Management">
<table>
<tr><th>Topic</th><th>Summary</th></tr>
<tr>
<td><a href="auto.html">Automatic Dependency Resolution</a></td>
<td>
Updating of the HelloComponent to support dependency declaration
and demonstration of Merlin's assembly support.
</td>
</tr>
<tr>
<td><a href="manual.html">Manual Dependency Declarations</a></td>
<td>
This tutorial shows how you can override Merlin's automatic
assembly system be manaually declaring the association of
suppliers with consumers.
</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>
1.1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/dependencies/manual.xml
Index: manual.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Service</title>
<authors>
<person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Managing Dependencies - Manual Association">
<p>
The manual dependencies tutorial covers additional information dealing
with the explict control over dependency binding. In this example we
have HelloComponent with a dependency on two services of the same type. If we
depended on classic merlin auto-assembly we would not necessarily get the
desired result. In such a situation, Merlin provides support for
overriding the auto assembly process though explicit dependency directives
included inside a <component/> tag.
</p>
<p>
In the block.xml we have three component directives:
</p>
<source><![CDATA[
<component name="gloria" class="tutorial.IdentifiableComponent"/>
<component name="nancy" class="tutorial.IdentifiableComponent"/>
<component name="hello" class="tutorial.HelloComponent">
<dependencies>
<dependency key="primary" source="gloria"/>
<dependency key="secondary" source="nancy"/>
</dependencies>
</component>
]]></source>
<p>
The "hello" component has been manually wired together using named components
references under a set of <dependency/> directives, thereby overriding Merlin
auto-assembly huristics.
</p>
</subsection>
<subsection name="Executing the demo">
<p>
Build and run the tutorial.
</p>
<source>
$ maven
$ merlin target\classes -execute
</source>
<p>
In the logging output we see that Merlin has established and
and assigned the components we requested based on our directives
in the block.xml file.
</p>
<source>
[INFO ] (tutorial.nancy): contextualize
[INFO ] (tutorial.gloria): contextualize
[INFO ] (tutorial.hello): initialization
[INFO ] (tutorial.hello): assigned primary: /tutorial/gloria
[INFO ] (tutorial.hello): assigned secondary: /tutorial/nancy
</source>
</subsection>
<subsection name="Advanced Features">
<p>
This completes the introduction to some of the basic features
of the merlin platform. More tutorials will be added so please check
for new releases and updates. In the meantime you may want to take a
look at some of Merlin's more <a href="../advanced/index.html">advanced
features</a>.
</p>
</subsection>
</section>
</body>
</document>
1.1
avalon-sandbox/merlin/merlin-platform/xdocs/starting/tutorial/dependencies/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<project>
<title>Merlin</title>
<body>
<links>
<item name="Home" href="http://avalon.apache.org/"/>
<item name="Framework" href="http://avalon.apache.org/framework/"/>
<item name="Components" href="http://avalon.apache.org/components"/>
<item name="Containers" href="http://avalon.apache.org/containers/"/>
<item name="Sandbox" href="http://avalon.apache.org/sandbox/"/>
</links>
<menu name="About Merlin">
<item name="Overview" href="/about/index.html"/>
<item name="Getting Started" href="/starting/index.html">
<item name="Installation" href="/starting/installation.html"/>
<item name="Using Merlin" href="/starting/tutorial/index.html">
<item name="Hello Block" href="/starting/tutorial/creation.html"/>
<item name="Running Hello" href="/starting/tutorial/execution.html"/>
<item name="Behind the Scenes" href="/starting/tutorial/internal.html"/>
<item name="Configurations" href="/starting/tutorial/config/index.html"/>
<item name="Contextualization"
href="/starting/tutorial/context/index.html"/>
<item name="Services" href="/starting/tutorial/services.html"/>
<item name="Dependencies"
href="/starting/tutorial/dependencies/index.html">
<item name="Auto" href="/starting/tutorial/dependencies/auto.html"/>
<item name="Manual" href="/starting/tutorial/dependencies/manual.html"/>
</item>
</item>
<item name="Advanced Features" href="/starting/advanced/index.html"/>
<item name="Examples" href="/starting/examples/index.html"/>
</item>
<item name="Merlin System" href="/merlin/index.html"/>
<item name="Meta Model" href="/meta/index.html"/>
<item name="Tools" href="/tools/index.html"/>
<item name="Resources" href="/resources/index.html"/>
</menu>
<menu name="Extensions">
<item name="JNDI" href="/extensions/jndi/index.html"/>
<item name="Servlet" href="/extensions/servlet/index.html"/>
</menu>
</body>
</project>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
