Tutorial Overview

This tutorial takes you though the creation of a very simple component, the declaration of a component type descriptor, and the declaration of a block containing the component.

Resources (sample code and build files) supporting this tutorial are included in the Merlin distribution under the tutorials/hello directory.

Creating a component

The following code is a minimal component. It simply logs a message. We will progressively extend this component to do more creative things as we proceed through this tutorial.

package tutorial;

import org.apache.avalon.framework.logger.Logger;

/**
 * A sample component.  
 *
 * @avalon.component 
 *    version="1.0" 
 *    name="hello" 
 *    lifestyle="singleton"
 */
public class HelloComponent 
{
    //-------------------------------------------------------
    // constructor
    //-------------------------------------------------------

   /**
    * Creation of a new hello component instance.
    *
    * @param logger the logging channel supplied by the container
    */
    public HelloComponent( Logger logger )
    {
        logger.info( "Hello World" );
    }
}

Creating a Type Descriptor

In order for Merlin to recognize this class as a component, we need to generate a <classname>.xinfo file. This can be done automatically by including a pre-goal as shown below into the maven.xml file.

<preGoal name="java:compile">
  <attainGoal name="avalon:meta"/>
</preGoal>

The avalon:meta plugin looks for @avalon tags in the source code, to generate the correct Type Descriptor. In the above example it will find the @avalon.component tag in the class level javadocs and generate component the descriptors for us (see below).

Generated Type Descriptor

The following text is an example of a component type definition. It contains the declaration of the component name and the component implementation version. From the example above ( @avalon.component version="1.0" name="hello" ) the generated Type Descriptor would look something like this.

<type>
  <info>
    <name>hello</name>
    <version>1.0.0</version>
    <lifestyle>singleton</lifestyle>
    <collection>hard</collection>
  </info>
</type>

Creating a block

A block is the definition of a composite component. It represents an application made up of a set of components and the supporting resources. In our example the block will contain the single HelloComponent component. Based on this information Merlin will create a container named "tutorial", create a component model named "hello" and deploy an instance of the component on startup.

<container name="tutorial">

   <component name="hello" class="tutorial.HelloComponent"/>

</container>

Execution

The next tutorial - titled Running Hello covers deployment of the component using the Merlin runtime platform.