org.onehippo.cms7.services

Class HippoServiceRegistry

java.lang.Object

org.onehippo.cms7.services.HippoServiceRegistry

public final class HippoServiceRegistry
extends Object

The HippoServiceRegistry is used for registration and lookup/discovery of singleton services which can be shared between multiple web applications (cross-context, using different classloaders).

The HippoServiceRegistry itself is a static singleton created in the common/shared classloader, and services can only be looked up through the service interface under which they are registered. This also implies that services registered with an interface which is not provided through the shared classloader will only be visible to their own web application, which can be considered a feature!

A registered service will be wrapped in a dynamic proxy which only exposes the service interface, and optionally extra implemented interfaces as specified during the registration. Furthermore, all method invocations on the service proxy will temporarily set the current content classloader to the context classloader at the time of the service registration, for cross-context/cross-classloader usages.

While registration of services by a non-shared interface is supported, more practical usage use a shared interface for the registration but to also specify non-shared extra implemented interfaces. This allows using web application internal interfaces to be used to access additional methods not to be shared across web applications. The getService(Class, Class) method can be used to automatically return a specialized service type for that purpose.

An additional feature is using a addTracker(ProxiedServiceTracker, Class) as a callback on (un)registration of a specific service by its interface. This can be used to wait for and 'chain' specific processes which depend on a service to be(come) available, or when it is removed. Note that a ProxiedServiceTracker only can be used for monitoring (un)registration of a service by its singleton interface, not any of its extra interfaces or a subtype. The serviceRegistered and serviceUnregistered callback methods provided by the service tracker will be invoked using the context classloader of the service tracker.

For registration and tracking of non-singleton services by a common interface and automatic proxy wrapping, extend or use concrete implementations of a WhiteboardProxiedServiceRegistry base class instead. Or for more basic non-singleton service objects registration and tracking the WhiteboardServiceRegistry base class. Both these base classes support using the Whiteboard Patternfor decoupled lookup/wiring of multiple service objects by a common interface or common base type (class or interface) respectively. Example implementation and usages of these are the PersistedHippoEventListenerRegistry from the hippo-repository-api module and the HippoEventListenerRegistry

Method Summary

Modifier and Type	Method and Description
static <T> void	addTracker(ProxiedServiceTracker<T> tracker, Class<T> serviceInterface) Add a service tracker for tracking a service (to be) registered with a specific service interface.
static <T> T	getService(Class<?> serviceInterface, Class<T> extraInterface) Lookup a service (proxy) by its (main) service interface and cast it to one of the extra interfaces exposed by the proxy.
static <T> T	getService(Class<T> serviceInterface) Lookup a service (proxy) by its (main) service interface.
static <T> void	register(T serviceObject, Class<T> serviceInterface, Class<?>... extraInterfaces) Register a service object as a singleton service of a certain interface type.
static <T> void	registerService(T serviceObject, Class<T> serviceInterface) Deprecated. since v13.0. Use register(Object, Class, Class[]) instead.
static <T> boolean	removeTracker(ProxiedServiceTracker<T> tracker, Class<T> serviceInterface) Remove a previously added ProxiedServiceTracker<T>.
static <T> boolean	unregister(T serviceObject, Class<T> serviceInterface) Unregister a previously registered service object
static <T> void	unregisterService(T serviceObject, Class<T> serviceInterface) Deprecated. since v13.0. Use unregister(Object, Class) instead.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

register

public static <T> void register(T serviceObject,
                                Class<T> serviceInterface,
                                Class<?>... extraInterfaces)

Register a service object as a singleton service of a certain interface type.

The service object will be proxied to expose only the service interface, and optionally extra interfaces, and to enforce setting the Thread ContextClassLoader to its registration classloader during invocation of its service (interface) methods.

Additional interfaces can be specified by the extraInterfaces parameter to be also exposed through the proxy. See the class level documentation for usages and common use-cases.

Parameters:

serviceObject - service object to register

serviceInterface - the service interface to implement and lookup the service

extraInterfaces - optional extra interfaces to proxy for the service,

Throws:

HippoServiceException - when the service object was already registered

registerService

@Deprecated
public static <T> void registerService(T serviceObject,
                                                   Class<T> serviceInterface)

Deprecated. since v13.0. Use register(Object, Class, Class[]) instead.

unregister

public static <T> boolean unregister(T serviceObject,
                                     Class<T> serviceInterface)

Unregister a previously registered service object

Parameters:

serviceObject - the service interface under which the service was registered

Returns:

true if the service object was registered before and now removed, false otherwise

unregisterService

@Deprecated
public static <T> void unregisterService(T serviceObject,
                                                     Class<T> serviceInterface)

Deprecated. since v13.0. Use unregister(Object, Class) instead.

getService

public static <T> T getService(Class<T> serviceInterface)

Lookup a service (proxy) by its (main) service interface.

Parameters:

serviceInterface - the service interface under which the service was registered

Returns:

the service proxy or null if not found

getService

public static <T> T getService(Class<?> serviceInterface,
                               Class<T> extraInterface)

Lookup a service (proxy) by its (main) service interface and cast it to one of the extra interfaces exposed by the proxy.

Parameters:

serviceInterface - the service interface under which the service was registered

extraInterface - the extra interface exposed by the proxy to be used as return type

Returns:

the service proxy casted to the extra interface, or null if the service either was not found or doesn't implement the extra interface to be casted to

addTracker

public static <T> void addTracker(ProxiedServiceTracker<T> tracker,
                                  Class<T> serviceInterface)

Add a service tracker for tracking a service (to be) registered with a specific service interface. Multiple trackers may be added to track (un)registration of the same service interface.

Parameters:

tracker - the service tracker

Throws:

HippoServiceException - when the provided tracker instance already was added before for tracking the specific service interface

removeTracker

public static <T> boolean removeTracker(ProxiedServiceTracker<T> tracker,
                                        Class<T> serviceInterface)

Remove a previously added ProxiedServiceTracker<T>.

Parameters:

tracker - the service tracker

Returns:

true if the service tracker was added before and now removed, false otherwise