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 components must also declare what resources they require to operate.
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.
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.
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 { ... }
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 { ... }
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 { ... }
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 ) { ... }
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 { ... }
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 { ... }