Totorial Objective

The objective of this tutorial is the demonstration of how we can introduce a new instantiation strategy into a part deployment descriptor. Subsequent tutorials will use the resource established here as the baseline for the introduction of the core Metro component model concepts.

Supporting classes:

Demo.java	A minimal component implementation.
DemoTestCase.java	Testcase that validates component deployment.

Technical Note

This tutorial and the following tuitorials use the Depot build system which is basically Ant driven by the depot command line handler. Depot reads information about a target project from a index.xml file and uses this information to establish an Ant project definition and supporting properties and classpath criteria. In most cases the project definition is sufficient to automate the build process. These tutorials assumes that the reader is familiar with the concepts of a project defintion, centralized defintions under a common index, and the management deployment strategy datatypes (refer Depot Tutorials for additional information).

Component Creation

In the following Depot project definition we are declaring a new project with publication of a jar and a part artifact. The significant difference from a regular plugin is the usage of a custom part strategy.

From the global index.xml we establish the reference to our target project:

<index ..... >

  ...
  
  <project xmlns="dpml:library" name="hello">

    <info title="DPML Metro Hello Tutorial">
      <description>Introductory Hello World demo.</description>
    </info>
    
    <types>
      <type id="jar"/>
      <type id="part" source="target/component.xml"/>
    </types>
    
    <dependencies>
      <test>
        <include ref="dpml/metro/dpml-metro-part"/>
        <include ref="org/apache/ant/ant-junit"/>
      </test>
    </dependencies>
    
  </project>
  
  ...
  
</index>

The component.xml file referenced in the part type production statement contains the information about the component deployment strategy.

<component xmlns="dpml:metro" name="demo" class="org.acme.Demo"/>

The custom part definition introduced under the dpml:metro namespace is declaring the production of a new part datastructure under which the class org.acme.Demo is to handled by the Metro runtime platform. The above project definition also includes the declaration of test phase dependencies that we will need in order to launch the component.

The generated part datastructure is show below (the custom Metro deployment strategy is hilighted in red). The datastructure include dependency information extracted from the prject defintion, together with component deployment infromation resolved from the referenced component.xml deployment directive.

<part xmlns="dpml:part"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <info/>

  <component xmlns="dpml:metro"
      class="org.acme.Demo"
      name="demo"/>

  <classpath>
    <private>
      <uri>artifact:jar:artifact:jar:org/acme/hello#SNAPSHOT</uri>
    </private>
  </classpath>

</part>

Summary

In this example the Demo implementation class contains nothing significant - however, the important point of this tutorial is the association of a different runtime handler for the class within our part definition. In particular:

• the <component> element is defined under a schema definition which assert a default value of "link:part:dpml/lang/dpml-lang-component" for the handler attibute which in turn is used to establish the runtime handler for the class
• the runtime handler is supplied with a classloader composed of jar files resolved from the <classpath> definition

Our next tutorial extends this project with the introduction of context management and in particular, the way in which a component class declares deployment context assumptions, and the mechanisms used by the Metro runtime to fullfill those requirements.