Javadoc Tag Markup

Information about a component type may be declared in the form of javadoc tags (refer Tag Specification. Using development tools supplied as part of the Avalon Meta package - the process of generation of an XML type descriptor can be completely automated.

A special tag @avalon.component is used to identify a class as a component. The following code framgment illustrates the use of the @avalon.component tag.

/**
 * Component demonstrating access to standard context entries.
 *
 * @avalon.component name="demo" lifestyle="singleton"
 */
public class HelloComponent 
{
   ...
}

Additional tags are used to markup requirements that a component class has towards a container. In the following code fragment a constructor is presented with a series of context entry dependencies that the component has during its instantiation phase. Each tag represents a particular context entry assumption that the component has, and the implicit responsibility of a container to fulfill.

   /**
    * Creation of a new HelloComponent instance using a 
    * container supplied logging channel and context.
    * The context supplied by the container holds the 
    * standard context entries for the home and 
    * working directories, component name and partition.
    *
    * @avalon.entry key="urn:avalon:name" 
    * @avalon.entry key="urn:avalon:partition" 
    * @avalon.entry key="urn:avalon:home" type="java.io.File"
    * @avalon.entry key="urn:avalon:temp" type="java.io.File"
    */
    public HelloComponent( Logger logger, Context context )
      throws ContextException
    {
        m_logger = logger;

        m_home = (File) context.get( "urn:avalon:home" );
        m_temp = (File) context.get( "urn:avalon:temp" );
        m_name = (String) context.get( "urn:avalon:name" );
        m_partition = (String) context.get( "urn:avalon:partition" );

        StringBuffer buffer = new StringBuffer( "standard context entries" );
        buffer.append( "\n  name: " + m_name );
        buffer.append( "\n  home: " + m_home );
        buffer.append( "\n  temp: " + m_temp );
        buffer.append( "\n  partition: " + m_partition );

        m_logger.info( buffer.toString() );
    }

XML External Form

A component type may be associated with a component class by colocating an XML file with the suffix "xinfo" with the component implementation class. For example, the class tutorial.Hello is packaged in a jar file under the path /tutorial/Hello.class. The xinfo file is packaged as /tutorial/Hello.xinfo.

The formal specification of the XML external form for component type descriptors is available as part of the Avalon Meta Package.

An example of a xinfo XML content taken from the context casting tutorial is presented below.

<type>
  <info>
    <name>demo</name>
    <version>1.0.0</version>
    <lifestyle>singleton</lifestyle>
    <collection>hard</collection>
  </info>
  <context type="tutorial.DemoContext">
    <entry key="urn:avalon:name" />
    <entry key="urn:avalon:partition" />
    <entry key="urn:avalon:home" type="java.io.File" />
    <entry key="urn:avalon:temp" type="java.io.File" />
  </context>
</type>

Type Model

The Avalon Meta package provides the overal meta-info layer within which a component type descriptor is defined. The descriptor is an immutable data object that contains a component classname, attributes, context dependencies, deployment dependencies, runtime service dependencies, service and extension publication, and associating logging channel assumptions. The full specification of the Type class is provided in the package javadoc. Type establishment is typically automated by the container by scanner jar file for xinfo descriptors (or possibly through dynamic type creation).