Package com.twelvemonkeys.util.service

Class ServiceRegistry

java.lang.Object

com.twelvemonkeys.util.service.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.

Field Summary

Fields

Modifier and Type	Field	Description
private java.util.Map<java.lang.Class<?>,ServiceRegistry.CategoryRegistry>	categoryMap
static java.lang.String	SERVICES	"META-INF/services/"

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

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

Field Detail

SERVICES

public static final java.lang.String SERVICES

"META-INF/services/"

See Also:

Constant Field Values

categoryMap

private final java.util.Map<java.lang.Class<?>,ServiceRegistry.CategoryRegistry> categoryMap

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

putCategory

private <T> void putCategory(java.util.Map<java.lang.Class<?>,ServiceRegistry.CategoryRegistry> pMap,
                             java.lang.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(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)