The Apache Jakarta Project Jakarta HiveMind Project
 
   

hivemind.BuilderFactory Service

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

The general usage of the BuilderFactory is:

invoke-factory (service-id=hivemind.BuilderFactory)
{
  construct (class=... log-property=... messages-property=...
    service-id-property=... initialize-method=...
    error-handler-property=... class-resolver-property=...)
  {
    log
    messages
    service-id
    error-handler
    class-resolver
    string { ... }
    boolean { ... }
    configuration { ... }
    int { ... }
    long { ... }
    resource { ... }
    service { ... }
    
    event-listener (service-id=... event-site-name=...)
    set (property=... value=...)
    set-configuration (property=... configuration-id=...)
    set-resource (property=... path=...)
    set-service (property=... service-id=...)
  }
} 

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

construct

Attribute Required ? Description
class yes The fully qualified name of the class to instantiate.
class-resolver-propertynoThe 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).
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, 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

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:

Property name Property Type
classResolver ClassResolver
errorHandler ErrorHandler
log org.apache.commons.logging.Log
messages Messages
serviceId String

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.
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 org.apache.hivemind.Messages The Messages object of the invoking module.
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 The List 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 org.apache.hivemind.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 of the elements of the configuration.

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.