Jakarta HiveMind Project Documentation

A service definition begins with a Java interface, the service interface. Any interface will do, HiveMind doesn't care, and there's no base HiveMind interface.

A module descriptor may include <service-point> elements to define services. A module may contain any number of services.

Each <service-point> establishes an id for the service and defines the interface for the service. An example is provided later in this document.

HiveMind is responsible for supplying the service implementation as needed; in most cases, the service implementation is an additional Java class which implements the service interface. HiveMind will instantiate the class and configure it as needed. The exact timing is determined from the service's service model:

• primitive : the service is constructed on first reference
• singleton : the service is not constructed until a method of the service interface is invoked
• threaded : invoking a service method constructs and binds an instance of the service to the current thread
• pooled : as with threaded, but service implementations are stored in a pool when unbound from a thread for future use in other threads.

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

HiveMind uses a system of proxies for most of the service models (all except the primitive service model, which primarily exists to bootstrap the core HiveMind services used by other services). Proxies are objects that implement the service interface and take care of details such as constructing the actual implementation of a service on the fly. These lifecycle issues are kept hidden from your code behind the proxies.

A service definition may include service contributions, or may leave that for another module.

Ultimately, a service will consist of a core implementation (a Java object that implements the service interface) and, optionally, any number of interceptors. Interceptors sit between the core implementation and the client, and add functionality to the core implementation such as logging, security, transaction demarkation or performance monitoring. Interceptors are yet more objects that implement the service interface.

Instantiating the core service implementation, configuring it, and wrapping it with any interceptors is referred to as constructing the service. Typically, a service proxy will be created first. The first time that a service method is invoked on the proxy, the service implementation is instantiated and configured, and any interceptors for the service are created.

Any module may contribute to any service extension point. An <implementation> element contains these contributions. Contributions take three forms:

• Service constructors:
  • <create-instance> to instantiate an instance of a Java class as the implementation
  • <invoke-factory> to have another service create the implementation
• <interceptor> to add additional logic to a core implementation

An interceptor contribution is represented by an <interceptor> element. The service-id attribute identifies a service interceptor factory service: a service that implements the ServiceInterceptorFactory interface.

An interceptor factory knows how to create an object that implements an arbitrary interface (the interface being defined by the service extension point), adding new functionality. For example, the hivemind.LoggingInterceptor factory creates an instance that logs entry and exit to each method.

The factory shouldn't care what the service interface itself is ... it should adapt to whatever interface is defined by the service extension point it will create an instance for.

A service extension point may have any number of interceptor contributions. If the order in which interceptors are applied is important, then the optional before and after attributes can be specified.

In this example, is was desired that any method logging occur first, before the other interceptors. This ensures that the time taken to log method entry and exit is not included in the performance statistics (gathered by the performance interceptor). To ensure that the logging interceptor is the first, or earliest, interceptor, the special value * (rather than a list of interceptor service ids) is given for its before attribute (within the <interceptor> element). This forces the logging interceptor to the front of the list (however, only a single interceptor may be so designated).

Likewise, the security checks should occur last, after logging and after performance; this is accomplished by setting the after attribute to *. The performance interceptor naturally falls between the two.

This is about as complex as an interceptor stack is likely to grow. However, through the use of explicit dependencies, almost any arraingment of interceptors is possible ... even when different modules contribute the interceptors.

Interceptors implement the toString() method to provide a useful identification for the interceptor, for example:
<Iterceptor: hivemind.LoggingInterceptor for com.myco.MyService(com.myco.MyServiceInterface)>

This string identifies the interceptor service factory (hivemind.LoggingInterceptor), the service extension point (com.myco.MyService) and the service interface (com.myco.MyServiceInterface).

Warning

If toString() is part of the service interface (really, a very rare case), then the interceptor does not override the service implementation's method. However, this is not a recommended practice.

As an example, let's create an interface with a single method, used to add together two numbers.

package com.myco.mypackage;

public interface Adder
{
  public int add(int arg1, int arg2);
}

We could define many methods, and the methods could throw exceptions. Once more, HiveMind doesn't care.

We need to create a module to contain this service. We'll create a simple HiveMind deployment descriptor. This is an XML file, named hivemodule.xml, that must be included in the module's META-INF directory.

<?xml version="1.0"?>      
<module id="com.myco.mypackage" version="1.0.0">
  <service-point id="Adder" interface="com.myco.mypackage.Adder"/>
</module>

The complete id for this service is com.myco.mypackage.Adder , formed from the module id and the service id. Commonly, the service id will exactly match the complete name of the service interface, but this is not required.

Normally, the <service-point> would contain a <create-instance> or <invoke-factory> element, used to create the core implementation. For this example, we'll create a second module that provides the implementation. First we'll define the implementation class.

package com.myco.mypackage.impl;

import com.myco.mypackage.Adder;

public class AdderImpl implements Adder
{
  public int add(int arg1, int arg2)
  {
    return arg1 + arg2;
  }
}

That's what we meant by a POJO. We'll create a second module to provide this implementation.

<?xml version="1.0"?>
<module id="com.myco.mypackage.impl" version="1.0.0">
  <implementation service-id="com.myco.mypackage.Adder">
    <create-instance class="com.myco.mypackage.impl.AdderImpl"/>
  </implementation>
</module>

The runtime code to access the service is very streamlined:

Registry registry = . . .
Adder service = (Adder) registry.getService("com.myco.mypackage.Adder", Adder.class);  
int sum = service.add(4, 7);

Another module may provide an interceptor:

<?xml version="1.0"?>
<module id="com.myco.anotherpackage version="1.0.0">
  <implementation service-id="com.myco.mypackage.Adder">
    <interceptor service-id="hivemind.LoggingInterceptor">
  </implementation>
</module>

Here the Logging interceptor is applied to the service extension point. The interceptor will be inserted between the client code and the core implementation. The client in the code example won't get an instance of the AdderImpl class, it will get an instance of the interceptor, which internally invokes methods on the AdderImpl instance. Because we code against interfaces instead of implementations, the client code neither knows nor cares about this.

The simplest service model is the primitive service model; in this model the service is constructed on first reference. This is appropriate for services such as service factories and interceptor factories, and for several of the basic services provided in the hivemind module.

Constructing a service can be somewhat expensive; it involves instantiating a core service implementation, configuring its properties (some of which may also be services), and building the stack of interceptors for the service. Although HiveMind encourages you to define your application in terms of a large number of small, simple, testable services, it is also desirable to avoid a cascade of unneccesary object creation due to the dependencies between services.

To resolve this, HiveMind defers the actual creation of services by default. This is controled by the model attribute of the <service-point> element; the default model is singleton.

When a service is first requested a proxy for the service is created. This proxy implements the same service interface as the actual service and, the first time a method of the service interface is invoked, will force the construction of the actual service (with the core service implementation, interceptors, references to other services, and so forth).

In certain cases (including many of the fundamental services provided by HiveMind) this behavior is not desired; in those cases, the primitive service model is specified. In addition, there is rarely a need to defer service implementation or service interceptor factory services.

In general, singleton services (using the singleton or primitive service models) should be sufficient. In some cases, the service may need to keep some specific state. State and multithreading don't mix, so the threaded service model constructs, as needed, a service instance for the current thread. Once constructed, the service instance stays bound to the thread until it is discarded. The particular service implementation is exclusive to the thread and is only accessible from that thread.

The threaded service model uses a special proxy class (fabricated at runtime) to support this behavior; the proxy may be shared between threads but methods invoked on the proxy are redirected to the private service implementation bound to the thread. Binding of a service implementation to a thread occurs automatically, the first time a service method is invoked.

The service instance is discarded when notified to cleanup; this is controlled by the hivemind.ThreadEventNotifier service. If your application has any threaded services, you are responsible for invoking the fireThreadCleanup() method of the service.

A core implementation may implement the Discardable interface. If so, it will receive a notification as the service instance is discarded.

HiveMind includes a servlet filter to take care creating the Registry and managing the ThreadEventNotifier service.

The pooled service model is very similar to the threaded model, in that a service implementation will be exclusively bound to a particular thread (until the thread is cleaned up). Unlike the threaded model, the service is not discarded; instead it is stored into a pool for later reuse with the same or a different thread.

As with the threaded model, all of this binding and unbinding is hidden behind a dynamically fabricated proxy class.

Core service implementations may implement the RegistryShutdownListener interface to receive a callback for final cleanups (as with the singleton and deferred service models).

In addition, a service may implement the PoolManageable interface to receive callbacks specific to the pooled service. The service is notified when it is activated (bound to a thread) and deactivated (unbound from the thread and returned to the pool).

As discussed, the service model determines when a service is instantiated. In many cases, the service needs to know when it has been created (to perform any final initializations) or when the Registry has been shut down.

A core service implementation may also implement the RegistryShutdownListener interface. When a Registry is shutdown, the registryDidShutdown() method is invoked on all services (and many other objects, such as proxies). The order in which these notifications occur is not defined. A service may release any resources it may hold at this time. It should not invoke methods on other service interfaces.

The threaded service model does not register services for Registry shutdown notification; regardless of whether the core service implementation implements the RegistryShutdownListener interface or not. Instead, the core service implementation should implement the Discardable interface, to be informed when a service bound to a thread is discarded.

It is preferred that, whenever possible, services use the singleton service model (the default) and not the primitive model. All the service models (except for the primitive service model) expose a proxy object (implementing the service interface) to client code (included other services). These proxies are aware of when the Registry is shutdown and will throw an exception when a service method is invoked on them.

It is fairly common that some services will produce events and other services will consume events. The use of the hivemind.BuilderFactory to construct a service simplifies this, using the < event-listener> element. The BuilderFactory can register a core service implementation (not the service itself!) as a listener of events produced by some other service.

The producing service must include a matched pair of listener registration methods, i.e., both addFooListener() and removeFooListener. Note that only the implementation class must implement the listener interface; the service interface does not have to extend the listener interface. The core service implementation is registered directly with the producer service, bypassing any interceptors or proxies.

• Why do I pass the interface class to getService()?

  This is to add an additional level of error checking and reporting. HiveMind knows, from the module descriptors, the interface provided by the service extension point, but it can't tell if you know that. By passing in the interface you'll cast the returned service to, HiveMind can verify that you won't get a ClassCastException. Instead, it throws an exception with more details (the service extension point id, the actual interface provided, and the interface you passed it).

• What if no module provides a core implementation of the service?

  HiveMind checks for a service constructor when the registry itself is assembled. If a service extension point has no service constructor, an error is logged (identifying the extension point id). In addition, getService() will throw an ApplicationRuntimeException.

• What if I need to do some initializations in my service?

  If you have additional initializations that can't occur inside your core service implementations constructor (for instance, if the initializations are based on properties set after the service implementation object is instantiated), then your class should use the hivemind.BuilderFactory to invoke an initializer method.

• What if I don't invoke Registry.cleanupThread()?

  Then service implementations bound to the current thread stay bound. When the thread is next used to process a request, the same services, in whatever state they were left in, will be used. This may not be desirable in a servlet or Tapestry application, as some state from a client may be left inside the services, and a different client may be associated with the thread in later executions.

• What if I want my service to be created early, not just when needed?

  Contribute your service into the hivemind.EagerLoad configuration; this will force HiveMind to instantiate the service on startup. This is often used when developing an application, so that configuration errors are caught early; it may also be useful when a service should be instantiated to listen for events from some other service.

A module may include <configuration-point> elements to define new configuration points. A configuration point may specify the expected, or allowed, number of contributions:

• Zero or one
• Zero or more (the default)
• At least one
• Exactly one

At runtime, the number of actual contributions is checked against the constraint and an error is reported if the number doesn't match.

<configuration-point id="Simple">
  <schema>
    <element name="datum">
      <attribute name="key" required="true"/>
      <attriute name="value" required="true"/>
      
      <conversion class="hivemind.test.config.impl.Datum"/>
    </element>
  </schema>
</configuration-point>

<contribution configuration-id="Simple">
  <datum key="key1" value="value1"/>
  <datum key="key2" value="value2"/>
</contribution>

<schema id="Defaults">
  <element name="default">
  
  . . .
  
  </element>
</schema>

<configuration-point id="FactoryDefaults" schema-id="Defaults"/>

Like services, configuration points are meant to be easy to access (the only trick is getting a reference to the registry to start from).

Registry registry = . . .;
List elements = registry.getConfiguration("com.myco.MyConfig");	

int count = elements.size();
for (int i = 0; i < count; i++)
{
  MyElement element = (MyElement) elements.get(i);
  
  . . .
}

The list of elements is always returned as an unmodifiable list. An empty list may be returned.

The order of the elements in the list is not defined. If order is important, you should create a new (modifiable) list from the returned list and sort it.

Note that the elements in the list are no longer the XML elements and attributes that were contributed, the rules provided in the configuration point's <schema> are used to convert the contributed XML into Java objects.

At application startup, all the module deployment descriptors are located and parsed and in-memory objects created. Validations (such as having the correct number of contributions) occur at this stage.

The list of elements for an configuration point is not created until the first call to Registry.getConfiguration() for that configuration point.

In fact, it is not created even then. When the element list for an configuration point is first accessed, what's returned is not really the list of elements; it's a proxy, a stand-in for the real data. The actual elements are not converted until they are actually needed, in much the same way that the creation of services is deferred.

In general, you will never know (or need to know) this; when you access the size() of the list or get() any of its elements, the conversion of contributions into Java objects will be triggered, and those Java objects will be returned in the list.

If there are minor errors in the contribution, then you may see errors logged; if the <contribution> contributions are singificantly malformed, HiveMind may be unable to recover and will throw a runtime exception.

The information provided by HiveMind module descriptors is entirely static, but in some cases, some aspects of the configuration should be dynamic. For example, a database URL or an e-mail address may not be known until runtime (a sophisticated application may have an installer which collects this information).

HiveMind supports this notion through substitution symbols. These are references to values that are supplied at runtime. Substitution symbols can appear inside literal values ... both as XML attributes, and as character data inside XML elements.

Example:

<contribution configuration-id="com.myco.MyConfig">
  <value> dir/foo.txt </value>
  <value> ${config.dir}/${config.file} </value>
</contribution>

This example contributes two elements to the com.myco.MyConfig configuration point. The first contribution is simply the text dir/foo.txt. In the second contribution, the content contains substitution symbols (which use a syntax derived from the Ant build tool). Symbol substitution occurs before <schema> rules are executed, so the config.dir and config.file symbols will be converted to strings first, then whatever rules are in place to convert the value element into a Java object will be executed.

• Are the any default implementations of SymbolSource?

  There is now an configuration point for setting factory defaults: hivemind.FactoryDefaults . A second configuration point, for application defaults, overrides the factory defaults: hivemind.ApplicationDefaults.

  SystemPropertiesSymbolSource is a one-line implementation that allows access to system properties as substitution symbols. Note that this configuration is not loaded by default.

  Additional implementations may follow in the future.

• What's all this about schemas and rules?

  A central goal of HiveMind is to reduce code clutter. If configuration point contributions are just strings (in a .properties file) or just XML, that puts a lot of burden on the developer whose code reads the configuration to then massage it into useful objects. That kind of ad-hoc code is notoriously buggy; in HiveMind it is almost entirely absent. Instead, all the XML parsing occurs inside HiveMind, which uses the schema and rules to validate and convert the XML contributions into Java objects.

  You can omit the schema, in which case the elements are left as XML (instances of Element) and your code is responsible for walking the elements and attributes ... but why bother? Far easier to let HiveMind do the conversions and validations.

• How do I know if the element list is a proxy or not?

  Basically, you can't, short of performing an instanceof check. There isn't any need to tell the difference between the deferred proxy to the element list and the actual element list; they are both immutable and both behave identically.

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

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

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.

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

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

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

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

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

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.

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

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

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

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

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

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 interceptor service id, 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.

The value for before or after is a list of service ids 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.

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

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.

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.

The <module> element is the root element.

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

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.

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

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.

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.

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

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

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.

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.

Rules are attached to <element>s. Each rule object has two methods: the begin() method is invoked when the element is first encountered. The content of the element is then processed recursively (which will involve more rules). Once that completes, the end() method is invoked.

Note: begin() is invoked in the order that rules are defined within the <rules> element. end() is invoked in inverse order. This rarely makes any difference.

Element processing is based on an object stack. Several rules will manipulate the top object on the stack, setting properties based on attributes or content. The <create-object> rule will instantiate a new object at begin() and pop it off the stack at end() .

In several cases, rule descriptions reference the parent and child objects. The top object on the stack is the child, the object beneath that is the parent. The <set-parent> and <invoke-parent> rules are useful for creating hierarchies of objects.

Commonly, it is necessary to perform some translation or transformation of string attribute value to convert the value into some other type, such as boolean, integer or date. This can be accomplished by specifying a translator in the <attribute> element (it also applies to element content, with the content-translator attribute of the <element> element).

A translator is an object implementing the Translator interface. The translator value specified in a rule may be either the complete class name of a class implementing the interface, or one of a number of builtin values.

Translators configurations consist of a translator name, and an optional initalizer string. The initializer string is separated from the translator id by a comma, ex: int,min=0 (where min=0 is the initializer string). Initializer strings are generally in the format of key=value[,key=value]* ... but each Translator is free to interpret the initializer string its own way.

The following sections describe the basic translators provided with the framework. You can add additional translators by contributing to the hivemind.Translators configuration point.

まず始めのステップで、サービス・インタフェースを定義します：

package hivemind.examples;

public interface Adder
{
    public int add(int arg0, int arg1);
} 

次に、このサービス用の実装が必要になります：

package hivemind.examples.impl;

import hivemind.examples.Adder;

public class AdderImpl implements Adder
{

  public int add(int arg0, int arg1)
  {
    return arg0 + arg1;
  }

} 

この例では、さらに３つのインタフェースとそれに対応する実装が追加されています：Subtracter・Multiplier・Dividerそして最後に全部を纏めるCalculatorです：

package hivemind.examples;


public interface Calculator extends Adder, Subtracter, Multiplier, Divider
{

}    

このCalculatorの実装は結合の為の配線工事が必要です：他の４つのサービス（Adder・, Substracter・Multiplier・Divider）が差し込まれます：

package hivemind.examples.impl;

import hivemind.examples.Adder;
import hivemind.examples.Calculator;
import hivemind.examples.Divider;
import hivemind.examples.Multiplier;
import hivemind.examples.Subtracter;

public class CalculatorImpl implements Calculator
{
  private Adder _adder;
  private Subtracter _subtracter;
  private Multiplier _multiplier;
  private Divider _divider;

  public void setAdder(Adder adder)
  {
    _adder = adder;
  }

  public void setDivider(Divider divider)
  {
    _divider = divider;
  }

  public void setMultiplier(Multiplier multiplier)
  {
    _multiplier = multiplier;
  }

  public void setSubtracter(Subtracter subtracter)
  {
    _subtracter = subtracter;
  }

  public int add(int arg0, int arg1)
  {
    return _adder.add(arg0, arg1);
  }

  public int subtract(int arg0, int arg1)
  {
    return _subtracter.subtract(arg0, arg1);
  }

  public int multiply(int arg0, int arg1)
  {
    return _multiplier.multiply(arg0, arg1);
  }

  public int divide(int arg0, int arg1)
  {
    return _divider.divide(arg0, arg1);
  }
}

最後に、HiveMind モジュール・デプロイ記述子であるhivemodule.xml が必要となります。

このモジュール記述子は、インタフェースと実装に関して各々のサービスを作成します。

<?xml version="1.0"?>
<module id="hivemind.examples" version="1.0.0">
  <service-point id="Adder" interface="hivemind.examples.Adder">
    <create-instance class="hivemind.examples.impl.AdderImpl"/>
    <interceptor service-id="hivemind.LoggingInterceptor"/>
  </service-point>
  
  <service-point id="Subtracter" interface="hivemind.examples.impl.SubtracterImpl">
    <create-instance class="hivemind.examples.impl.AdderImpl"/>
    <interceptor service-id="hivemind.LoggingInterceptor"/>
  </service-point>
  
  <service-point id="Multiplier" interface="hivemind.examples.Multipler">
    <create-instance class="hivemind.examples.impl.MultiplierImpl"/>
    <interceptor service-id="hivemind.LoggingInterceptor"/>
  </service-point>
  
  <service-point id="Calculator" interface="hivemind.examples.Calculator">
    <invoke-factory>
      <!-- Autowires service properties based on interface! -->
      <constuct class="hivemind.examples.impl.CalculatorImpl"/>
    </invoke-factory>
    <interceptor service-id="hivemind.LoggingInterceptor"/>
  </service-point>  
  
</module>

ここで、module id hivemind.examples がパッケージの名前と一致するよう選びましたが、絶対的に必須であるわけではありません。

興味深い点は、hivemind.BuilderFactory をCalculatorサービスのコンストラクトのために使い、他の４つのサービスとつなぎ合わせるためにも使っている、という点です。

あらゆるサービス（あるいはコンフィグ・ポイント）にアクセスできるようになる前に、Registry がコンストラクトされなければなりません：Registry は、HiveMind によって管理されるサービスや設定のゲートウェイです。

package hivemind.examples;

import org.apache.hivemind.Registry;
import org.apache.hivemind.impl.RegistryBuilder;

public class Main
{

  public static void main(String[] args)
  {
    int arg0 = Integer.parseInt(args[0]);
    int arg1 = Integer.parseInt(args[1]);

    Registry registry = RegistryBuilder.constructDefaultRegistry();

    Calculator c =
      (Calculator) registry.getService(Calculator.class);

    System.out.println("Inputs " + arg0 + " and " + arg1);

    System.out.println("Add   : " + c.add(arg0, arg1));
    System.out.println("Subtract: " + c.subtract(arg0, arg1));
    System.out.println("Multiply: " + c.multiply(arg0, arg1));
    System.out.println("Divide  : " + c.divide(arg0, arg1));
  }
}
 

RegistryBuilder には、Registry をコンストラクトする為の、殆どの場面に見合った static メソッドが含まれています。

そして、レジストリを有する事になりましたので、Calculator インタフェースを Calculator の実装を探すためのキーとして使う事が出来るようになったわけです。実際のアプリケーションでは、同じインタフェースを実装する複数のサービスがある事がよくありますので、完全修辞のサービスIDを指定する事も必要となるでしょう。

Calculator サービスへのリファレンスを使う事で、漸くadd()・subtract()・multiply()・divide()メソッドを invoke する事が出来るようになりました。

Ant を使ってサンプルをビルド・実行するのはいともたやすい事です：詳細は、build.xmlの中に全てあります：

<?xml version="1.0"?>

<project name="HiveMind Adder Example" default="jar">

  <property name="java.src.dir" value="src/java"/>
  <property name="test.src.dir" value="src/test"/>
  <property name="conf.dir" value="src/conf"/>
  <property name="descriptor.dir" value="src/descriptor"/>
  <property name="target.dir" value="target"/>
  <property name="classes.dir" value="${target.dir}/classes"/>
  <property name="test.classes.dir" value="${target.dir}/test-classes"/>
  <property name="example.jar" value="${target.dir}/hivemind-examples.jar"/>
  <property name="lib.dir" value="lib"/>
  <property name="junit.temp.dir" value="${target.dir}/junit-temp"/>
  <property name="junit.reports.dir" value="${target.dir}/junit-reports"/>

  <path id="build.class.path">
    <fileset dir="${lib.dir}">
      <include name="*.jar"/>
    </fileset>
  </path>
      
  <path id="test.build.class.path">
    <path refid="build.class.path"/>
    <path location="${classes.dir}"/>
  </path>
        
  <path id="run.class.path">
    <path refid="build.class.path"/>
    <pathelement location="${classes.dir}"/>
    <pathelement location="${descriptor.dir}"/>
    <pathelement location="${conf.dir}"/>
  </path>
  
  <path id="test.run.class.path">
    <path refid="run.class.path"/>
    <path location="${test.classes.dir}"/>
  </path>  
  
  <target name="clean" description="Delete all derived files.">
    <delete dir="${target.dir}" quiet="true"/>
  </target>
  
  <target name="compile" description="Compile all Java code.">  
    <mkdir dir="${classes.dir}"/>    
    <javac srcdir="${java.src.dir}" destdir="${classes.dir}" classpathref="build.class.path"/>
  </target>
  
  <target name="compile-tests" description="Compile test classes." depends="compile">
    <mkdir dir="${test.classes.dir}"/>
    <javac srcdir="${test.src.dir}" destdir="${test.classes.dir}" classpathref="test.build.class.path"/>
  </target>
  
  <target name="run-tests" description="Run unit tests." depends="compile-tests">
  
    <mkdir dir="${junit.temp.dir}"/>
    <mkdir dir="${junit.reports.dir}"/>

    <junit haltonfailure="off" failureproperty="junit-failure" tempdir="${junit.temp.dir}">    
      <classpath refid="test.run.class.path"/>
    
      <formatter type="xml"/>
      <formatter type="plain"/>
      <formatter type="brief" usefile="false"/>
    
      <batchtest todir="${junit.reports.dir}">
        <fileset dir="${test.classes.dir}">
          <include name="**/Test*.class"/>
        </fileset>
      </batchtest>
    </junit>

    <fail if="junit-failure" message="Some tests failed."/>

  </target>
  
  <target name="jar" description="Construct the JAR file." depends="compile,run-tests">
    <jar destfile="${example.jar}">
      <fileset dir="${classes.dir}"/>
    <fileset dir="${descriptor.dir}"/>
    </jar>
  </target>
  
  <target name="run" depends="compile" description="Run the Adder service.">
    <java classname="hivemind.examples.Main" classpathref="run.class.path" fork="true">
      <arg value="11"/>
      <arg value="23"/>
    </java>
  </target>

</project>

JAR の中に HiveMind モジュール・デプロイ記述子とクラスファイルの両方をパッケージかして入れておく、というが重要なポイントです。

その他、唯一変わった点としては、src/conf をランタイムのクラスパスに追加する、という点が挙げられるでしょうか：log4j.properties という設定ファイルを追加するためです：さもないと、Log4J が設定ミスに関するコンソールのエラーメッセージを吐き出すでしょう。

bash-2.05b$ ant run
Buildfile: build.xml

compile:
    [mkdir] Created dir: C:\workspace\hivemind-example\target\classes
    [javac] Compiling 15 source files to C:\workspace\hivemind-example\target\classes

run:
     [java] Inputs 11 and 23
     [java] Add     : 34
     [java] Subtract: -12
     [java] Multiply: 253
     [java] Divide  : 0



BUILD SUCCESSFUL
Total time: 3 seconds

Registry が RegistryBuilder によって生成された際、ロケールが指定されます。これは、Registry の ロケールであり、更に拡張解釈すれば、レジストリ内の全てのモジュールのロケールにもなるというわけです。ロケールは変更されません。

HiveMind では、一つの起動スレッドで初期の処理が進行していく事が予定されています。これは、初期段階・モジュールのデプロイ記述子の場所確認・解析されたところのコンストラクションの段階・そしてレジストリを集めるのに使われる内容であります：RegistryBuilderのドメインです。

コンストラクション自体はスレッドセーフではありません。これには、パーサーやその他のコード（事実上、その全てがアプリケーションから隠されています）

コンストラクション段階は、RegistryBuilder が、constructRegistry() メソッドから Registry を返したときに終了します。

Registry とモジュールで起こる全ての事象はスレッドセーフでなければなりません。キーとなるメソッドは常に synchronized です。特に、 サービスをコンストラクトするメソッドやコンフィグ・ポイントをコンストラクトするメソッドはスレッドセーフです。インタセプタ・スタックをビルドするといった処理、コアとなるサービスの実装のインスタンス化、Java オブジェクトのXMLへの変換といった処理は、スレッドセーフで行われます。しかし、異なるスレッドが同時に他のサービスをビルドする可能性もあります。つまり、例えば、２つ以上の異なるサービスの為のインタセプタを同時に呼び出す事もあり得るため、インタセプタ・サービスの実装はスレッドセーフであるのです。

一方、XML<rules> によってコンストラクトされたJavaオブジェクトはスレッドセーフである必要がありません。というのも、コンストラクションは適切に synchronized な状態で行われるからです。・・・ただ一つのスレッドが XML を あらゆる一つのコンフィグ・ポイントで Java オブジェクトに変換するでしょう。

サービスが単にbetweenメソッドの invoke 状態を維持しなければならない場合、いくつかの良いオプションがあります：

• サービスに渡されるあるいはサービスから戻ってくるオブジェクト内のデータを格納
• thread-local マップ内のデータを格納する為の、hivemind.ThreadLocalStorage サービスの使用
• threaded あるいは pooled サービス・モデルの使用：サービス・メソッドが invoke されている間その状態をキープするのをサービスに許可する

フィルタを利用するためには、ウェブ・デプロイ記述子（web.xml）の中でその事が宣言されていなければなりません。フィルタは、サーブレットか、URL パターンかあるいはその両方に記述する事が出来ます。例えば：

<filter>
  <filter-name>HiveMindFilter</filter-name>
  <filter-class>org.apache.hivemind.servlet.HiveMindFilter</filter-class>
</filter>

<servlet>
  <servlet-name>MyServlet</servlet-name>
  <servlet-class>myco.servlets.MyServlet</servlet-class>
</servlet>

<filter-mapping>
  <filter-name>HiveMindFilter</filter-name>
  <servlet-name>MyServlet</servlet-name>
</filter-mapping>
 

To describe this technique, we'll start with a ordinary, every day service. In fact, for discussion purposes, there will be two services: Consumer and Provider. Ultimately, we'll show how to override Provider. Also for discussion purposes, we'll do all of this in a single module, though (of course) you can as easily split it up across many modules.

To begin, we'll define the two services, and set Provider as a property of Consumer:

<module id="ex.override" version="1.0.0">
  <service-point id="Provider" interface="ex.override.Provider">
    <create-instance class="ex.override.impl.ProviderImpl"/>
  </service-point>
  
  <service-point id="Consumer" interface="ex.override.Consumer">
    <invoke-factory>
      <construct class="ex.override.impl.Consumer">
        <set-service property="provider" service-id="Provider"/>
    </invoke-factory>
  </service-point>
</module> 

In this step, we still have just the two services ... Consumer and Provider, but they are linked together less explicitly, by using substitution symbols.

<module id="ex.override" version="1.0.0">
  <service-point id="Provider" interface="ex.override.Provider">
    <create-instance class="ex.override.impl.ProviderImpl"/>
  </service-point>
  
  <contribution configuration-id="hivemind.FactoryDefaults">
    <default symbol="ex.override.Provider" value="ex.override.Provider"/>
  </contribution>
  
  <service-point id="Consumer" interface="ex.override.Consumer">
    <invoke-factory>
      <construct class="ex.override.impl.Consumer">
        <set-service property="provider" service-id="${ex.override.Provider}"/>
    </invoke-factory>
  </service-point>
</module>       

The indirection is in the form of the symbol ex.override.Provider, which evaluates to the service id ex.override.Provider and the end result is the same as step one. We needed to use a fully qualified service id because, ultimately, we don't know in which modules the symbol will be referenced.

The final step is to define a second service and slip it into place. For kicks, the OverrideProvider service will get a reference to the original Provider service.

<module id="ex.override" version="1.0.0">
  <service-point id="Provider" interface="ex.override.Provider">
    <create-instance class="ex.override.impl.ProviderImpl"/>
  </service-point>
  
  <contribution configuration-id="hivemind.FactoryDefaults">
    <default symbol="ex.override.Provider" value="ex.override.Provider"/>
  </contribution>
  
  <service-point id="OverrideProvider" interface="ex.override.Provider">
    <invoke-factory>
      <construct class="ex.override.impl.OverrideProviderImpl">
        <set-service property="defaultProvider" service-id="Provider"/>
      </construct>
    </invoke-factory>
  </service-point>
  
  <!-- ApplicationDefaults overrides FactoryDefaults -->
  
  <contribution id="hivemind.ApplicationDefaults">
    <default symbol="ex.override.Provider" value="ex.override.OverrideProvider"/>
  </contribution>
  
  <!-- Consumer unchanged from step 2 -->
  
  <service-point id="Consumer" interface="ex.override.Consumer">
    <invoke-factory>
      <construct class="ex.override.impl.Consumer">
        <set-service property="provider" service-id="${ex.override.Provider}"/>
    </invoke-factory>
  </service-point>
</module>  

The new service, OverrideProvider, gets a reference to the original service using its real id. It can't use the symbol that the Consumer service uses, because that would end up pointing it at itself. Again, in this example it's all happening in a single module, but it could absolutely be split up, with OverrideProvider and the configuration to hivemind.ApplicationDefaults in an entirely different module.

hivemind.ApplicationDefaults overrides hivemind.FactoryDefaults. This means that the Consumer will be connected to ex.override.OverrideProvider.

Note that the <service-point> for the Consumer doesn't change between steps two and three.

The main limitation to this approach is that you can only do it once for a service; there's no way to add an EvenMoreOverridenProvider service that wraps around OverrideProvider (that wraps around Provider). Making multiple contributions to the hivemind.ApplicationDefaults configuration point with the name symbol name will result in a runtime error ... and unpredictable results.

This could be addressed by adding another source to the hivemind.SymbolSources configuration.

To be honest, if this kind of indirection becomes extremely frequent, then HiveMind should change to accomidate the pattern, perhaps adding an <override> element, similar to a <interceptor> element.

The remaining elements are enclosed by the <construct> element, and are used to supply constructor parameters and configure properties of the constructed service implementation.

BuilderFactory will automatically set certain common properties of the service implementation. By using standard names (and standard types), the need to specify attributes log-property, error-handler-property, etc. is avoided. Simply by having a writable property with the correct name and type is sufficient:

In addition, if the initialize-method attribute is not specified, and the service implementation includes a public method initializeService() (no parameters, returns void), then initializeService() will be invoked as the initializer.

The following table summarizes the elements which can be used to specify constructor parameters for the class to instantiate. These elements can be mixed freely with the properties configuring elements. It is important to know that the number, type, and order of the constructor parameter elements determine the constructor that will be used to instantiate the implementation.

Create target/registry.xml from all hivemodule.xml descriptors found inside the src directory.

<constructregistry output="target/registry.xml">
  <descriptors>
    <fileset dir="src">
      <include name="**/hivemodule.xml"/>
    </fileset>
  </descriptors>
</constructregistry> 

Generate a list of JARs inside the ${target} directory as relative paths and use it to set the Class-Path manifest attribute.

<manifestclasspath directory="${target}" property="manifest.class.path">
  <classpath refid="build.class.path"/>
</manifestclasspath>

<jar . . .>
  <manifest>
    <attribute name="Class-Path" value="${manifest.class.path}"/>
    . . .
  </manifest>
</jar>

 

The service takes a single parameter element:

<factory vend-class="..." configuration-id="..." default-cacheable="..."/>

The vend-class attribute is the name of a class all vended objects must be assignable to (as a class or interface). This is used to validate contributed bean definitions. By default it is java.lang.Object.

The configuration-id is the id of the companion configuration (used to define object classes).

The optional default-cacheable attribute sets the default for whether instantiated beans should be cached for reuse. By default this is true, which is appropriate for most use cases where the vended objects are immutable.

Each BeanFactory service must have a configuration, into which beans are contributed:

<configuration-point id="..." schema-id="hivemind.lib.BeanFactoryContribution"/>
         

Contributions into the configuration are used to specify the bean classes to instantiate, as:

<bean name="..." class="..." cacheable="..."/>  

name is a unique name used to reference an instance of the class.

class is the Java class to instantiate.

cacheable determines whether instances of the class are cacheable (that is, have immutable internal state and should be reused), or non-cacheable (presumably, because of mutable internal state).

The factory expects a single parameter element:

<create-pipeline filter-interface="..." configuration-id="..." terminator="..."/>

The filter-interface attribute is the complete class name of the filter interface.

The configuration-id is the id of the companion configuration (used to define filters).

The optional terminator attribute is used to specify an object reference. A terminator may also be contributed into the pipeline configuration.

Each pipeline service must have a configuration, into which filters are contributed:

<configuration-point id="..." schema-id="hivemind.lib.Pipeline"/>

Contributions into the configuration are used to specify the filters and the terminator.

<filter name="..." before="..." after="..." object="..."/> 

<terminator object="..."/>

package com.panorama.startup;

/**
 * Much like {@link java.lang.Runnable}, but allows the caller
 * to handle any exceptions thrown.
 *
 * @author Howard Lewis Ship
 */
public interface Executable
{
    public void execute() throws Exception;
}

The Executable interface is implemented by tasks, and by services or other objects that need to be executed. It throws Exception so that exception catching and reporting can be centralized inside the Startup service.

package com.panorama.startup.impl;

import org.apache.hivemind.impl.BaseLocatable;

import com.panorama.startup.Executable;

/**
 * An operation that may be executed. A Task exists to wrap
 * an {@link com.panorama.startup.Executable} object with
 * a title and ordering information (id, after, before).
 *
 * @author Howard Lewis Ship
 */
public class Task extends BaseLocatable implements Executable
{
    private String _id;
    private String _title;
    private String _after;
    private String _before;
    private Executable _executable;

    public String getBefore()
    {
        return _before;
    }

    public String getId()
    {
        return _id;
    }

    public String getAfter()
    {
        return _after;
    }

    public String getTitle()
    {
        return _title;
    }

    public void setExecutable(Executable executable)
    {
        _executable = executable;
    }

    public void setBefore(String string)
    {
        _before = string;
    }

    public void setId(String string)
    {
        _id = string;
    }

    public void setAfter(String string)
    {
        _after = string;
    }

    public void setTitle(String string)
    {
        _title = string;
    }

    /**
     * Delegates to the {@link #setExecutable(Executable) executable} object.
     */
    public void execute() throws Exception
    {
        _executable.execute();
    }

}

The Task class is a wrapper around an Executable object; whether that's a service, some arbitrary object, or a StaticTask.

package com.panorama.startup.impl;

import java.lang.reflect.Method;

import com.panorama.startup.Executable;

/**
 * Used to access the legacy startup code that is in the form
 * of a public static method (usually <code>init()</code>) on some
 * class.
 *
 * @author Howard Lewis Ship
 */
public class ExecuteStatic implements Executable
{
    private String _methodName = "init";
    private Class _targetClass;

    public void execute() throws Exception
    {
        Method m = _targetClass.getMethod(_methodName, null);

        m.invoke(null, null);
    }

    /**
     * Sets the name of the method to invoke; if not set, the default is <code>init</code>.
     * The target class must have a public static method with that name taking no
     * parameters.
     */
    public void setMethodName(String string)
    {
        _methodName = string;
    }

    /**
     * Sets the class to invoke the method on.
     */
    public void setTargetClass(Class targetClass)
    {
        _targetClass = targetClass;
    }
}

ExecuteStatic uses Java reflection to invoke a public static method of a particular class.

package com.panorama.startup.impl;

import java.util.Iterator;
import java.util.List;

import org.apache.commons.logging.Log;
import org.apache.hivemind.ErrorHandler;
import org.apache.hivemind.Messages;
import org.apache.hivemind.order.Orderer;

/**
 * A service that executes a series of {@link com.panorama.startup.impl.Task}s. Tasks have
 * an ordering based on pre- and post-requisites.
 *
 * @author Howard Lewis Ship
 */
public class TaskExecutor implements Runnable
{
    private ErrorHandler _errorHandler;
    private Log _log;
    private List _tasks;
    private Messages _messages;

    /**
     * Orders the {@link #setTasks(List) tasks} into an execution order, and executes
     * each in turn.  Logs the elapsed time, number of tasks, and the number of failures (if any).
     */
    public void run()
    {
        long startTime = System.currentTimeMillis();
 
        Orderer orderer = new Orderer(_log, _errorHandler, task());

        Iterator i = _tasks.iterator();
        while (i.hasNext())
        {
            Task t = (Task) i.next();

            orderer.add(t, t.getId(), t.getAfter(), t.getBefore());
        }

        List orderedTasks = orderer.getOrderedObjects();

        int failures = 0;

        i = orderedTasks.iterator();
        while (i.hasNext())
        {
            Task t = (Task) i.next();

            if (!execute(t))
                failures++;
        }

        long elapsedTime = System.currentTimeMillis() - startTime;

        if (failures == 0)
            _log.info(success(orderedTasks.size(), elapsedTime));
        else
            _log.info(failure(failures, orderedTasks.size(), elapsedTime));
    }

    /**
     * Execute a single task.
     * 
     * @return true on success, false on failure
     */
    private boolean execute(Task t)
    {
        _log.info(executingTask(t));

        try
        {
            t.execute();

            return true;
        }
        catch (Exception ex)
        {
            _errorHandler.error(_log, exceptionInTask(t, ex), t.getLocation(), ex);

            return false;
        }
    }

    private String task()
    {
        return _messages.getMessage("task");
    }

    private String executingTask(Task t)
    {
        return _messages.format("executing-task", t.getTitle());
    }

    private String exceptionInTask(Task t, Throwable cause)
    {
        return _messages.format("exception-in-task", t.getTitle(), cause);
    }

    private String success(int count, long elapsedTimeMillis)
    {
        return _messages.format("success", new Integer(count), new Long(elapsedTimeMillis));
    }

    private String failure(int failureCount, int totalCount, long elapsedTimeMillis)
    {
        return _messages.format(
            "failure",
            new Integer(failureCount),
            new Integer(totalCount),
            new Long(elapsedTimeMillis));
    }

    public void setErrorHandler(ErrorHandler handler)
    {
        _errorHandler = handler;
    }

    public void setLog(Log log)
    {
        _log = log;
    }

    public void setMessages(Messages messages)
    {
        _messages = messages;
    }

    public void setTasks(List list)
    {
        _tasks = list;
    }

}

This class is where it all comes together; it is the core service implementation for the panorama.startup.Startup service. It is constructed by the hivemind.BuilderFactory, which autowires the errorHandler, log and messages properties, as well as the tasks property (which is explicitly set in the module deployment descriptor).

Most of the run() method is concerned with ordering the contributed tasks into execution order and reporting the results.