APIdia Launch Partner
Top Description Inners Fields Constructors Methods
javax.imageio.spi

public Class ServiceRegistry

Additional top-level classes in compilation unit: SubRegistry, FilterIterator.

extends Object
Class Inheritance
Known Direct Subclasses
javax.imageio.spi.IIORegistry
Imports
java.util.ArrayList, .HashMap, .Iterator, .List, .Map, .NoSuchElementException, .Set, .ServiceLoader

A registry for service provider instances for Image I/O service types.

Service providers are stored in one or more categories, each of which is defined by a class or interface (described by a Class object) that all of its members must implement.

The set of categories supported by this class is limited to the following standard Image I/O service types:

An attempt to load a provider that is not a subtype of one of the above types will result in IllegalArgumentException.

For the general mechanism to load service providers, see ServiceLoader, which is the underlying standard mechanism used by this class.

Only a single instance of a given leaf class (that is, the actual class returned by getClass(), as opposed to any inherited classes or interfaces) may be registered. That is, suppose that the com.mycompany.mypkg.GreenImageReaderProvider class is a subclass of javax.imageio.spi.ImageReaderSpi. If a GreenImageReaderProvider instance is registered, it will be stored in the category defined by the ImageReaderSpi class. If a new instance of GreenImageReaderProvider is registered, it will replace the previous instance. In practice, service provider objects are usually singletons so this behavior is appropriate.

The service provider classes should be lightweight and quick to load. Implementations of these interfaces should avoid complex dependencies on other classes and on native code. The usual pattern for more complex services is to register a lightweight proxy for the heavyweight service.

An application may customize the contents of a registry as it sees fit.

For information on how to create and deploy service providers, refer to the documentation on ServiceLoader

See Also
RegisterableService, java.util.ServiceLoader

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
ServiceRegistry.Filter

A simple filter interface used by ServiceRegistry.getServiceProviders to select providers matching an arbitrary criterion.

Field Summary

Modifier and TypeField and Description
private Map<Class<?>, SubRegistry>

Constructor Summary

AccessConstructor and Description
public
ServiceRegistry(Iterator<Class<?>>
an Iterator containing Class objects to be used to define categories.
categories
)

Constructs a ServiceRegistry instance with a set of categories taken from the categories argument.

Method Summary

Modifier and TypeMethod and Description
private static void
checkClassAllowed(Class<?> clazz)

Checks whether the provided class is one of the allowed ImageIO service provider classes.

public boolean

Returns:

true if the given provider has been registered.
contains
(Object
the service provider object to be queried.
provider
)

Returns true if provider is currently registered.

public void
deregisterAll(Class<?>
the category to be emptied.
category
)

Deregisters all service provider object currently registered under the given category.

public void
deregisterAll()

Deregisters all currently registered service providers from all categories.

public <
the type of the provider.
T
>
boolean

Returns:

true if the provider was previously registered in the same category category, false otherwise.
deregisterServiceProvider
(T
the service provider object to be deregistered.
provider
,
Class<T>
the category from which to deregister the provider.
category
)

Removes a service provider object from the given category.

public void
deregisterServiceProvider(Object
the service provider object to be deregistered.
provider
)

Removes a service provider object from all categories that contain it.

public Iterator<Class<?>>

Returns:

an Iterator containing Class objects.
getCategories
()

Returns an Iterator of Class objects indicating the current set of categories.

public <
the type of the provider.
T
>
T

Returns:

a currently registered service provider object with the desired Class type, or null is none is present.
getServiceProviderByClass
(Class<T>
the Class of the desired service provider object.
providerClass
)

Returns the currently registered service provider object that is of the given class type.

public <
the type of the category.
T
>
Iterator<T>

Returns:

an Iterator containing service provider objects from the given category, possibly in order.
getServiceProviders
(Class<T>
the category to be retrieved from.
category
,
boolean
true if pairwise orderings should be taken account in ordering the returned objects.
useOrdering
)

Returns an Iterator containing all registered service providers in the given category.

public <
the type of the category.
T
>
Iterator<T>

Returns:

an Iterator containing service provider objects from the given category, possibly in order.
getServiceProviders
(Class<T>
the category to be retrieved from.
category
,
ServiceRegistry.Filter
an instance of ServiceRegistry.Filter whose filter method will be invoked.
filter
,
boolean
true if pairwise orderings should be taken account in ordering the returned objects.
useOrdering
)

Returns an Iterator containing service provider objects within a given category that satisfy a criterion imposed by the supplied ServiceRegistry.Filter object's filter method.

private Iterator<SubRegistry>
getSubRegistries(Object provider)

Returns an Iterator containing the subregistries to which the provider belongs.

public static <
the type of the providerClass.
T
>
Iterator<T>

Returns:

An Iterator that yields provider objects for the given service, in some arbitrary order. The iterator will throw an Error if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.
lookupProviders
(Class<T>
a Class object indicating the class or interface of the service providers being detected.
providerClass
,
ClassLoader
the class loader to be used to load provider-configuration files and instantiate provider classes, or null if the system class loader (or, failing that the bootstrap class loader) is to be used.
loader
)

Searches for implementations of a particular service class using the given class loader.

public static <
the type of the providerClass.
T
>
Iterator<T>

Returns:

An Iterator that yields provider objects for the given service, in some arbitrary order. The iterator will throw an Error if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.
lookupProviders
(Class<T>
a Class object indicating the class or interface of the service providers being detected.
providerClass
)

Locates and incrementally instantiates the available providers of a given service using the context class loader.

public <
the type of the provider.
T
>
boolean

Returns:

true if no provider of the same class was previously registered in the same category category.
registerServiceProvider
(T
the service provide object to be registered.
provider
,
Class<T>
the category under which to register the provider.
category
)

Adds a service provider object to the registry.

public void
registerServiceProvider(Object
the service provider object to be registered.
provider
)

Adds a service provider object to the registry.

public void
registerServiceProviders(Iterator<?>
an Iterator containing service provider objects to be registered.
providers
)

Adds a set of service provider objects, taken from an Iterator to the registry.

public <
the type of the category.
T
>
boolean

Returns:

true if a previously unset ordering was established.
setOrdering
(Class<T>
a Class object indicating the category under which the preference is to be established.
category
,
T
the preferred provider.
firstProvider
,
T
the provider to which firstProvider is preferred.
secondProvider
)

Sets a pairwise ordering between two service provider objects within a given category.

public <
the type of the category.
T
>
boolean

Returns:

true if a previously set ordering was disestablished.
unsetOrdering
(Class<T>
a Class object indicating the category under which the preference is to be disestablished.
category
,
T
the formerly preferred provider.
firstProvider
,
T
the provider to which firstProvider was formerly preferred.
secondProvider
)

Sets a pairwise ordering between two service provider objects within a given category.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

categoryMapback to summary
private Map<Class<?>, SubRegistry> categoryMap

Constructor Detail

ServiceRegistryback to summary
public ServiceRegistry(Iterator<Class<?>> categories)

Constructs a ServiceRegistry instance with a set of categories taken from the categories argument. The categories must all be members of the set of service types listed in the class specification.

Parameters
categories:Iterator<Class<?>>

an Iterator containing Class objects to be used to define categories.

Exceptions
IllegalArgumentException:
if categories is null, or if one of the categories is not an allowed service type.

Method Detail

checkClassAllowedback to summary
private static void checkClassAllowed(Class<?> clazz)

Checks whether the provided class is one of the allowed ImageIO service provider classes. If it is, returns normally. If it is not, throws IllegalArgumentException.

Exceptions
IllegalArgumentException:
if clazz is null or is not one of the allowed set
containsback to summary
public boolean contains(Object provider)

Returns true if provider is currently registered.

Parameters
provider:Object

the service provider object to be queried.

Returns:boolean

true if the given provider has been registered.

Exceptions
IllegalArgumentException:
if provider is null.
deregisterAllback to summary
public void deregisterAll(Class<?> category)

Deregisters all service provider object currently registered under the given category.

Parameters
category:Class<?>

the category to be emptied.

Exceptions
IllegalArgumentException:
if there is no category corresponding to category.
deregisterAllback to summary
public void deregisterAll()

Deregisters all currently registered service providers from all categories.

If an application creates a new ServiceRegistry instance and registers providers, and at some point no longer needs the instance, it should call this method to ensure that all providers which are instances of RegisterableService receive a RegisterableService#onDeregistration(ServiceRegistry, Class<?>) call back, before allowing the instance to be garbage collected.

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

Removes a service provider object from the given category. If the provider was not previously registered, nothing happens and false is returned. Otherwise, true is returned. If an object of the same class as provider but not equal (using ==) to provider is registered, it will not be deregistered.

If provider implements the RegisterableService interface, its onDeregistration method will be called.

Parameters
<T>
the type of the provider.
provider:T

the service provider object to be deregistered.

category:Class<T>

the category from which to deregister the provider.

Returns:boolean

true if the provider was previously registered in the same category category, false otherwise.

Exceptions
IllegalArgumentException:
  • if provider is null.
  • if there is no category corresponding to category.
ClassCastException:
if provider does not implement the class defined by category.
deregisterServiceProviderback to summary
public void deregisterServiceProvider(Object provider)

Removes a service provider object from all categories that contain it.

Parameters
provider:Object

the service provider object to be deregistered.

Exceptions
IllegalArgumentException:
if provider is null.
getCategoriesback to summary
public Iterator<Class<?>> getCategories()

Returns an Iterator of Class objects indicating the current set of categories. The iterator will be empty if no categories exist.

Returns:Iterator<Class<?>>

an Iterator containing Class objects.

getServiceProviderByClassback to summary
public <T> T getServiceProviderByClass(Class<T> providerClass)

Returns the currently registered service provider object that is of the given class type. At most one object of a given class is allowed to be registered at any given time. If no registered object has the desired class type, null is returned.

Parameters
<T>
the type of the provider.
providerClass:Class<T>

the Class of the desired service provider object.

Returns:T

a currently registered service provider object with the desired Class type, or null is none is present.

Exceptions
IllegalArgumentException:
if providerClass is null.
getServiceProvidersback to summary
public <T> Iterator<T> getServiceProviders(Class<T> category, boolean useOrdering)

Returns an Iterator containing all registered service providers in the given category. If useOrdering is false, the iterator will return all of the server provider objects in an arbitrary order. Otherwise, the ordering will respect any pairwise orderings that have been set. If the graph of pairwise orderings contains cycles, any providers that belong to a cycle will not be returned.

Parameters
<T>
the type of the category.
category:Class<T>

the category to be retrieved from.

useOrdering:boolean

true if pairwise orderings should be taken account in ordering the returned objects.

Returns:Iterator<T>

an Iterator containing service provider objects from the given category, possibly in order.

Exceptions
IllegalArgumentException:
if there is no category corresponding to category.
getServiceProvidersback to summary
public <T> Iterator<T> getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering)

Returns an Iterator containing service provider objects within a given category that satisfy a criterion imposed by the supplied ServiceRegistry.Filter object's filter method.

The useOrdering argument controls the ordering of the results using the same rules as getServiceProviders(Class, boolean).

Parameters
<T>
the type of the category.
category:Class<T>

the category to be retrieved from.

filter:ServiceRegistry.Filter

an instance of ServiceRegistry.Filter whose filter method will be invoked.

useOrdering:boolean

true if pairwise orderings should be taken account in ordering the returned objects.

Returns:Iterator<T>

an Iterator containing service provider objects from the given category, possibly in order.

Exceptions
IllegalArgumentException:
if there is no category corresponding to category.
getSubRegistriesback to summary
private Iterator<SubRegistry> getSubRegistries(Object provider)

Returns an Iterator containing the subregistries to which the provider belongs.

lookupProvidersback to summary
public static <T> Iterator<T> lookupProviders(Class<T> providerClass, ClassLoader loader)

Searches for implementations of a particular service class using the given class loader.

The service class must be one of the service types listed in the class specification. If it is not, IllegalArgumentException will be thrown.

This method transforms the name of the given service class into a provider-configuration filename as described in the class comment and then uses the getResources method of the given class loader to find all available files with that name. These files are then read and parsed to produce a list of provider-class names. The iterator that is returned uses the given class loader to look up and then instantiate each element of the list.

Because it is possible for extensions to be installed into a running Java virtual machine, this method may return different results each time it is invoked.

Parameters
<T>
the type of the providerClass.
providerClass:Class<T>

a Class object indicating the class or interface of the service providers being detected.

loader:ClassLoader

the class loader to be used to load provider-configuration files and instantiate provider classes, or null if the system class loader (or, failing that the bootstrap class loader) is to be used.

Returns:Iterator<T>

An Iterator that yields provider objects for the given service, in some arbitrary order. The iterator will throw an Error if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.

Exceptions
IllegalArgumentException:
if providerClass is null, or if it is not one of the allowed service types.
lookupProvidersback to summary
public static <T> Iterator<T> lookupProviders(Class<T> providerClass)

Locates and incrementally instantiates the available providers of a given service using the context class loader. This convenience method is equivalent to:

  ClassLoader cl = Thread.currentThread().getContextClassLoader();
  return Service.providers(service, cl);

The service class must be one of the service types listed in the class specification. If it is not, IllegalArgumentException will be thrown.

Parameters
<T>
the type of the providerClass.
providerClass:Class<T>

a Class object indicating the class or interface of the service providers being detected.

Returns:Iterator<T>

An Iterator that yields provider objects for the given service, in some arbitrary order. The iterator will throw an Error if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.

Exceptions
IllegalArgumentException:
if providerClass is null, or if it is not one of the allowed service types.
registerServiceProviderback to summary
public <T> boolean registerServiceProvider(T provider, Class<T> category)

Adds a service provider object to the registry. The provider is associated with the given category.

If provider implements the RegisterableService interface, its onRegistration method will be called. Its onDeregistration method will be called each time it is deregistered from a category, for example if a category is removed or the registry is garbage collected.

Parameters
<T>
the type of the provider.
provider:T

the service provide object to be registered.

category:Class<T>

the category under which to register the provider.

Returns:boolean

true if no provider of the same class was previously registered in the same category category.

Exceptions
IllegalArgumentException:
  • if provider is null.
  • if there is no category corresponding to category.
ClassCastException:
if provider does not implement the Class defined by category.
registerServiceProviderback to summary
public void registerServiceProvider(Object provider)

Adds a service provider object to the registry. The provider is associated within each category present in the registry whose Class it implements.

If provider implements the RegisterableService interface, its onRegistration method will be called once for each category it is registered under. Its onDeregistration method will be called each time it is deregistered from a category.

Parameters
provider:Object

the service provider object to be registered.

Exceptions
IllegalArgumentException:
if provider is null.
registerServiceProvidersback to summary
public void registerServiceProviders(Iterator<?> providers)

Adds a set of service provider objects, taken from an Iterator to the registry. Each provider is associated within each category present in the registry whose Class it implements.

For each entry of providers that implements the RegisterableService interface, its onRegistration method will be called once for each category it is registered under. Its onDeregistration method will be called each time it is deregistered from a category.

Parameters
providers:Iterator<?>

an Iterator containing service provider objects to be registered.

Exceptions
IllegalArgumentException:
if providers is null or contains a null entry.
setOrderingback to summary
public <T> boolean setOrdering(Class<T> category, T firstProvider, T secondProvider)

Sets a pairwise ordering between two service provider objects within a given category. If one or both objects are not currently registered within the given category, or if the desired ordering is already set, nothing happens and false is returned. If the providers previously were ordered in the reverse direction, that ordering is removed.

The ordering will be used by the getServiceProviders methods when their useOrdering argument is true.

Parameters
<T>
the type of the category.
category:Class<T>

a Class object indicating the category under which the preference is to be established.

firstProvider:T

the preferred provider.

secondProvider:T

the provider to which firstProvider is preferred.

Returns:boolean

true if a previously unset ordering was established.

Exceptions
IllegalArgumentException:
  • if either provider is null or they are the same object.
  • if there is no category corresponding to category.
unsetOrderingback to summary
public <T> boolean unsetOrdering(Class<T> category, T firstProvider, T secondProvider)

Sets a pairwise ordering between two service provider objects within a given category. If one or both objects are not currently registered within the given category, or if no ordering is currently set between them, nothing happens and false is returned.

The ordering will be used by the getServiceProviders methods when their useOrdering argument is true.

Parameters
<T>
the type of the category.
category:Class<T>

a Class object indicating the category under which the preference is to be disestablished.

firstProvider:T

the formerly preferred provider.

secondProvider:T

the provider to which firstProvider was formerly preferred.

Returns:boolean

true if a previously set ordering was disestablished.

Exceptions
IllegalArgumentException:
  • if either provider is null or they are the same object.
  • if there is no category corresponding to category.
javax.imageio.spi back to summary

public Interface ServiceRegistry.Filter

Known Direct Implementers
com.sun.imageio.plugins.tiff.TIFFJPEGCompressor.JPEGSPIFilter, javax.imageio.ImageIO.CanDecodeInputFilter, javax.imageio.ImageIO.CanEncodeImageAndFormatFilter, javax.imageio.ImageIO.ContainsFilter, javax.imageio.ImageIO.TranscoderFilter

A simple filter interface used by ServiceRegistry.getServiceProviders to select providers matching an arbitrary criterion. Classes that implement this interface should be defined in order to make use of the getServiceProviders method of ServiceRegistry that takes a Filter.
See Also
ServiceRegistry#getServiceProviders(Class, ServiceRegistry.Filter, boolean)

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if the provider matches the criterion.
filter
(Object
a service provider Object.
provider
)

Returns true if the given provider object matches the criterion defined by this Filter.

Method Detail

filterback to summary
public boolean filter(Object provider)

Returns true if the given provider object matches the criterion defined by this Filter.

Parameters
provider:Object

a service provider Object.

Returns:boolean

true if the provider matches the criterion.