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

For more information, please explore the Attic.

The BuilderFactory service is a service implementation factory ... a service that is used to construct other services.

The builder factory takes a single parameter element (usually with nested elements):

<construct
    class="..." autowire-services="..." log-property="..." messages-property="..."
    service-id-property="..." initialize-method="..." error-log-property="..."
    error-handler-property="..." class-resolver-property="...">

    <log/>
    <messages/>
    <service-id/>
    <error-handler/>
    <error-log/>
    <class-resolver/>
    <string>  ... </string>
    <boolean> ... </boolean>
    <configuration> ... </configuration>
    <int> ... </int>
    <long> ... </long>
    <resource> ... </resource>
    <service> ... </service>
    <object> ... </object>
    <null/>

    <event-listener service-id="..." event-type-name="..."/>
    <set property="..." value="..."/>
    <set-configuration property="..." configuration-id="..."/>
    <set-resource property="..." path="..."/>
    <set-service property="..." service-id="..."/>
    <set-object property="..." value="..."/>
</construct> 

The attributes of the construct element are used to specify the implementation class and set common service properties. Nested elements supply the constructor parameters and configure other specific properties of the implementation (the set-... elements).

Note:

BuilderFactory is a complex tool, with support for both constructor dependency injection and property dependency injection. Many of the options are rarely used; the most general purpose and most frequently used are set, set-object and event-listener (along with autowiring).

construct

Attribute Required ? Description
autowire-services no If true (the default), then the BuilderFactory will attempt to automatically wire services and some common properties to constructor parameters and to properties of the constructed implementation with setter methods (see notes below).
class yes The fully qualified name of the class to instantiate.
class-resolver-property no The property to receive the module's ClassResolver.
error-handler-property no The name of a property to recieve the module's ErrorHandler instance (which is used to report recoverable errors).
error-log-property no The name of a property which will be assigned an ErrorLog instance for the service. An ErrorLog is simply a wrapper around a Log and an ErrorHandler as is the preferred approach.
initialize-method no The name of a method (public, no parameters) to invoke after the service is constructed, to allow it to perform any final initializion before being put into use.
log-property no The name of a property which will be assigned a org.apache.commons.logging.Log instance for the service. The Log is created from the complete service id (not the name of the class). If ommitted (and autowiring is disabled), no Log will be assigned.
messages-property no Allows the Messages for the module to be assigned to a property of the instance.
service-id-property no Allows the service id of the constructed service to be assigned to a property of the service implementation.

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

Autowiring

With autowire-services set to true the BuilderFactory can automatically both perform constructor based and setter based dependency injection. It will not only attempt to inject services but also certain common properties. By using standard names (and standard types), the need to specify attributes log-property, error-handler-property, etc. is avoided. Simply declaring a constructor parameter with the correct type or a writable property with the correct name and type is sufficient:

Property name Property / parameter type
classResolver ClassResolver
errorHandler ErrorHandler
errorLog ErrorLog
log org.apache.commons.logging.Log
messages Messages
serviceId String

Note:

The service id (last entry in above table) will only be automatically injected through a writable property (i.e. setServiceId(String)). This because a constructor parameter of type String is far too common.

As noted the BuilderFactory will also inject services into the constructed service implementation. Through every constructor parameter and writable property whose type is an interface (with the exception of the common parameters / properties listed above) and hasn't been set otherwise the BuilderFactory will attempt to inject a service. This attempt may fail if there is no visible service or more than one visible service implementing the given interface. (Visibility is checked with respect to the module declaring the constructed service's implementation.)

The action taken if the service injection fails (due to one of the reasons given above) depends on the type of dependency injection. For constructor based dependency injection the BuilderFactory will try using a different constructor (see selection details below). If no "working" constructor is found an error is logged. For setter based dependency injection the BuilderFactory will log an error immedeately upon failed injection.

Constructor based dependency injection is enabled with the autowire-services attribute but can be overridden by declaring any constructor parameter elements (see next section). The constructor being used for the constructor based dependency injection has to meet all of the following criteria:

  • the constructor is declared as public
  • all parameter types are interfaces (including the common types listed above)
  • no two parameters are of the same type
All constructors of the service implementation class meeting these criteria (the default constructor is considered as one of these) are ordered by length (given by the number of parameters) and the first of these for which every parameter type either has a matching common property or there is exactly one corresponding visible service available will be invoked. If no such constructor can be found an error is logged. Autowiring may be complicated by the fact that one module may define a service point that will tangentially affect the construction of a service in another module (simply by implementing the same service interface). In this situation, service autowiring can be turned off, by setting the autowire-services attribute to false. Once all properties have been set (possibly by autowiring), an initializer method will be invoked. 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.

Constructor Parameter Elements

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.

Element Matched Parameter Type Passed Parameter Value
error-handler ErrorHandler The module's ErrorHandler, user to report recoverable errors.
error-log ErrorLog The service's ErrorLog, used to report recoverable errors (this is preferred over using a Log and an ErrorHandler).
log org.apache.commons.logging.Log The Log is created from the complete service id (not the name of the class) of the created service.
messages Messages The Messages object of the invoking module.
object variable As determined by the object translator, this is decidedly free-form. See hivemind.ObjectProviders.
null any reference type Always simply null.
service-id java.lang.String The service id of the constructed service.
string java.lang.String This element's content.
boolean boolean This element's content. Must be either "true" or "false".
configuration java.util.List or java.util.Map The List / Map of the elements of the configuration specified by this element's content as a configuration id. The id can either by a simple id for a configuration within the same module as the constructed service, or a complete id.
int int This element's content parsed as an integer value.
long long This element's content parsed as a long value.
resource Resource This element's content parsed as a path to a Resource, which is relative to the contributing module's deployment descriptor. If available, a localized version of the Resource will be selected.
service interface corresponding to specified service The implementation of the service with the id given in this element's content. The id can either be a simple id for a service within the same module as the constructed service, or a complete id.

Service Property Configuring Elements

event-listener

Attribute Description
service-id The service which produces events. The service must provide, in its service interface, the necessary add and remove listener methods.
name The name of an event set to be registered. If not specified, all applicable event sets are used.

If the name attribute is not specified, then BuilderFactory will register for all applicable event sets. For each event set provided by the specified service, BuilderFactory will check to see if the service instance being constructed implements the corresponding listener interface ... if so, the constructed service instance is added as a listener. When the name attribute is specified, the constructed service instance is registered as a listener of just that single type.

Event notifications go directly to the constructed service instance; they don't go through any proxies or interceptors for the service. The service instance must implement the listener interface, the constructed service's service interface does not have to extend the listener interface. In other words, event notifications are "behind the scenes", not part of the public API of the service.

It is perfectly acceptible to include multiple <event-listener> elements for a number of different event producing services.

It is not enough for the event producer service to have an add listener method (i.e., addPropertyChangeListener(PropertyChangeListener)). To be recognized as an event set, there must also be a corresponding remove listener method (i.e., removePropertyChangeListener(PropertyChangeListener)), even though BuilderFactory does not make use of the remove method. This is an offshoot of how the JavaBeans API defines event sets.

set

Attribute Description
property The name of the property to set.
value A value to assigned to the property. The value will be converted to an appropriate type for the property.

set-configuration

Attribute Description
property The name of the property to set.
configuration-id The id of a configuration, either a simple id for a configuration within the same module as the constructed service, or a complete id. The property will be assigned a List or Map of the elements of the configuration.

set-object

Attribute Description
property The name of the property to set.
value The selector used to find an object value. The selector consists of a prefix (such as "service" or "configuration"), a colon, and a locator whose interpretation is defined by the prefix. For example, service:MyService. See hivemind.ObjectProviders.

set-resource

Attribute Description
property The name of the property to set.
path The path to a Resource, relative to the contributing module's deployment descriptor. If available, a localized version of the Resource will be selected.

set-service

Attribute Description
property The name of the property to set.
service-id The id of a service, either a simple id for a service within the same module as the constructed service, or a complete id. The property will be assigned the service.