org.glassfish.hk2.utilities

Class ServiceLocatorUtilities

java.lang.Object

org.glassfish.hk2.utilities.ServiceLocatorUtilities

public abstract class ServiceLocatorUtilities
extends java.lang.Object

This is a set of useful utilities for working with ServiceLocator.

Author:

jwells

Constructor Summary

Constructors

Constructor and Description
ServiceLocatorUtilities()

Method Summary

Methods

Modifier and Type	Method and Description
static <T> ActiveDescriptor<T>	addOneConstant(ServiceLocator locator, java.lang.Object constant) This method adds one existing object to the given service locator.
static <T> ActiveDescriptor<T>	addOneConstant(ServiceLocator locator, java.lang.Object constant, java.lang.String name, java.lang.reflect.Type... contracts) This method adds one existing object to the given service locator.
static <T> ActiveDescriptor<T>	addOneDescriptor(ServiceLocator locator, Descriptor descriptor) It is very often the case that one wishes to add a single descriptor to a service locator.
static <T> ActiveDescriptor<T>	addOneDescriptor(ServiceLocator locator, Descriptor descriptor, boolean requiresDeepCopy) It is very often the case that one wishes to add a single descriptor to a service locator.
static ServiceLocator	bind(Binder... binders) This method will create or find a ServiceLocator with the name "default" and bind all of the binders given together in a single config transaction.
static void	bind(ServiceLocator locator, Binder... binders) This method will bind all of the binders given together in a single config transaction.
static ServiceLocator	bind(java.lang.String name, Binder... binders) This method will create or find a ServiceLocator with the given name and bind all of the binders given together in a single config transaction.
static DynamicConfiguration	createDynamicConfiguration(ServiceLocator locator) This method returns a DynamicConfiguration for use with adding and removing services to the given ServiceLocator.
static void	enablePerThreadScope(ServiceLocator locator) This method will add the ability to use the PerThread scope to the given locator.
static <T> ActiveDescriptor<T>	findOneDescriptor(ServiceLocator locator, Descriptor descriptor) Finds a descriptor in the given service locator.
static <T> T	findOrCreateService(ServiceLocator locator, java.lang.Class<T> type, java.lang.annotation.Annotation... qualifiers) This method will first attempt to find a service corresponding to the type and qualifiers passed in to the method, and if one is found simply returns it.
static java.lang.String	getOneMetadataField(Descriptor d, java.lang.String field) Gets one value from a metadata field from the given descriptor
static java.lang.String	getOneMetadataField(ServiceHandle<?> h, java.lang.String field) Gets one value from a metadata field from the given service handle
static <T> T	getService(ServiceLocator locator, Descriptor descriptor) Returns the service in this service locator given the current descriptor.
static <T> T	getService(ServiceLocator locator, java.lang.String className) Returns the best service matching the passed in fully qualified class name of the service
static void	removeFilter(ServiceLocator locator, Filter filter) Removes all the descriptors from the given locator that match the given filter
static void	removeOneDescriptor(ServiceLocator locator, Descriptor descriptor) This method will attempt to remove descriptors matching the passed in descriptor from the given locator.

Methods inherited from class java.lang.Object

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

Constructor Detail

ServiceLocatorUtilities

public ServiceLocatorUtilities()

Method Detail

enablePerThreadScope

public static void enablePerThreadScope(ServiceLocator locator)

This method will add the ability to use the PerThread scope to the given locator. If the locator already has a Context implementation that handles the PerThread scope this method does nothing.

Parameters:

locator - The non-null locator to enable the PerThread scope on

Throws:

MultiException - if there were errors when committing the service

bind

public static void bind(ServiceLocator locator,
        Binder... binders)

This method will bind all of the binders given together in a single config transaction.

Parameters:

locator - The non-null locator to use for the configuration action

binders - The non-null list of binders to be added to the locator

Throws:

MultiException - if any error was encountered while binding services

bind

public static ServiceLocator bind(java.lang.String name,
                  Binder... binders)

This method will create or find a ServiceLocator with the given name and bind all of the binders given together in a single config transaction.

Parameters:

name - The non-null name of the locator to use for the configuration action

binders - The non-null list of binders to be added to the locator

Returns:

The service locator that was either found or created

Throws:

MultiException - if any error was encountered while binding services

bind

public static ServiceLocator bind(Binder... binders)

This method will create or find a ServiceLocator with the name "default" and bind all of the binders given together in a single config transaction.

Parameters:

binders - The non-null list of binders to be added to the locator

Returns:

The service locator that was either found or created

Throws:

MultiException - if any error was encountered while binding services

addOneConstant

public static <T> ActiveDescriptor<T> addOneConstant(ServiceLocator locator,
                                     java.lang.Object constant)

This method adds one existing object to the given service locator. The caller of this will not get a chance to customize the descriptor that goes into the locator, and hence must rely completely on the analysis of the system to determine the set of contracts and metadata associated with the descriptor. The same algorithm is used in this method as in the BuilderHelper.createConstantDescriptor(Object) method.

Parameters:

locator - The non-null locator to add this descriptor to

constant - The non-null constant to add to the service locator

Returns:

The descriptor that was added to the service locator

addOneConstant

public static <T> ActiveDescriptor<T> addOneConstant(ServiceLocator locator,
                                     java.lang.Object constant,
                                     java.lang.String name,
                                     java.lang.reflect.Type... contracts)

This method adds one existing object to the given service locator. The caller of this will not get a chance to customize the descriptor that goes into the locator, and hence must rely completely on the analysis of the system to determine the set of contracts and metadata associated with the descriptor. The same algorithm is used in this method as in the BuilderHelper.createConstantDescriptor(Object) method.

Parameters:

locator - The non-null locator to add this descriptor to

constant - The non-null constant to add to the service locator

name - The name this descriptor should take (may be null)

contracts - The full set of contracts this descriptor should take

Returns:

The descriptor that was added to the service locator

addOneDescriptor

public static <T> ActiveDescriptor<T> addOneDescriptor(ServiceLocator locator,
                                       Descriptor descriptor)

It is very often the case that one wishes to add a single descriptor to a service locator. This method adds that one descriptor. If the descriptor is an ActiveDescriptor and is reified, it will be added as an ActiveDescriptor. Otherwise it will be bound as a Descriptor. A deep copy will be made of the descriptor passed in

Parameters:

locator - The non-null locator to add this descriptor to

descriptor - The non-null descriptor to add to this locator

Throws:

MultiException - On a commit failure

addOneDescriptor

public static <T> ActiveDescriptor<T> addOneDescriptor(ServiceLocator locator,
                                       Descriptor descriptor,
                                       boolean requiresDeepCopy)

It is very often the case that one wishes to add a single descriptor to a service locator. This method adds that one descriptor. If the descriptor is an ActiveDescriptor and is reified, it will be added as an ActiveDescriptor. Otherwise it will be bound as a Descriptor.

Parameters:

locator - The non-null locator to add this descriptor to

descriptor - The non-null descriptor to add to this locator

requiresDeepCopy - If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking)

Throws:

MultiException - On a commit failure

findOneDescriptor

public static <T> ActiveDescriptor<T> findOneDescriptor(ServiceLocator locator,
                                        Descriptor descriptor)

Finds a descriptor in the given service locator. If the descriptor has the serviceId and locatorId set then it will first attempt to use those values to get the exact descriptor described by the input descriptor. Failing that (or if the input descriptor does not have those values set) then it will use the equals algorithm of to determine the equality of the descriptor.

Parameters:

locator - The non-null locator in which to find the descriptor

descriptor - The non-null descriptor to search for

Returns:

The descriptor as found in the locator, or null if no such descriptor could be found

removeOneDescriptor

public static void removeOneDescriptor(ServiceLocator locator,
                       Descriptor descriptor)

This method will attempt to remove descriptors matching the passed in descriptor from the given locator. If the descriptor has its locatorId and serviceId values set then only a descriptor matching those exact locatorId and serviceId will be removed. Otherwise any descriptor that returns true from the DescriptorImpl.equals(Object) method will be removed from the locator. Note that if more than one descriptor matches they will all be removed. Hence more than one descriptor may be removed by this method.

Parameters:

locator - The non-null locator to remove the descriptor from

descriptor - The non-null descriptor to remove from the locator

removeFilter

public static void removeFilter(ServiceLocator locator,
                Filter filter)

Removes all the descriptors from the given locator that match the given filter

Parameters:

locator - The non-null locator to remove the descriptors from

filter - The non-null filter which will determine what descriptors to remove

getService

public static <T> T getService(ServiceLocator locator,
               java.lang.String className)

Returns the best service matching the passed in fully qualified class name of the service

Parameters:

locator - The locator to find the service in

className - The fully qualified class name of the service

Returns:

The found service, or null if there is no service with this class name

getService

public static <T> T getService(ServiceLocator locator,
               Descriptor descriptor)

Returns the service in this service locator given the current descriptor.

Parameters:

locator - The non-null locator in which to get the service associated with this descriptor

descriptor - The non-null descriptor to find the corresponding service for

Returns:

createDynamicConfiguration

public static DynamicConfiguration createDynamicConfiguration(ServiceLocator locator)
                                                       throws java.lang.IllegalStateException

This method returns a DynamicConfiguration for use with adding and removing services to the given ServiceLocator.

Parameters:

locator - A non-null locator to get a DynamicConfiguration for

Returns:

A non-null DynamicConfiguration object that can be used to add or remove services to the passed in locator

Throws:

java.lang.IllegalStateException - If there was an error retrieving the DynamicConfigurationService for this locator

findOrCreateService

public static <T> T findOrCreateService(ServiceLocator locator,
                        java.lang.Class<T> type,
                        java.lang.annotation.Annotation... qualifiers)
                             throws MultiException

This method will first attempt to find a service corresponding to the type and qualifiers passed in to the method, and if one is found simply returns it. If no service is found in the locator this method will call ServiceLocator.createAndInitialize(Class) on the class (ignoring the qualifiers) in order to create an instance of the service.

Parameters:

locator - The service locator to search for the service with

type - The non-null type of object to either find or create

qualifiers - The set of qualifiers that should be associated with the service

Returns:

An instance of type as either found in the locator or automatically created, injected and post-constructed. Note that the return value CAN be null IF the service was found in the service locator and the context in which the service is in allows for null services.

Throws:

MultiException - On a failure from any of the underlying operations

getOneMetadataField

public static java.lang.String getOneMetadataField(Descriptor d,
                                   java.lang.String field)

Gets one value from a metadata field from the given descriptor

Parameters:

d - The non-null descriptor from which to get the first value in the given field

field - The non-null field to get the first value of

Returns:

The first value in the given field, or null if no such field exists in the descriptor

getOneMetadataField

public static java.lang.String getOneMetadataField(ServiceHandle<?> h,
                                   java.lang.String field)

Gets one value from a metadata field from the given service handle

Parameters:

h - The non-null service handle from which to get the first value in the given field

field - The non-null field to get the first value of

Returns:

The first value in the given field, or null if no such field exists in the descriptor