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