Module org.glassfish.hk2.api
Package 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 Details

    • ServiceLocatorUtilities

      public ServiceLocatorUtilities()

  • Method Details

    • 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

    • 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 jakarta.inject.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