javax.imageio.spi

Class ServiceRegistry

Known Direct 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> categories)
Constructs a ServiceRegistry for the specified service categories.

Method Summary

Iterator getServiceProviders(Class category, boolean useOrdering)
Retrieves all providers that have been registered for the specified service category.
Iterator getServiceProviders(Class 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
Iterator lookupProviders(Class spi)
Finds service providers that are implementing the specified Service Provider Interface, using the context class loader for loading providers.
static
Iterator lookupProviders(Class spi, ClassLoader loader)
Finds service providers that are implementing the specified Service Provider Interface.
T getServiceProviderByClass(Class providerClass)
Returns one of the service providers that is a subclass of the specified class.
boolean deregisterServiceProvider(T provider, Class category)
De-registers a provider for the specified service category.
boolean registerServiceProvider(T provider, Class category)
Registers a provider for the specified service category.
boolean setOrdering(Class category, T firstProvider, T secondProvider)
Adds an ordering constraint on service providers.
boolean unsetOrdering(Class category, T firstProvider, T secondProvider)
Removes an ordering constraint on service providers.
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.
void
finalize()
Called by the Virtual Machine when it detects that this ServiceRegistry has become garbage.
Iterator>
getCategories()
Returns an iterator over all service categories.
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.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ServiceRegistry

public ServiceRegistry(Iterator> 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 Details

Iterator getServiceProviders

public  Iterator getServiceProviders(Class 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)

Iterator getServiceProviders

public  Iterator getServiceProviders(Class 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.

Iterator lookupProviders

public static  Iterator lookupProviders(Class 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)

Iterator lookupProviders

public static  Iterator lookupProviders(Class 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.

T getServiceProviderByClass

public  T getServiceProviderByClass(Class providerClass)
Returns one of the service providers that is a subclass of the specified class.
Parameters:
providerClass - a class to search for.

boolean deregisterServiceProvider

public  boolean deregisterServiceProvider(T provider,
                                             Class 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.

boolean registerServiceProvider

public  boolean registerServiceProvider(T provider,
                                           Class 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.

boolean setOrdering

public  boolean setOrdering(Class 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:
ServiceRegistry, getServiceProviders(Class, Filter, boolean)

boolean unsetOrdering

public  boolean unsetOrdering(Class 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:
ServiceRegistry

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()
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.


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.

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.

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

getCategories

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

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.

ServiceRegistry.java -- A simple registry for service providers. Copyright (C) 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.