org.glassfish.hk2.utilities

Class ServiceLocatorUtilities

java.lang.Object

org.glassfish.hk2.utilities.ServiceLocatorUtilities

public abstract class ServiceLocatorUtilities
extends Object

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

Author:

jwells

Constructor Summary

Constructors

Constructor and Description
ServiceLocatorUtilities()

Method Summary

Modifier and Type	Method and Description
static List<ActiveDescriptor<?>>	addClasses(ServiceLocator locator, boolean idempotent, Class<?>... toAdd) It is very often the case that one wishes to add classes that hk2 will automatically analyze for contracts and qualifiers to a service locator.
static List<ActiveDescriptor<?>>	addClasses(ServiceLocator locator, Class<?>... toAdd) It is very often the case that one wishes to add classes that hk2 will automatically analyze for contracts and qualifiers to a service locator.
static List<FactoryDescriptors>	addFactoryConstants(ServiceLocator locator, Factory<?>... constants) This method adds factory constants to the given locator.
static List<FactoryDescriptors>	addFactoryDescriptors(ServiceLocator locator, boolean requiresDeepCopy, FactoryDescriptors... factories) Adds the given factory descriptors to the service locator
static List<FactoryDescriptors>	addFactoryDescriptors(ServiceLocator locator, FactoryDescriptors... factories) Adds the given factory descriptors to the service locator
static <T> ActiveDescriptor<T>	addOneConstant(ServiceLocator locator, Object constant) This method adds one existing object to the given service locator.
static <T> ActiveDescriptor<T>	addOneConstant(ServiceLocator locator, Object constant, String name, 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(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 ServiceLocator	createAndPopulateServiceLocator() This method is often the first line of a stand-alone client that wishes to use HK2.
static ServiceLocator	createAndPopulateServiceLocator(String name) This method is often the first line of a stand-alone client that wishes to use HK2.
static DynamicConfiguration	createDynamicConfiguration(ServiceLocator locator) This method returns a DynamicConfiguration for use with adding and removing services to the given ServiceLocator.
static void	dumpAllDescriptors(ServiceLocator locator) Dumps all descriptors in this ServiceLocator to stderr
static void	dumpAllDescriptors(ServiceLocator locator, PrintStream output) Dumps all descriptors in this ServiceLocator to the given PrintStream
static void	enableGreedyResolution(ServiceLocator locator) Enables greedy service resolution in this service locator by adding the GreedyResolver into the service locator.
static void	enableImmediateScope(ServiceLocator locator) This method will add the ability to use the Immediate scope to the given locator.
static ImmediateController	enableImmediateScopeSuspended(ServiceLocator locator) This method will add the ability to use the Immediate scope to the given locator.
static void	enableInheritableThreadScope(ServiceLocator locator) This method will add the ability to use the InheritableThread scope to the given locator.
static void	enableLookupExceptions(ServiceLocator locator) This method will cause lookup operations to throw exceptions when exceptions are encountered in underlying operations such as classloading.
static void	enablePerThreadScope(ServiceLocator locator) This method will add the ability to use the PerThread scope to the given locator.
static void	enableTopicDistribution(ServiceLocator locator) Deprecated. Use ExtrasUtilities.enableTopicDistribution. This method WILL BE REMOVED in the next version of hk2
static <T> ActiveDescriptor<T>	findOneDescriptor(ServiceLocator locator, Descriptor descriptor) Finds a descriptor in the given service locator.
static <T> T	findOrCreateService(ServiceLocator locator, Class<T> type, 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 Immediate	getImmediateAnnotation() Returns a Immediate Annotation implementation
static InheritableThread	getInheritableThreadAnnotation() Returns a InheritableThread Annotation implementation
static String	getOneMetadataField(Descriptor d, String field) Gets one value from a metadata field from the given descriptor
static String	getOneMetadataField(ServiceHandle<?> h, String field) Gets one value from a metadata field from the given service handle
static PerLookup	getPerLookupAnnotation() Returns a PerLookup Annotation implementation
static PerThread	getPerThreadAnnotation() Returns a PerThread Annotation implementation
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, String className) Returns the best service matching the passed in fully qualified class name of the service
static Singleton	getSingletonAnnotation() Returns a Singleton Annotation implementation
static void	removeFilter(ServiceLocator locator, Filter filter) Removes all the descriptors from the given locator that match the given filter
static void	removeFilter(ServiceLocator locator, Filter filter, boolean includeAliasDescriptors) 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.
static void	removeOneDescriptor(ServiceLocator locator, Descriptor descriptor, boolean includeAliasDescriptors) 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

enableInheritableThreadScope

public static void enableInheritableThreadScope(ServiceLocator locator)

This method will add the ability to use the InheritableThread scope to the given locator. If the locator already has a Context implementation that handles the InheritableThread 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

enableImmediateScope

public static void enableImmediateScope(ServiceLocator locator)

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

This implementation of Immediate scope will use a separate thread for instantiating services. Any failures from Immediate scoped services will be given to the current set of ImmediateErrorHandler implementations

Parameters:

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

Throws:

MultiException - if there were errors when committing the service

enableImmediateScopeSuspended

public static ImmediateController enableImmediateScopeSuspended(ServiceLocator locator)

This method will add the ability to use the Immediate scope to the given locator. If the locator already has a Context implementation that handles the Immediate scope this method does nothing. The Immediate scope will start in the suspended state, allowing the caller to customize the Immediate scope using the ImmediateController

Parameters:

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

Returns:

The ImmediateController that can be used to further configure the Immediate scope

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(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,
                                                     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

addFactoryConstants

public static List<FactoryDescriptors> addFactoryConstants(ServiceLocator locator,
                                                           Factory<?>... constants)

This method adds factory constants to the given locator. None of the constants may be null. The returned list will contain the FactoryDescriptors added to the locator. So while the factories are constant valued, the provide method return values are NOT, and will be invoked according to their normal hk2 lifecycle

Parameters:

locator - The non-null locator to add these factory constants to

constants - The constant factories to add to the locator. None of the constants in this array may be null

Returns:

The descriptors that were added to the service locator. Will not return null, but may return an empty list (if the constants array was zero length)

addOneConstant

public static <T> ActiveDescriptor<T> addOneConstant(ServiceLocator locator,
                                                     Object constant,
                                                     String name,
                                                     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. If this field is the empty set then the contracts will be automatically discovered

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

Returns:

The descriptor that was added to the system

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)

Returns:

The descriptor that was added to the system

Throws:

MultiException - On a commit failure

addFactoryDescriptors

public static List<FactoryDescriptors> addFactoryDescriptors(ServiceLocator locator,
                                                             FactoryDescriptors... factories)

Adds the given factory descriptors to the service locator

Parameters:

locator - The locator to add the factories to. May not be null

factories - The list of factory descriptors to add to the system. May not be null

Returns:

a list of the FactoryDescriptor descriptors that were added to the service locator

Throws:

MultiException - On a commit failure

addFactoryDescriptors

public static List<FactoryDescriptors> addFactoryDescriptors(ServiceLocator locator,
                                                             boolean requiresDeepCopy,
                                                             FactoryDescriptors... factories)

Adds the given factory descriptors to the service locator

Parameters:

locator - The locator to add the factories to. May not be null

requiresDeepCopy - This is false ONLY if every one of the factories given to this method can be used without a copy

factories - The list of factory descriptors to add to the system. May not be null

Returns:

A list of the FactoryDescriptor descriptors that were added to the service locator

Throws:

MultiException - On a commit failure

addClasses

public static List<ActiveDescriptor<?>> addClasses(ServiceLocator locator,
                                                   boolean idempotent,
                                                   Class<?>... toAdd)

It is very often the case that one wishes to add classes that hk2 will automatically analyze for contracts and qualifiers to a service locator. This method adds those classes.

If the class to add implements Factory then two descriptors will be added, one for the Factory class itself, and one for the Factory.provide() method of the factory. In the output list the descriptor for the Factory will be added first, followed by the descriptor for the Factory.provide() method

Parameters:

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

toAdd - The classes to add to the locator. If a class in this list implements Factory then two descriptors will be added for that class

Returns:

The list of descriptors added to the system. Will not return null but may return an empty list

Throws:

MultiException - On a commit failure. If idempotent is true the commit failure may be due to duplicate descriptors found in the locator

addClasses

public static List<ActiveDescriptor<?>> addClasses(ServiceLocator locator,
                                                   Class<?>... toAdd)

It is very often the case that one wishes to add classes that hk2 will automatically analyze for contracts and qualifiers to a service locator. This method adds those classes.

If the class to add implements Factory then two descriptors will be added, one for the Factory class itself, and one for the Factory.provide() method of the factory. In the output list the descriptor for the Factory will be added first, followed by the descriptor for the Factory.provide() method

Parameters:

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

toAdd - The classes to add to the locator. If a class in this list implements Factory then two descriptors will be added for that class

Returns:

The list of descriptors added to the system. Will not return null but may return an empty list

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 the DescriptorImpl 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

removeOneDescriptor

public static void removeOneDescriptor(ServiceLocator locator,
                                       Descriptor descriptor,
                                       boolean includeAliasDescriptors)

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

includeAliasDescriptors - If set to true all AliasDescriptors that point to any descriptors found by filter will also be removed

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

removeFilter

public static void removeFilter(ServiceLocator locator,
                                Filter filter,
                                boolean includeAliasDescriptors)

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

includeAliasDescriptors - If set to true all AliasDescriptors that point to any descriptors found by filter will also be removed

getService

public static <T> T getService(ServiceLocator locator,
                               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:

The service object

createDynamicConfiguration

public static DynamicConfiguration createDynamicConfiguration(ServiceLocator locator)
                                                       throws 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:

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

findOrCreateService

public static <T> T findOrCreateService(ServiceLocator locator,
                                        Class<T> type,
                                        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 String getOneMetadataField(Descriptor d,
                                         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 String getOneMetadataField(ServiceHandle<?> h,
                                         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

createAndPopulateServiceLocator

public static ServiceLocator createAndPopulateServiceLocator(String name)
                                                      throws MultiException

This method is often the first line of a stand-alone client that wishes to use HK2. It creates a ServiceLocator with the given name (or a randomly generated name if null is passed in) and then populates that service locator with services found in the META-INF/hk2-locator/default files that can be found with the classloader that loaded HK2 (usually the system classloader).

Parameters:

name - The name of the service locator to create. If there is already a service locator of this name this method will use that one to populate. If this is null a randomly assigned name will be given to the service locator, and it will not be tracked by the system. If this is NOT null then this service locator can be found with ServiceLocatorFactory.find(String).

Returns:

A service locator that has been populated with services

Throws:

MultiException - If there was a failure when populating or creating the ServiceLocator

createAndPopulateServiceLocator

public static ServiceLocator createAndPopulateServiceLocator()

This method is often the first line of a stand-alone client that wishes to use HK2. It creates a ServiceLocator with a randomly generated name and then populates that service locator with services found in the META-INF/hk2-locator/default files that can be found with the classloader that loaded HK2 (usually the system classloader).

Returns:

A service locator that has been populated with services

Throws:

MultiException - If there was a failure when populating or creating the ServiceLocator

enableLookupExceptions

public static void enableLookupExceptions(ServiceLocator locator)

This method will cause lookup operations to throw exceptions when exceptions are encountered in underlying operations such as classloading. This method is idempotent. This method works by adding RethrowErrorService to the service registry

Do not use this methods in secure applications where callers to lookup should not be given the information that they do NOT have access to a service

Parameters:

locator - The service locator to enable lookup exceptions on. May not be null

enableGreedyResolution

public static void enableGreedyResolution(ServiceLocator locator)

Enables greedy service resolution in this service locator by adding the GreedyResolver into the service locator. This method is idempotent.

WARNING: Use of greedy resolution may cause classes that were not intended to be instantiated by hk2 to be instantiated by hk2. Please use this with care

Parameters:

locator - The locator to enable for greedy resolution

enableTopicDistribution

public static void enableTopicDistribution(ServiceLocator locator)

Deprecated. Use ExtrasUtilities.enableTopicDistribution. This method WILL BE REMOVED in the next version of hk2

This method will enable the default topic distribution service.

The default distribution service distributes messages on the same thread as the caller of Topic.publish(Object) and (TBD security policy). Objects to be distributed to will be held with SoftReferences, and hence if they go out of scope they will not be distributed to. Only services created AFTER the topic distribution service is enabled will be distributed to.

This method is idempotent, so that if there is already a TopicDistributionService with the default name is available this method will do nothing

Parameters:

locator - The service locator to enable topic distribution on. May not be null

dumpAllDescriptors

public static void dumpAllDescriptors(ServiceLocator locator)

Dumps all descriptors in this ServiceLocator to stderr

Parameters:

locator - The non-null locator to dump to stderr

dumpAllDescriptors

public static void dumpAllDescriptors(ServiceLocator locator,
                                      PrintStream output)

Dumps all descriptors in this ServiceLocator to the given PrintStream

Parameters:

locator - The non-null locator to dump

output - The non-null PrintStream to print the descriptors to

getSingletonAnnotation

public static Singleton getSingletonAnnotation()

Returns a Singleton Annotation implementation

Returns:

a Singleton Annotation implementation

getPerLookupAnnotation

public static PerLookup getPerLookupAnnotation()

Returns a PerLookup Annotation implementation

Returns:

a PerLookup Annotation implementation

getPerThreadAnnotation

public static PerThread getPerThreadAnnotation()

Returns a PerThread Annotation implementation

Returns:

a PerThread Annotation implementation

getInheritableThreadAnnotation

public static InheritableThread getInheritableThreadAnnotation()

Returns a InheritableThread Annotation implementation

Returns:

a InheritableThread Annotation implementation

getImmediateAnnotation

public static Immediate getImmediateAnnotation()

Returns a Immediate Annotation implementation

Returns:

a Immediate Annotation implementation