2009/04/15 - Apache HiveMind has been retired.

For more information, please explore the Attic.

Apache > HiveMind
Apache
 
Font size:      

HiveMind Module Descriptor

The purpose of the module descriptor is to provide a runtime and compile-time description of each HiveMind module in terms of service and configuration extension points and contributions to those extension points.

The descriptor is named hivemodule.xml and is stored in the META-INF directory of the module.

The root element of the descriptor is the <module> element.

attribute

<attribute> is used to define an attribute within an <element>. Inside a <contribution>, only known attributes are allowed in elements; unknown attributes will be logged as an error and ignored. In addition, some attributes are required; again, errors occur if the contributed element does not provide a value for the attribute.

Attribute Type Required ? Description
name string yes The name of the attribute.
required boolean no If true, the attribute must be provided in the contributed configuration element. The default is false.
unique boolean no If true, the attribute must contain a unique value with respect to all other contributions to the same configuration point. The default is false.
translator string no The translator configuration that is used to convert the attribute into a useable type. By default, the attribute is treated as a single string.

configuration-point

The <configuration-point> element defines a configuration extension point.

Attribute Type Required ? Description
id string yes The simple id of the service extension point. The fully qualified id for the extension point is created by prefixing with the module's id (and a dot).
visibility public | private no If private is specified, then the configuration point may only be referenced (or contributed to) from within the same module. It will not be visible to the application (via the Registry) if private. The default is public.
occurs unbounded | 0..1 | 1 | 1..n | none no The number of contributions allowed:
  • unbounded (default): any number
  • 0..1: optional
  • 1 : required
  • 1..n: at least one
  • none: none allowed
Note
none doesn't make sense for occurances to a configuration point, but does occasionally make sense for parameters to a factory.
schema-id string no Used to reference a <schema> (in the same module, or a different one) that defines the format of contributions into the configuration point. This may be omitted, in which case the extension point will contain a list of Element .

Contains: <schema>

<configuration-point> only defines a configuration point, it does not supply any data into that point. The <contribution> element is used to provide such data.

contribution

The <contribution> element contributes elements to an existing configuration extension point.

Attribute Type Required ? Description
configuration-id string yes Either the id of an <configuration-point> within the module, or the fully qualified id of an <configuration-point> in another module.
if string no A conditional expression controlling whether the contribution is used or ignored.

The content of the <contribution> consists of elements. These elements are converted, in accordance with the configuration point's <schema>, into Java objects.

conversion

<conversion> is an alternative to <rules> that is generally simpler and more concise. An <element> should contain <conversion> or <rules> but not both.

<conversion> is geared towards the typical case; a straight-forward mapping of the element to an instance of a Java class, and a mapping of the element's attributes to the properties of the Java object.

Attribute Type Required ? Description
class string yes The fully qualified name of a Java class to instantiate.
parent-method string no The name of a method of the parent object used to add the created object to the parent. The default, addElement, is appropriate for top-level <element>s.

Contains: <map>

Each attribute will be mapped to a property. A limited amount of name mangling occurs: if the attribute name contains dashes, they are removed, and the character following is converted to upper case. So, an attribute named "complex-attribute-name" would be mapped to a property named "complexAttributeName". Only attributes identified with a <attribute> element will be mapped, others will be ignored.

create-instance

<create-instance> is used, within <service-point> and <implementation> to create the core service implementation for a service by instantiating a class. This is appropriate for simple services that require no explicit configuration.

Attribute Type Required ? Description
class class name yes The class name to instantiate. May use instance initializer syntax.
model primitive | singleton | threaded | pooled no The model used to construct and manage the service. singleton is the default.

Additional service models can be defined via the hivemind.ServiceModels configuration point.

dependency

<dependency> is used, within <module> to specify a dependency upon another required module.

Attribute Type Required ? Description
module-id string yes The id of the required module.
version version number no The version of the required module as a dotted sequence of three numbers. Example: "1.0.0". With no version specified any version of the required module is matched.

In the future HiveMind will support other more sophisticated version matching types for dependencies.

element

The <element> element is used to define an element in a the <schema>. <element> may also be nested within another <element>, to indicate an element that may be enclosed within another element.

Attribute Type Required ? Description
name string yes The name of the element.
content-translator string no The translator configuration that is used to convert the element's content into a useable type. By default, the content is treated as a single string.
key-attribute string no The name of this element's <attribute> whose translated value will be used as a unique key for configuration contributions corresponding to this element. The contributions can then be accessed in a Map using this key. The specified <attribute> is implicitly marked as required and unique.

Contains: <attribute>, <conversion>, <element>, <rules>

Future enhancements to the HiveMind framework will include greater sophistication in defining configuration content.

implementation

The <implementation> element contributes a core implementation or interceptors to a service extension point.

Attribute Type Required ? Description
service-id string yes The id of the service to extend; this may be a fully qualified id, or the local id of a service within the same module.
if string no A conditional expression controlling whether the contribution is used or ignored.

Contains: <create-instance>, <interceptor>, <invoke-factory>

interceptor

<interceptor> contributes an interceptor factory to a service extension point. An interceptor factory is a service which implements the ServiceInterceptorFactory interface.

When the service is constructed, each invoked interceptor factory will fabricate an interceptor class to provide additional functionality for the service.

Attribute Type Required ? Description
service-id string yes The id of the service that will create the interceptor for the service. This may be the local id of a service defined within the same module, or a fully qualified id.
before string no A list of interceptors whose behavior should come later in execution than this interceptor.
after string no A list of interceptors whose behavior should come earlier in execution than this interceptor.
name string no The name to use for ordering this interceptor. Defaults to the service-id. This comes in handy when using the same factory to create multiple unique interceptors which should be able to be ordered with respect to one another.

Like a service implementation factory, a service interceptor factory may need parameters. As with <invoke-factory>, parameters to the interceptor factory are enclosed by the <interceptor> element. The service interceptor factory will decode the parameters using the schema identified by its parameters-schema-id attribute.

Interceptor ordering is based on dependencies; each interceptor can identify, by name, other interceptors. Interceptors in the before list are deferred until after this interceptor. Likewise, this interceptor is deferred until after all interceptors in the after list.

Note
The after dependencies will look familar to anyone who has used Ant or any version of Make. before dependencies are simply the opposite.

The value for before or after is a list of interceptor names seperated by commas. Service ids may be unqualified if they are within the same module. Alternately, the fixed value * may be used instead of a list: this indicates that the interceptor should be ordered absolutely first or absolutely last.

invoke-factory

The <invoke-factory> element is used to provide a service implementation for a service by invoking another service, a factory service.

Attribute Type Required ? Description
service-id string no The id of the factory service. This may be a simple id for a service within the same module, or a fully qualified service id. The default, if not specified, is hivemind.BuilderFactory.
model primitive | singleton | threaded | pooled no The model used to construct and manage the service. singleton is the default.

A service factory defines its parameters in terms of a schema. The content of the <invoke-factory> is converted, in accordance with the factory's schema, and provided to the factory.

Note
Additional service models can be defined via the hivemind.ServiceModels configuration point.

map

The <map> element appears within <conversion> to override the default mapping from an attribute to a property. By default, the property name is expected to match the attribute name (with the name mangling described in the description of <conversion>); the <map> element is used to handle exceptions to the rule.

Attribute Type Required ? Description
attribute string yes The name of the attribute, which should match a name defined by an<attribute> (of the enclosing <element>).
property string yes The corresponding property (of the Java object specified by the enclosing <conversion>)

module

The <module> element is the root element.

Attribute Type Required ? Description
id string yes The id should be a dotted sequence, like a package name. In general, the module id should be the package name.
version version number yes The version of the module as a dotted sequence of three numbers. Example: "1.0.0"
package string no The package which contains Java types within the module. Defaults to the module's id if not specified.

Contains: <contribution>, <configuration-point>, <dependency>, <implementation> , <service-point>, <schema>, <sub-module>

Every module is mapped to a Java package, using the package attribute (or the module's id if not specified). When a class name is referenced within a module, the name will be searched for within the package if not found normally. This applies to all contributions, etc., within the module ... virtually anywhere a Java class name can be used. Literally, if the class can't be found by the provided type, the module's package name is prefixed and a second search is attempted. The interface attribute of the <service-point> element is slightly different.

parameters-schema

The <parameters-schema> element is identical to the <schema> element, but only appears inside <service-point>, to define the schema for the parameters for a service implementation factory or service interceptor factory.

Note
This element and the owning <service-point> element's parameters-schema-id attribute are mutually exclusive.

rules

<rules> is a container for element and attribute parsing rules within an <element>. These rules are responsible for converting the contributed element and its attributes into objects and object properties. The available rules are documented separately .

schema

The <schema> element is used to describe the format of element contributions to an <configuration-point>, or parameters provided to a service or interceptor factory.

Attribute Type Required ? Description
id string yes Assigns a local id to the schema that may be referenced elsewhere.
visibility public | private no If private is specified, then the schema may only be referenced from within the same module. The default is public.

Contains: <element>

At a future time, the <schema> element will be extended to provide more options, to provide more precise control over the elements that may be provided in an <contribution>. At this time, a <schema> is simply a list of <element> elements.

Warning
When <schema> appears directly within <configuration-point>, or <parameters-schema> appears directly within <service-point>, then the id and visibility attributes are not allowed.

service-point

The <service-point> element defines a service extension point.

Attribute Type Required ? Description
id string yes The simple id of the service extension point. The fully qualified id for the extension point is created by prefixing with the module's id (and a dot).
interface class name no The name of the Java interface (or class) supplied by this service extension point. If no value is provided, the interface defaults to the service id (and will then be qualified by the module's package).
visibility public | private no If private is specified, then the service may only be referenced (or contributed to) from within the same module. It will not be visible to the application (via the Registry) if private. The default is public. It is common for a module to have several public services acting as a facade over many more private services.
parameters-schema-id string no Used to reference a <schema> (in the same module, or a different one) that defines parameters used by the service. This is used when the service being defined is a ServiceImplementationFactory or a ServiceInterceptorFactory.
parameters-occurs unbounded | 0..1 | 1 | 1..n | none no The number of parameter element contributions allowed:
  • unbounded: any number
  • 0..1: optional
  • 1 (default) : required
  • 1..n: at least one
  • none: none allowed

Contains: <create-instance>, <interceptor>, <invoke-factory> , <parameters-schema>

If the specified interface name is unqualified (does not contain a period), then it is prefixed with the module's package name. Note that this is slightly different than how partial class names are resolved elsewhere in a module descriptor.

sub-module

The <sub-module> element is used to identify an additional HiveMind module deployment descriptor. This is used when a single JAR file contains logically distinct packages, each of which should be treated as an individual HiveMind module. This can also be useful as a way to reduce developer conflict against a single, large, central module descriptor by effectively breaking it into smaller pieces. Sub-modules identified in this way must still have their own unique module id.

Attribute Type Required ? Description
descriptor string yes Location of the module descriptor.
if string no A conditional expression controlling whether the sub-module is included or ignored.

The descriptor should be specified as a relative path, either the name of another module descriptor within the same folder, or within a child folder.