Class ServiceRegistry

java.lang.Object
com.twelvemonkeys.util.service.ServiceRegistry

public class ServiceRegistry extends 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:
  • Field Details

  • Constructor Details

    • ServiceRegistry

      public ServiceRegistry(Iterator<? extends 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:
      IllegalArgumentException - if pCategories is null.
      ClassCastException - if pCategories contains anything but Class objects.
  • Method Details

    • putCategory

      private <T> void putCategory(Map<Class<?>,ServiceRegistry.CategoryRegistry> pMap, Class<T> pCategory)
    • 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(URL pResource, Class<T> pCategory, 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> Iterator<T> providers(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:
      IllegalArgumentException - if pCategory is not a valid category in this registry
    • categories

      protected Iterator<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 Iterator<Class<?>> compatibleCategories(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 Iterator<Class<?>> containingCategories(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(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(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:
    • registerImpl

      private <T> boolean registerImpl(Object pProvider, Class<T> pCategory)
    • register

      public <T> boolean register(T pProvider, 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(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:
    • deregister

      public boolean deregister(Object pProvider, 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(String[] pArgs)