You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by mc...@apache.org on 2003/04/04 00:12:59 UTC
cvs commit: avalon-sandbox/merlin/merlin-smp/xdocs/starting/hello/context standard.xml stage.xml navigation.xml index.xml entries.xml casting.xml
mcconnell 2003/04/03 14:12:59
Added: merlin/merlin-smp/xdocs/starting/hello/context standard.xml
stage.xml navigation.xml index.xml entries.xml
casting.xml
Log:
Initial commit of placeholder documents for context management tutorials.
Revision Changes Path
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/starting/hello/context/standard.xml
Index: standard.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Contextualization</title>
<authors>
<person name="Stephen McConnell" email="mcconnell@apache.org"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Managing Configurations">
<p>
This tutorial presents information about the management
of the runtime context supplied to your component.
</p>
<p>
Resource supporting this tutorial are contained in the
turorial/003 package.
</p>
</subsection>
<subsection name="Adding context support to the component">
<p>
In order to receive a runtime context we need to update the
HelloComponent source so that it implements the Avalon
Contextualization stage interface. Merlin will build and
supply a context object containing the following four
context entries:
</p>
<p><i>Merlin Standard Context Entries</i></p>
<table>
<tr>
<th>Key</th><th>Class</th><th>Description</th>
</tr>
<tr>
<td>urn:avalon:home</td><td>java.io.File</td><td>The working directory.</td>
</tr>
<tr>
<td>urn:avalon:work</td><td>java.io.File</td><td>The temporary directory.</td>
</tr>
<tr>
<td>urn:avalon:name</td><td>java.io.File</td><td>The component name.</td>
</tr>
<tr>
<td>urn:avalon:partition</td><td>java.lang.String</td>
<td>The assigned partition name.</td>
</tr>
</table>
<source>
package tutorial;
import org.apache.avalon.framework.logger.AbstractLogEnabled;
import org.apache.avalon.framework.activity.Initializable;
import org.apache.avalon.framework.configuration.Configurable;
import org.apache.avalon.framework.configuration.Configuration;
import org.apache.avalon.framework.configuration.ConfigurationException;
public class HelloComponent extends AbstractLogEnabled
implements Configurable, Initializable
{
private String m_source = "undefined";
/**
* Configuration of the component by the container. The
* implementation get a child element named 'source' and
* assigns the value of the element to a local variable.
*
* @param config the component configuration
* @exception ConfigurationException if a configuration error occurs
*/
public void configure( Configuration config ) throws ConfigurationException
{
getLogger().info( "configuration stage" );
m_source = config.getChild( "source" ).getValue( "unknown" );
}
/**
* Initialization of the component by the container.
* @exception Exception if an initialization error occurs
*/
public void initialize() throws Exception
{
getLogger().info( "initialization stage" );
final String message =
"source: " + m_source;
getLogger().info( message );
}
}
</source>
<p>
Build and run the tutorial without declaring any configuration.
</p>
<source>
$ ant jar
$ merlin build\classes
</source>
<p>
In the logging output we see that Merlin has created and
supplied an empty configuration to the component.
</p>
<source>
$ ant jar
$ merlin build\classes
[INFO ] (tutorial.hello): configuration stage
[INFO ] (tutorial.hello): initialization stage
[INFO ] (tutorial.hello): source: unknown
</source>
</subsection>
</section>
</body>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/starting/hello/context/stage.xml
Index: stage.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Contextualization</title>
<authors>
<person name="Stephen McConnell" email="mcconnell@apache.org"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Custom Contextualization">
<p>
This tutorial presents information about the declaration
and implementation of a custom contextualization stage
handler.
</p>
<p>
Resource supporting this tutorial are contained in the
turorial/xxx package.
</p>
</subsection>
</section>
</body>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/starting/hello/context/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<project>
<title>Merlin</title>
<body>
<links>
<item name="Avalon" href="http://avalon.apache.org/"/>
<item name="Excalibur" href="http://avalon.apache.org/excalibur"/>
</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/hello/index.html">
<item name="Hello Block" href="/starting/hello/creation.html"/>
<item name="Running Hello" href="/starting/hello/execution.html"/>
<item name="Behind the Scenes" href="/starting/hello/internal.html"/>
<item name="Configurations" href="/starting/hello/config.html"/>
<item name="Contextualization" href="/starting/hello/context/index.html">
<item name="Standard Entries" href="/starting/hello/context/standard.html"/>
<item name="Custom Entries" href="/starting/hello/context/entries.html"/>
<item name="Context Casting" href="/starting/hello/context/types.html"/>
<item name="Custom Contextualization" href="/starting/hello/context/stage.html"/>
</item>
<item name="Managing Dependencies" href="/starting/hello/dependencies.html"/>
<item name="Publishing Services" href="/starting/hello/services.html"/>
</item>
<item name="Advanced Features" href="/starting/advanced/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"/>
</menu>
<menu name="Extensions">
<item name="JNDI" href="/extensions/jndi/index.html"/>
</menu>
</body>
</project>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/starting/hello/context/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Context</title>
<authors>
<person name="Stephen McConnell" email="mcconnell@apache.org"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Context Management">
<table>
<tr><th>Topic</th><th>Summary</th></tr>
<tr>
<td><a href="standard.html">Standard Context Entries</a></td>
<td>
Updating of the HelloComponent to support contextualization
and an overview of the standard context entries provided by
Merlin to a component.
</td>
</tr>
<tr>
<td><a href="entries.html">Custom Entries</a></td>
<td>
Declaration of the custom context entry requirements
and the mechanisms used to construct and supply
corresponding context entry values.
</td>
</tr>
<tr>
<td><a href="casting.html">Casting Context</a></td>
<td>
Examples of how you use domain specific context
specializations and safely cast the supplied context
instance.
</td>
</tr>
<tr>
<td><a href="stage.html">Custom Contextualization</a></td>
<td>
Building and deploying a completly custom contextaulization
stage.
</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/starting/hello/context/entries.xml
Index: entries.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Contextualization</title>
<authors>
<person name="Stephen McConnell" email="mcconnell@apache.org"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Managing Configurations">
<p>
This tutorial presents information about the management
of the runtime context supplied to your component.
</p>
<p>
Resource supporting this tutorial are contained in the
turorial/003 package.
</p>
</subsection>
<subsection name="Adding context support to the component">
<p>
In order to receive a runtime context we need to update the
HelloComponent source so that it implements the Avalon
Contextualization stage interface. Merlin will build and
supply a context object containing the following four
context entries:
</p>
<p><i>Merlin Standard Context Entries</i></p>
<table>
<tr>
<th>Key</th><th>Class</th><th>Description</th>
</tr>
<tr>
<td>urn:avalon:home</td><td>java.io.File</td><td>The working directory.</td>
</tr>
<tr>
<td>urn:avalon:work</td><td>java.io.File</td><td>The temporary directory.</td>
</tr>
<tr>
<td>urn:avalon:name</td><td>java.io.File</td><td>The component name.</td>
</tr>
<tr>
<td>urn:avalon:partition</td><td>java.io.File</td>
<td>The assigned partition name.</td>
</tr>
</table>
<p>
In addition to the standard context entries, Merlin provides
support for the declaration by a component type of the supplimentary
context entry requirements (key and casting class). This criteria
is declared under the xinfo resource co-located with the component
class. An example of a simple custom context entry constrain is
included in the example xinfo descriptor presented below:
</p>
<p><i>Sample component xinfo with context entry.</i></p>
<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>hello</name>
<version>1.0</version>
</info>
<context>
<entry key="location"/>
</context>
</type>
]]></source>
<p>
In the above example we have declared that the component requires
a context entry under the key "location" returning a String (the default
context entry class) value.
</p>
<source>
package tutorial;
import org.apache.avalon.framework.logger.AbstractLogEnabled;
import org.apache.avalon.framework.activity.Initializable;
import org.apache.avalon.framework.configuration.Configurable;
import org.apache.avalon.framework.configuration.Configuration;
import org.apache.avalon.framework.configuration.ConfigurationException;
public class HelloComponent extends AbstractLogEnabled
implements Configurable, Initializable
{
private String m_source = "undefined";
/**
* Configuration of the component by the container. The
* implementation get a child element named 'source' and
* assigns the value of the element to a local variable.
*
* @param config the component configuration
* @exception ConfigurationException if a configuration error occurs
*/
public void configure( Configuration config ) throws ConfigurationException
{
getLogger().info( "configuration stage" );
m_source = config.getChild( "source" ).getValue( "unknown" );
}
/**
* Initialization of the component by the container.
* @exception Exception if an initialization error occurs
*/
public void initialize() throws Exception
{
getLogger().info( "initialization stage" );
final String message =
"source: " + m_source;
getLogger().info( message );
}
}
</source>
<p>
Build and run the tutorial without declaring any configuration.
</p>
<source>
$ ant jar
$ merlin build\classes
</source>
<p>
In the logging output we see that Merlin has created and
supplied an empty configuration to the component.
</p>
<source>
$ ant jar
$ merlin build\classes
[INFO ] (tutorial.hello): configuration stage
[INFO ] (tutorial.hello): initialization stage
[INFO ] (tutorial.hello): source: unknown
</source>
</subsection>
</section>
</body>
</document>
1.1 avalon-sandbox/merlin/merlin-smp/xdocs/starting/hello/context/casting.xml
Index: casting.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Using Merlin : Contextualization</title>
<authors>
<person name="Stephen McConnell" email="mcconnell@apache.org"/>
</authors>
</header>
<body>
<section name="Using Merlin">
<subsection name="Casting Context">
<p>
This tutorial presents information about the declaration
and implementation of a custom contextualization stage
handler.
</p>
<p>
Resource supporting this tutorial are contained in the
turorial/xxx package.
</p>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org