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

Author:

Harald Kuhr

See Also:

RegisterableService, JAR File Specification

Field Summary

static String

SERVICES "META-INF/services/"

Constructor Summary

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

Method Summary

protected Iterator<Class<?>>	categories() Returns an Iterator containing all categories in this registry.
protected Iterator<Class<?>>	compatibleCategories(Object pProvider) Returns an Iterator containing all categories in this registry the given pProvider may be registered with.
protected Iterator<Class<?>>	containingCategories(Object pProvider) Returns an Iterator containing all categories in this registry the given pProvider is currently registered with.
boolean	deregister(Object pProvider) De-registers the given provider from all categories it's currently registered in.
boolean	deregister(Object pProvider, Class<?> pCategory) Deregisters the given provider from the given category.
static void	main(String[] pArgs)
protected <T> Iterator<T>	providers(Class<T> pCategory) Returns an Iterator containing all providers in the given category.
boolean	register(Object pProvider) Registers the given provider for all categories it matches.
<T> boolean	register(T pProvider, 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SERVICES

public static final String SERVICES

"META-INF/services/"

See Also:

Constant Field Values

Constructor Detail

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 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

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

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:

compatibleCategories(Object)

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:

containingCategories(Object)

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)