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.
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
{
...
}