javax.imageio.spi
Class ServiceRegistry

java.lang.Object
  extended by javax.imageio.spi.ServiceRegistry
Direct Known Subclasses:
IIORegistry

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()
          De-registers all service providers.
 void deregisterAll(Class<?> category)
          De-registers all providers which have been registered for the specified service category.
 void deregisterServiceProvider(Object provider)
          De-registers a provider from all service categories it implements.
<T> boolean
deregisterServiceProvider(T provider, Class<T> category)
          De-registers a provider for the specified service category.
 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)
          Finds service providers that are implementing the specified Service Provider Interface, using the context class loader for loading providers.
static
<T> Iterator<T>
lookupProviders(Class<T> spi, ClassLoader loader)
          Finds service providers that are implementing the specified Service Provider Interface.
 void registerServiceProvider(Object provider)
          Registers a provider under all service categories it implements.
<T> boolean
registerServiceProvider(T provider, Class<T> category)
          Registers a provider for the specified service category.
 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.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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 Iterator.next() method returns null.
ClassCastException - if categories does not iterate over instances of Class.
Method Detail

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 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 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.
See Also:
lookupProviders(Class, ClassLoader)

getCategories

public Iterator<Class<?>> getCategories()
Returns an iterator over all service categories.

Returns:
an unmodifiable Iterator<Class>.

registerServiceProvider

public <T> boolean registerServiceProvider(T provider,
                                           Class<T> category)
Registers a provider for the specified service category.

If provider implements the RegisterableService interface, its onRegistration method is invoked in order to inform the provider about the addition to this registry.

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.
Throws:
IllegalArgumentException - if provider is null, or if category is not among the categories passed to the constructor of this ServiceRegistry.
ClassCastException - if provider does not implement category.

registerServiceProvider

public void registerServiceProvider(Object provider)
Registers a provider under all service categories it implements.

If provider implements the RegisterableService interface, its 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.
Throws:
IllegalArgumentException - if provider is null, or if provider does not implement any of the service categories passed to the constructor of this ServiceRegistry.

registerServiceProviders

public void registerServiceProviders(Iterator<?> providers)
Registers a number of providers under all service categories they implement.

If a provider implements the RegisterableService interface, its 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 constructor of this ServiceRegistry.

deregisterServiceProvider

public <T> boolean deregisterServiceProvider(T provider,
                                             Class<T> category)
De-registers a provider for the specified service category.

If provider implements the RegisterableService interface, its onDeregistration method is invoked in order to inform the provider about the removal from this registry.

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 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 RegisterableService interface, its 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 constructor of this ServiceRegistry.

deregisterAll

public void deregisterAll(Class<?> category)
De-registers all providers which have been registered for the specified service category.

If a provider implements the RegisterableService interface, its 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 constructor of this ServiceRegistry.

deregisterAll

public void deregisterAll()
De-registers all service providers.

If a provider implements the RegisterableService interface, its 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.


finalize

public void finalize()
              throws Throwable
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 RegisterableService to receive a onDeregistration notification.

Overrides:
finalize in class Object
Throws:
Throwable - permits a subclass to throw anything in an overridden version; but the default throws nothing
See Also:
System.gc(), System.runFinalizersOnExit(boolean), java.lang.ref

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.

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 ordering constraints; false in order to retrieve the providers in any order.
Throws:
IllegalArgumentException - if category is not among the categories passed to the constructor of this ServiceRegistry.
See Also:
getServiceProviders(Class, Filter, boolean)

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 ordering constraints; false in order to retrieve the providers in any order.
Throws:
IllegalArgumentException - if category is not among the categories passed to the constructor of this ServiceRegistry.

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.

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.
firstProvider - the provider which is supposed to come before second.
secondProvider - 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.
See Also:
unsetOrdering(java.lang.Class, T, T), getServiceProviders(Class, Filter, boolean)

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.
firstProvider - the provider which is supposed to come before second.
secondProvider - 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.
See Also:
setOrdering(java.lang.Class, T, T)