Class ServiceRegistry


  • public class ServiceRegistry
    extends java.lang.Object
    A registry for service provider objects.

    Service providers are looked up from the classpath, under the path META-INF/services/<full-class-name>.

    For example:
    META-INF/services/com.company.package.spi.MyService.

    The file should contain a list of fully-qualified concrete class names, one per line.

    The full-class-name represents an interface or (typically) an abstract class, and is the same class used as the category for this registry. Note that only one instance of a concrete subclass may be registered with a specific category at a time.

    Implementation detail: This class is a clean room implementation of a service registry and does not use the proprietary sun.misc.Service class that is referred to in the JAR File specification. This class should work on any Java platform.

    Version:
    $Id: com/twelvemonkeys/util/service/ServiceRegistry.java#2 $
    See Also:
    RegisterableService, JAR File Specification
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) class  ServiceRegistry.CategoryRegistry<T>
      Keeps track of each individual category.
    • Constructor Summary

      Constructors 
      Constructor Description
      ServiceRegistry​(java.util.Iterator<? extends java.lang.Class<?>> pCategories)
      Creates a ServiceRegistry instance with a set of categories taken from the pCategories argument.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected java.util.Iterator<java.lang.Class<?>> categories()
      Returns an Iterator containing all categories in this registry.
      protected java.util.Iterator<java.lang.Class<?>> compatibleCategories​(java.lang.Object pProvider)
      Returns an Iterator containing all categories in this registry the given pProvider may be registered with.
      protected java.util.Iterator<java.lang.Class<?>> containingCategories​(java.lang.Object pProvider)
      Returns an Iterator containing all categories in this registry the given pProvider is currently registered with.
      boolean deregister​(java.lang.Object pProvider)
      De-registers the given provider from all categories it's currently registered in.
      boolean deregister​(java.lang.Object pProvider, java.lang.Class<?> pCategory)
      Deregisters the given provider from the given category.
      private <T> ServiceRegistry.CategoryRegistry<T> getRegistry​(java.lang.Class<T> pCategory)
      Gets the category registry for the given category.
      static void main​(java.lang.String[] pArgs)  
      protected <T> java.util.Iterator<T> providers​(java.lang.Class<T> pCategory)
      Returns an Iterator containing all providers in the given category.
      private <T> void putCategory​(java.util.Map<java.lang.Class<?>,​ServiceRegistry.CategoryRegistry> pMap, java.lang.Class<T> pCategory)  
      boolean register​(java.lang.Object pProvider)
      Registers the given provider for all categories it matches.
      <T> boolean register​(T pProvider, java.lang.Class<? super T> pCategory)
      Registers the given provider for the given category.
      void registerApplicationClasspathSPIs()
      Registers all provider implementations for this ServiceRegistry found in the application classpath.
      private <T> boolean registerImpl​(java.lang.Object pProvider, java.lang.Class<T> pCategory)  
      (package private) <T> void registerSPIs​(java.net.URL pResource, java.lang.Class<T> pCategory, java.lang.ClassLoader pLoader)
      Registers all SPIs listed in the given resource.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ServiceRegistry

        public ServiceRegistry​(java.util.Iterator<? extends java.lang.Class<?>> pCategories)
        Creates a ServiceRegistry instance with a set of categories taken from the pCategories argument.

        The categories are constant during the lifetime of the registry, and may not be changed after initial creation.

        Parameters:
        pCategories - an Iterator containing Class objects that defines this registry's categories.
        Throws:
        java.lang.IllegalArgumentException - if pCategories is null.
        java.lang.ClassCastException - if pCategories contains anything but Class objects.
    • Method Detail

      • registerApplicationClasspathSPIs

        public void registerApplicationClasspathSPIs()
        Registers all provider implementations for this ServiceRegistry found in the application classpath.
        Throws:
        ServiceConfigurationError - if an error occurred during registration
      • registerSPIs

        <T> void registerSPIs​(java.net.URL pResource,
                              java.lang.Class<T> pCategory,
                              java.lang.ClassLoader pLoader)
        Registers all SPIs listed in the given resource.
        Parameters:
        pResource - the resource to load SPIs from
        pCategory - the category class
        pLoader - the class loader to use
      • providers

        protected <T> java.util.Iterator<T> providers​(java.lang.Class<T> pCategory)
        Returns an Iterator containing all providers in the given category.

        The iterator supports removal.

        NOTE: Removing a provider from the iterator, deregisters the current provider (as returned by the last invocation of next()) from pCategory, it does not remove the provider from other categories in the registry.

        Parameters:
        pCategory - the category class
        Returns:
        an Iterator containing all providers in the given category.
        Throws:
        java.lang.IllegalArgumentException - if pCategory is not a valid category in this registry
      • categories

        protected java.util.Iterator<java.lang.Class<?>> categories()
        Returns an Iterator containing all categories in this registry.

        The iterator does not support removal.

        Returns:
        an Iterator containing all categories in this registry.
      • compatibleCategories

        protected java.util.Iterator<java.lang.Class<?>> compatibleCategories​(java.lang.Object pProvider)
        Returns an Iterator containing all categories in this registry the given pProvider may be registered with.

        The iterator does not support removal.

        Parameters:
        pProvider - the provider instance
        Returns:
        an Iterator containing all categories in this registry the given pProvider may be registered with
      • containingCategories

        protected java.util.Iterator<java.lang.Class<?>> containingCategories​(java.lang.Object pProvider)
        Returns an Iterator containing all categories in this registry the given pProvider is currently registered with.

        The iterator supports removal.

        NOTE: Removing a category from the iterator, de-registers pProvider from the current category (as returned by the last invocation of next()), it does not remove the category itself from the registry.

        Parameters:
        pProvider - the provider instance
        Returns:
        an Iterator containing all categories in this registry the given pProvider may be registered with
      • getRegistry

        private <T> ServiceRegistry.CategoryRegistry<T> getRegistry​(java.lang.Class<T> pCategory)
        Gets the category registry for the given category.
        Parameters:
        pCategory - the category class
        Returns:
        the CategoryRegistry for the given category
      • register

        public boolean register​(java.lang.Object pProvider)
        Registers the given provider for all categories it matches.
        Parameters:
        pProvider - the provider instance
        Returns:
        true if pProvider is now registered in one or more categories it was not registered in before.
        See Also:
        compatibleCategories(Object)
      • registerImpl

        private <T> boolean registerImpl​(java.lang.Object pProvider,
                                         java.lang.Class<T> pCategory)
      • register

        public <T> boolean register​(T pProvider,
                                    java.lang.Class<? super T> pCategory)
        Registers the given provider for the given category.
        Parameters:
        pProvider - the provider instance
        pCategory - the category class
        Returns:
        true if pProvider is now registered in the given category
      • deregister

        public boolean deregister​(java.lang.Object pProvider)
        De-registers the given provider from all categories it's currently registered in.
        Parameters:
        pProvider - the provider instance
        Returns:
        true if pProvider was previously registered in any category and is now de-registered.
        See Also:
        containingCategories(Object)
      • deregister

        public boolean deregister​(java.lang.Object pProvider,
                                  java.lang.Class<?> pCategory)
        Deregisters the given provider from the given category.
        Parameters:
        pProvider - the provider instance
        pCategory - the category class
        Returns:
        true if pProvider was previously registered in the given category
      • main

        public static void main​(java.lang.String[] pArgs)