What you will learn

In this short summary you will get an idea how services are registered to the engine and how to write your own IServiceProvider.

1. Basics

The IServiceProvider is the core component that enables the developers to register services, so that they become available throughout the runtime of the IEngine. The used IServiceProvider can be assigned to the IContext (with the ContextBuilder) during the process of the Engine Builder while creating the default IEngine.

By default, the IServiceProvider is the preferred source for fetching services. But when a service couldn’t be found, then the default IEngine falls back on the ServiceLoader mechanism provided natively by Java. This behaviour can be configured through the IServiceProvider method boolean preferServiceLoader().

Your implementation of IServiceProvider gets wrapped around internally by the framework and enhanced by the ServiceLoader mechanism.

2. Signature

Before giving a short example on how the interface should be used, this section describes the signature of the IServiceProvider interface, as well as an overview on which methods have to be implemented.

<T> T find(Class<T> clazz);

Fetches the wanted service registered under the class given. Null if none could be found.

 
<T> T find(Class<T> clazz, String id);

Fetches the wanted service registered under the class and id given. Used for example when multiple services are registered, but only one needs to be fetched.

 
Map<Class<?>, Object> getAll();

Returns all registered services of the provider.

 
<A, T extends A> void put(Class<A> clazz, T object);

Registers a service at the provider.

 
<A, T extends A> void put(Class<A> clazz, T object, String id);

Registers a service with an id at the provider.

 
default boolean preferServiceLoader()

Defines if the ServiceLoader mechanism is preferred over the service fetched from the provider. By default, it returns false, and services from this provider are preferred.

3. Usage

This section briefly outlines a few examples demonstrating how the IServiceProvider should be used.

3.1. Configure at the Engine Builder

To make sure the services are available during the default IEngine runtime, you need to configure it at the Engine Builder.

// Using the context builder to create a IContext
final ContextBuilder cb = new ContextBuilder(); (1)
// Using your own written IServiceProvider
final IServiceProvider sp = new YourProvider();
cb.setServiceProviderFactory(context -> sp); (2)
// Finalizing the Engine Builder
final IContext context = cb.build();
final IEngine engine = new EngineBuilder()...setContext(context).build(); (3)
1 The IServiceProvider is part of the IContext so we use the Context Builder to combine them both.
2 Registering your implementation is as easy as let it be the return value of an IServiceProviderFactory. As we didn’t implement one we can use an anonymous class to let it return for us.
3 Now the IContext only needs to be set to the Engine Builder and the services will be available to the engine.

The IServiceProvider is part of the IContext and can be later accessed over that, during engine runtime.

3.2. Registering Services

You can register services before configuring it for the IEngine or during the execution. In both cases call the put method of the IServiceProvider to register an implementation to an interface it fulfills.

// Using the context builder to create a IContext
final ContextBuilder cb = new ContextBuilder();
// Using your own written IServiceProvider
final IServiceProvider sp = new YourProvider();

sp.put(IDataTransformer.class, new JsonStringDataTransformer()); (1)

cb.setServiceProviderFactory(context -> sp);
// Finalizing the Engine Builder
final IContext context = cb.build();
final IEngine engine = new EngineBuilder()...setContext(context).build();
1 The service IDataTransformer is registered with the default implementation JsonStringDataTransformer and is now accessible during engine execution.

3.3. Fetching Services

Let’s suppose we are in an inner component of the engine, e.g a WrappingPersistenceService and want to transform any data before putting them into the persistence. Then the wrapping component only needs to be initialized with the Context of the engine. Then we can fetch the IServiceProvider and request the IDataTransformer service.

class WrappingPersistenceService implements IPersistenceService{

	private final IContext context; (1)
	private final IPersistenceService wrapped;
	...
    @Override
    public Object find(final String key){
		final IDataTransformer dt = this.context.getServiceProvider().find(IDataTransformer.class); (2)
...
    }
}
1 The IContext is set beforehand. Remember that the IServiceProvider is part of the context.
2 Now you can use the context during method invocation to access the services registered in the IServiceProvider
Also services of the ServiceLoader can be fetched this way. Because your given IServiceProvider is enhanced by the mechanism from us.

4. Default Implementations

  • de.asap.pak.core.simple.context.SimpleServiceProvider : Functions as a prototype IServiceProvider which holds the services registered in a map.

  • de.asap.pak.extra.guice.GuiceServiceProvider : Uses the functionalities of Guice, allowing to use its annotation to register services etc.