Class ServiceLocatorUtilities


  • public abstract class ServiceLocatorUtilities
    extends Object
    This is a set of useful utilities for working with ServiceLocator.
    Author:
    jwells
    • 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
      • 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 javax.inject.Singleton getSingletonAnnotation()
        Returns a Singleton Annotation implementation
        Returns:
        a Singleton Annotation implementation