javax.imageio.spi

Class ServiceRegistry

public class ServiceRegistry extends Object

A registry for service providers.

Since: 1.4

Nested Class Summary
static interface	ServiceRegistry.Filter A filter for selecting service providers that match custom criteria.

Constructor Summary
	ServiceRegistry(Iterator<Class<?>> categories) Constructs a `ServiceRegistry` for the specified service categories.

Method Summary
boolean	contains(Object provider) Determines whether a provider has been registered with this registry.
void	deregisterAll(Class<?> category) De-registers all providers which have been registered for the specified service category.
void	deregisterAll() De-registers all service providers.
<T> boolean	deregisterServiceProvider(T provider, Class<T> category) De-registers a provider for the specified service category.
void	deregisterServiceProvider(Object provider) De-registers a provider from all service categories it implements.
void	finalize() Called by the Virtual Machine when it detects that this `ServiceRegistry` has become garbage.
Iterator<Class<?>>	getCategories() Returns an iterator over all service categories.
<T> T	getServiceProviderByClass(Class<T> providerClass) Returns one of the service providers that is a subclass of the specified class.
<T> Iterator<T>	getServiceProviders(Class<T> category, boolean useOrdering) Retrieves all providers that have been registered for the specified service category.
<T> Iterator<T>	getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering) Retrieves all providers that have been registered for the specified service category and that satisfy the criteria of a custom filter.
static <T> Iterator<T>	lookupProviders(Class<T> spi, ClassLoader loader) Finds service providers that are implementing the specified Service Provider Interface.
static <T> Iterator<T>	lookupProviders(Class<T> spi) Finds service providers that are implementing the specified Service Provider Interface, using the context class loader for loading providers.
<T> boolean	registerServiceProvider(T provider, Class<T> category) Registers a provider for the specified service category.
void	registerServiceProvider(Object provider) Registers a provider under all service categories it implements.
void	registerServiceProviders(Iterator<?> providers) Registers a number of providers under all service categories they implement.
<T> boolean	setOrdering(Class<T> category, T firstProvider, T secondProvider) Adds an ordering constraint on service providers.
<T> boolean	unsetOrdering(Class<T> category, T firstProvider, T secondProvider) Removes an ordering constraint on service providers.

Constructor Detail

ServiceRegistry

public ServiceRegistry(Iterator<Class<?>> categories)

Constructs a ServiceRegistry for the specified service categories.

Parameters: categories the categories to support

Throws: IllegalArgumentException if categories is null, or if its {@link Iterator#next()} method returns null. ClassCastException if categories does not iterate over instances of {@link java.lang.Class}.

Method Detail

contains

public boolean contains(Object provider)

Determines whether a provider has been registered with this registry.

Returns: true if provider has been registered under any service category; false if it is not registered.

Throws: IllegalArgumentException if provider is null.

deregisterAll

public void deregisterAll(Class<?> category)

De-registers all providers which have been registered for the specified service category.

If a provider implements the {@link RegisterableService} interface, its {@link RegisterableService#onDeregistration onDeregistration} method is invoked in order to inform the provider about the removal from this registry. If the provider implements several service categories, onDeregistration gets called multiple times.

Parameters: category the category whose registered providers will be de-registered.

Throws: IllegalArgumentException if category is not among the categories passed to the {@linkplain #ServiceRegistry(Iterator) constructor} of this ServiceRegistry.

deregisterAll

public void deregisterAll()

De-registers all service providers.

deregisterServiceProvider

public <T> boolean deregisterServiceProvider(T provider, Class<T> category)

De-registers a provider for the specified service category.

Parameters: provider the service provider to be de-registered. category the service category from which provider shall be de-registered.

Returns: true if provider was previously registered for the specified service category; false if if the provider had not been registered.

Throws: IllegalArgumentException if provider is null, or if category is not among the categories passed to the {@linkplain #ServiceRegistry(Iterator) constructor} of this ServiceRegistry. ClassCastException if provider does not implement category.

deregisterServiceProvider

public void deregisterServiceProvider(Object provider)

De-registers a provider from all service categories it implements.

If provider implements the {@link RegisterableService} interface, its {@link RegisterableService#onDeregistration onDeregistration} method is invoked in order to inform the provider about the removal from this registry. If provider implements several service categories, onDeregistration gets called multiple times.

Parameters: provider the service provider to be de-registered.

Throws: IllegalArgumentException if provider is null, or if provider does not implement any of the service categories passed to the {@linkplain #ServiceRegistry(Iterator) constructor} of this ServiceRegistry.

finalize

public void finalize()

Called by the Virtual Machine when it detects that this ServiceRegistry has become garbage. De-registers all service providers, which will cause those that implement {@link RegisterableService} to receive a {@link RegisterableService#onDeregistration onDeregistration} notification.

getCategories

public Iterator<Class<?>> getCategories()

Returns an iterator over all service categories.

Returns: an unmodifiable {@link java.util.Iterator}<{@link java.lang.Class}>.

getServiceProviderByClass

public <T> T getServiceProviderByClass(Class<T> providerClass)

Returns one of the service providers that is a subclass of the specified class.

Parameters: providerClass a class to search for.

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category, boolean useOrdering)

Retrieves all providers that have been registered for the specified service category.

Parameters: category the service category whose providers are to be retrieved. useOrdering true in order to retrieve the providers in an order imposed by the {@linkplain #setOrdering ordering constraints}; false in order to retrieve the providers in any order.

Throws: IllegalArgumentException if category is not among the categories passed to the {@linkplain #ServiceRegistry(Iterator) constructor} of this ServiceRegistry.

getServiceProviders

public <T> Iterator<T> getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering)

Retrieves all providers that have been registered for the specified service category and that satisfy the criteria of a custom filter.

Parameters: category the service category whose providers are to be retrieved. filter a custom filter, or null to retrieve all registered providers for the specified category. useOrdering true in order to retrieve the providers in an order imposed by the {@linkplain #setOrdering ordering constraints}; false in order to retrieve the providers in any order.

Throws: IllegalArgumentException if category is not among the categories passed to the {@linkplain #ServiceRegistry(Iterator) constructor} of this ServiceRegistry.

lookupProviders

public static <T> Iterator<T> lookupProviders(Class<T> spi, ClassLoader loader)

Finds service providers that are implementing the specified Service Provider Interface.

On-demand loading: Loading and initializing service providers is delayed as much as possible. The rationale is that typical clients will iterate through the set of installed service providers until one is found that matches some criteria (like supported formats, or quality of service). In such scenarios, it might make sense to install only the frequently needed service providers on the local machine. More exotic providers can be put onto a server; the server will only be contacted when no suitable service could be found locally.

Security considerations: Any loaded service providers are loaded through the specified ClassLoader, or the system ClassLoader if classLoader is null. When lookupProviders is called, the current {@link java.security.AccessControlContext} gets recorded. This captured security context will determine the permissions when services get loaded via the next() method of the returned Iterator.

Parameters: spi the service provider interface which must be implemented by any loaded service providers. loader the class loader that will be used to load the service providers, or null for the system class loader. For using the context class loader, see {@link #lookupProviders(Class)}.

Returns: an iterator over instances of spi.

Throws: IllegalArgumentException if spi is null.

lookupProviders

public static <T> Iterator<T> lookupProviders(Class<T> spi)

Finds service providers that are implementing the specified Service Provider Interface, using the context class loader for loading providers.

Parameters: spi the service provider interface which must be implemented by any loaded service providers.

Returns: an iterator over instances of spi.

Throws: IllegalArgumentException if spi is null.

registerServiceProvider

public <T> boolean registerServiceProvider(T provider, Class<T> category)

Registers a provider for the specified service category.

Parameters: provider the service provider to be registered. category the service category under which provider shall be registered.

Returns: true if provider is the first provider that gets registered for the specified service category; false if other providers have already been registered for the same servide category.

registerServiceProvider

public void registerServiceProvider(Object provider)

Registers a provider under all service categories it implements.

If provider implements the {@link RegisterableService} interface, its {@link RegisterableService#onRegistration onRegistration} method is invoked in order to inform the provider about the addition to this registry. If provider implements several service categories, onRegistration gets called multiple times.

Parameters: provider the service provider to be registered.

registerServiceProviders

public void registerServiceProviders(Iterator<?> providers)

Registers a number of providers under all service categories they implement.

If a provider implements the {@link RegisterableService} interface, its {@link RegisterableService#onRegistration onRegistration} method is invoked in order to inform the provider about the addition to this registry. If provider implements several service categories, onRegistration gets called multiple times.

Throws: IllegalArgumentException if providers is null, if any iterated provider is null, or if some iterated provider does not implement any of the service categories passed to the {@linkplain #ServiceRegistry(Iterator) constructor} of this ServiceRegistry.

setOrdering

public <T> boolean setOrdering(Class<T> category, T firstProvider, T secondProvider)

Adds an ordering constraint on service providers.

Parameters: category the service category to which an ordering constraint is to be added. first the provider which is supposed to come before second. second the provider which is supposed to come after first.

Throws: IllegalArgumentException if first and second are referring to the same object, or if one of them is null.

unsetOrdering

public <T> boolean unsetOrdering(Class<T> category, T firstProvider, T secondProvider)

Removes an ordering constraint on service providers.

Parameters: category the service category from which an ordering constraint is to be removed. first the provider which is supposed to come before second. second the provider which is supposed to come after first.

Throws: IllegalArgumentException if first and second are referring to the same object, or if one of them is null.