Service Composite
Service Composite is a subtype of Composite, and has a range of features built into it.
Services are composites that extends from the ServiceComposite interface. All the normal Composite features, such as composition of Fragments, visibility rules and declaration in assemblies during bootstrap, applies to services as well.
Services are Singletons. A Singleton in this context means that only one instance is ever created per declaration. It is still possible to have many instances, but each are declared separately and are not related to each other. This simplifies many aspects of both the Qi4j runtime as well as ambiguities for client code. Any session handling, threading model, pooling and what not, can be handled by one extra step in the service itself.
By default, services are not instantiated until they are used. This means that the ServiceComposite instance itself will not exist until someone calls a method. If a service needs to be instantiated when the Module is activated, one need to declare/call the instantiateOnStartup() method on the ServiceDescriptor during the bootstrap.
If a service implements the Activatable interface, the activate() method will be called after the service has been instantiated. The passivate() method is called when the service is being taken down. The Qi4j Runtime ensures that passivate() will not be called in the ServiceComposite instance if there are method calls in progress, to simplify the clean-up procedure.
Many services needs configuration. Qi4j has built-in support for this. By declaring
Composites
Services are composites that extends from the ServiceComposite interface. All the normal Composite features, such as composition of Fragments, visibility rules and declaration in assemblies during bootstrap, applies to services as well.
Singletons
Services are Singletons. A Singleton in this context means that only one instance is ever created per declaration. It is still possible to have many instances, but each are declared separately and are not related to each other. This simplifies many aspects of both the Qi4j runtime as well as ambiguities for client code. Any session handling, threading model, pooling and what not, can be handled by one extra step in the service itself.
Lazy and Eager Instantiation
By default, services are not instantiated until they are used. This means that the ServiceComposite instance itself will not exist until someone calls a method. If a service needs to be instantiated when the Module is activated, one need to declare/call the instantiateOnStartup() method on the ServiceDescriptor during the bootstrap.
Activatable
If a service implements the Activatable interface, the activate() method will be called after the service has been instantiated. The passivate() method is called when the service is being taken down. The Qi4j Runtime ensures that passivate() will not be called in the ServiceComposite instance if there are method calls in progress, to simplify the clean-up procedure.
Configuration
Many services needs configuration. Qi4j has built-in support for this. By declaring
@This RadioConfiguration config;
where MyServiceConfiguration is an EntityComposite, for instance;
public interface RadioConfiguration extends ConfigurationComposite
{
Property<BatteryType> batteryType();
{
Property<BatteryType> batteryType();
Property<List<Channel>> presetChannels();
// :
}
The ServiceComposite has built-in support that any Entity reference used will be considered a configuration instance. When the configuration is accessed, the ServiceComposite will automatically load it from the persistence system, and if it doesn't exist, it will create a new entity, look for a properties file with the same name and populate the entity with the values from the properties file.
The Service implementation should refresh() the ServiceComposite, to obtain any changes and do so in an atomic and controlled manner. This could be by time interval, or every time the service is called to a method that will need configuration data.
Qi4j and the Qi4j logo are trademarks of Richard Öberg, Niclas Hedhman and the members of the Qi4j Core Team. See Qi4j licensing for more information.
