Class ServiceLocatorUtilities
ServiceLocator
.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
private static class
private static class
private static class
private static class
private static class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final String
private static final Immediate
private static final InheritableThread
private static final PerLookup
private static final PerThread
private static final javax.inject.Singleton
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic 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 locatorstatic List
<FactoryDescriptors> addFactoryDescriptors
(ServiceLocator locator, FactoryDescriptors... factories) Adds the given factory descriptors to the service locatorstatic <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
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 void
bind
(ServiceLocator locator, Binder... binders) This method will bind all of the binders given together in a single config transaction.static ServiceLocator
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 ServiceLocator
This method is often the first line of a stand-alone client that wishes to use HK2.static ServiceLocator
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 aDynamicConfiguration
for use with adding and removing services to the givenServiceLocator
.static void
dumpAllDescriptors
(ServiceLocator locator) Dumps all descriptors in this ServiceLocator to stderrstatic void
dumpAllDescriptors
(ServiceLocator locator, PrintStream output) Dumps all descriptors in this ServiceLocator to the given PrintStreamstatic void
enableGreedyResolution
(ServiceLocator locator) Enables greedy service resolution in this service locator by adding theGreedyResolver
into the service locator.static void
enableImmediateScope
(ServiceLocator locator) This method will add the ability to use theImmediate
scope to the given locator.static ImmediateController
This method will add the ability to use theImmediate
scope to the given locator.static void
This method will add the ability to use theInheritableThread
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 thePerThread
scope to the given locator.static void
enableTopicDistribution
(ServiceLocator locator) Deprecated.Use ExtrasUtilities.enableTopicDistribution.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.(package private) static String
static Immediate
Returns aImmediate
Annotation
implementationstatic InheritableThread
Returns aInheritableThread
Annotation
implementationstatic String
getOneMetadataField
(Descriptor d, String field) Gets one value from a metadata field from the given descriptorstatic String
getOneMetadataField
(ServiceHandle<?> h, String field) Gets one value from a metadata field from the given service handlestatic PerLookup
Returns aPerLookup
Annotation
implementationstatic PerThread
Returns aPerThread
Annotation
implementationstatic <T> T
getService
(ServiceLocator locator, String className) Returns the best service matching the passed in fully qualified class name of the servicestatic <T> T
getService
(ServiceLocator locator, Descriptor descriptor) Returns the service in this service locator given the current descriptor.static javax.inject.Singleton
Returns aSingleton
Annotation
implementationprivate static boolean
static void
removeFilter
(ServiceLocator locator, Filter filter) Removes all the descriptors from the given locator that match the given filterstatic void
removeFilter
(ServiceLocator locator, Filter filter, boolean includeAliasDescriptors) Removes all the descriptors from the given locator that match the given filterstatic 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.
-
Field Details
-
DEFAULT_LOCATOR_NAME
- See Also:
-
SINGLETON
private static final javax.inject.Singleton SINGLETON -
PER_LOOKUP
-
PER_THREAD
-
INHERITABLE_THREAD
-
IMMEDIATE
-
-
Constructor Details
-
ServiceLocatorUtilities
public ServiceLocatorUtilities()
-
-
Method Details
-
enablePerThreadScope
This method will add the ability to use thePerThread
scope to the given locator. If the locator already has aContext
implementation that handles thePerThread
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
This method will add the ability to use theInheritableThread
scope to the given locator. If the locator already has aContext
implementation that handles theInheritableThread
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
This method will add the ability to use theImmediate
scope to the given locator. If the locator already has aContext
implementation that handles theImmediate
scope this method does nothing.This implementation of
Immediate
scope will use a separate thread for instantiating services. Any failures fromImmediate
scoped services will be given to the current set ofImmediateErrorHandler
implementations- Parameters:
locator
- The non-null locator to enable the Immediate scope on- Throws:
MultiException
- if there were errors when committing the service
-
enableImmediateScopeSuspended
This method will add the ability to use theImmediate
scope to the given locator. If the locator already has aContext
implementation that handles theImmediate
scope this method does nothing. The Immediate scope will start in the suspended state, allowing the caller to customize the Immediate scope using theImmediateController
- 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
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 actionbinders
- The non-null list of binders to be added to the locator- Throws:
MultiException
- if any error was encountered while binding services
-
bind
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 actionbinders
- 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
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
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 theBuilderHelper.createConstantDescriptor(Object)
method.- Parameters:
locator
- The non-null locator to add this descriptor toconstant
- 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 toconstants
- 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 theBuilderHelper.createConstantDescriptor(Object)
method.- Parameters:
locator
- The non-null locator to add this descriptor toconstant
- The non-null constant to add to the service locatorname
- 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 anActiveDescriptor
and is reified, it will be added as anActiveDescriptor
. Otherwise it will be bound as aDescriptor
. A deep copy will be made of the descriptor passed in- Parameters:
locator
- The non-null locator to add this descriptor todescriptor
- 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 anActiveDescriptor
and is reified, it will be added as anActiveDescriptor
. Otherwise it will be bound as aDescriptor
.- Parameters:
locator
- The non-null locator to add this descriptor todescriptor
- The non-null descriptor to add to this locatorrequiresDeepCopy
- 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 nullfactories
- 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 nullrequiresDeepCopy
- This is false ONLY if every one of the factories given to this method can be used without a copyfactories
- 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 theFactory
class itself, and one for theFactory.provide()
method of the factory. In the output list the descriptor for theFactory
will be added first, followed by the descriptor for theFactory.provide()
method- Parameters:
locator
- The non-null locator to add this descriptor totoAdd
- The classes to add to the locator. If a class in this list implementsFactory
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
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 theFactory
class itself, and one for theFactory.provide()
method of the factory. In the output list the descriptor for theFactory
will be added first, followed by the descriptor for theFactory.provide()
method- Parameters:
locator
- The non-null locator to add this descriptor totoAdd
- The classes to add to the locator. If a class in this list implementsFactory
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
-
getBestContract
-
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 theDescriptorImpl
to determine the equality of the descriptor.- Parameters:
locator
- The non-null locator in which to find the descriptordescriptor
- 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
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 theDescriptorImpl.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 fromdescriptor
- 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 theDescriptorImpl.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 fromdescriptor
- The non-null descriptor to remove from the locatorincludeAliasDescriptors
- If set to true allAliasDescriptor
s that point to any descriptors found by filter will also be removed
-
removeFilter
Removes all the descriptors from the given locator that match the given filter- Parameters:
locator
- The non-null locator to remove the descriptors fromfilter
- 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 fromfilter
- The non-null filter which will determine what descriptors to removeincludeAliasDescriptors
- If set to true allAliasDescriptor
s that point to any descriptors found by filter will also be removed
-
getService
Returns the best service matching the passed in fully qualified class name of the service- Parameters:
locator
- The locator to find the service inclassName
- The fully qualified class name of the service- Returns:
- The found service, or null if there is no service with this class name
-
getService
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 descriptordescriptor
- 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 aDynamicConfiguration
for use with adding and removing services to the givenServiceLocator
.- 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 theDynamicConfigurationService
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 callServiceLocator.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 withtype
- The non-null type of object to either find or createqualifiers
- 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
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 fieldfield
- 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
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 fieldfield
- 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
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 withServiceLocatorFactory.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
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
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 addingRethrowErrorService
to the service registryDo 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
Enables greedy service resolution in this service locator by adding theGreedyResolver
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
Deprecated.Use ExtrasUtilities.enableTopicDistribution. This method WILL BE REMOVED in the next version of hk2This 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
Dumps all descriptors in this ServiceLocator to stderr- Parameters:
locator
- The non-null locator to dump to stderr
-
dumpAllDescriptors
Dumps all descriptors in this ServiceLocator to the given PrintStream- Parameters:
locator
- The non-null locator to dumpoutput
- The non-null PrintStream to print the descriptors to
-
getSingletonAnnotation
public static javax.inject.Singleton getSingletonAnnotation()Returns aSingleton
Annotation
implementation- Returns:
- a
Singleton
Annotation
implementation
-
getPerLookupAnnotation
Returns aPerLookup
Annotation
implementation- Returns:
- a
PerLookup
Annotation
implementation
-
getPerThreadAnnotation
Returns aPerThread
Annotation
implementation- Returns:
- a
PerThread
Annotation
implementation
-
getInheritableThreadAnnotation
Returns aInheritableThread
Annotation
implementation- Returns:
- a
InheritableThread
Annotation
implementation
-
getImmediateAnnotation
Returns aImmediate
Annotation
implementation- Returns:
- a
Immediate
Annotation
implementation
-
isDupException
-