MetaData Model

This document describes the minimal set of metadata requirements for DNA components.The metadata includes what resources the component can provide to other components and what resources the component requires from the container.

DNA components must declare the resources that they are capable of providing to other components.

  • dna.component : The object must declare that they are DNA components and not just some random java object.
  • dna.service : The object must declare what services (aka work interfaces) that the component implements and is capable of providing to other components.

DNA components must also declare what resources they require to operate.

  • dna.logger : The object must declare the Logger objects that they will use.
  • dna.configuration : The object must declare location of the configuration schema (if any) that can be used to validate any configuraiton data that they are provided.
  • dna.dependency : The object mus t declare the services that it expects to find in the ResourceLocator.

DNA components can optionally declare their compatibility with a particular container extension. A component could declare that the component requires, supports or is incompatible with the container extension. For further details on extensions see the extensions document.

Model Elements

The following sections describe the metadata elements that should be interpreted for DNA components. The metadata is represented as JavaDoc tags as that format is capable of being pre-processed by tools and should be familiar to the developer.

Several of the JavaDoc tags have parameters that represent a type name. These type names may either be the full qualified name of a class or it may be a name resolvable in the Java source file. The resolution process follows the standard rules for resolution. ie First the runtime will check if the class is explicitly imported, then it will check to see if it is imported using a '*' import, then it will check to see if it is a member of the current package, then it will check to see if the class is part of the java.lang package and if none of the above conditions hold true it will assume that the full qualified name has been specified.

dna.component

The dna.component tag is specified in the class JavaDocs and simply declares that the class is a DNA component . It must be present for tools and runtimes to automatically recognize the component.

Example:

/**
 * This is a DNA component.
 *
 * @dna.component
 */
public class MyComponent
{
   ...
}
                    

dna.service

The dna.service tag declares the services the component is capable of providing to other components. The dna.service tag is specified as part of the class JavaDocs and has the following parameters.

Name Default Value Description Optional
type n/a The type parameter specifies the name of the interface for service. This parameter follows type resolution rules as specified above. false

Example:

package com.biz;

import com.biz.services.MyService1;

/**
 * @dna.service type="MyService1"
 * @dna.service type="MyService2"
 */
public class MyComponent
  implements MyService1, MyService2, SomeOtherInterface
{
   ...
}
                    

dna.extension

The dna.extension tag declares the components relationship to a container extension. The dna.extension tag is specified as part of the class JavaDocs and has the following parameters.

Name Default Value Description Optional
name n/a The name of the container extension. false
compatibility required The compatibility of container with extension. Must be one of "required", "supports" or "incompatible". true

Example:

/**
 * @dna.extension name="tx"
 * @dna.extension name="mx" compatibility="supports"
 * @dna.extension name="remote" compatibility="incompatible"
 */
public class MyComponent
{
   ...
}
                    

dna.logger

The dna.logger tag declares the names of the loggers that the component will use. The dna.logger tag is specified as part of the LogEnabled.enableLogging(Logger) method JavaDocs and has the following parameters.

Name Default Value Description Optional
name "" The name of the logger. The Logger object passed to the component has the name "". true

Example:

/**
 * @dna.logger
 * @dna.logger name="auth"
 */
public void enableLogging( Logger logger )
{
   ...
}
                    

dna.configuration

The dna.configuration tag declares the schema that can be used to validate the configuration for the component. The dna.configuration tag is specified as part of the Configurable.configure(Configuration) method JavaDocs and has the following parameters.

Name Default Value Description Optional
location < classname > -schema.xml The location of the configuration schema file relative to the .class file. true
type "" The type of the schema file. If not specified then the underlying validator will attempt to guess the schema type either via the file extension (for DTDs) or via the namespace used in the xml schema file. true

Example:

/**
 * @dna.configuration location="MySchema.dtd"
 */
public void configure( Configuration config )
    throws ConfigurationException
{
   ...
}
                    

dna.dependency

The dna.dependency tag declares the services that the component should be able to access from the ResourceLocator. The dna.dependency tag is specified as part of the Composable.compose(ResourceLocator) method JavaDocs and has the following parameters.

Name Default Value Description Optional
type n/a The type name of the dependency. This follows the type resolution rules specified above. false
optional false Specifies whether the dependency is optional or required. true
qualifier "" Specifies the qualifier used to default key value. See description of key parameter for further details. This parameter can not be specified if the key parameter is specified. true
key See Description The key specifies the name used to access service from the ResourceLocator. The default value for this parameter is either the type name or < type-name$gt;/ < qualifier > if the qualifier parameter is specified. true

Example:

/**
 * @dna.dependency type="Store"
 * @dna.dependency key="persist" type="PersistenceEngine"
 * @dna.dependency qualifier="TempSpool" type="Store" optional="true"
 */
public void compose( ResourceLocator locator )
    throws MissingResourceException
{
   ...
}