IIORegistry
public class ServiceRegistry extends Object
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, so long as it has the appropriate runtime permission.
For information on how to create and deploy service providers, refer to the documentation on ServiceLoader
Modifier and Type | Class | Description |
---|---|---|
static interface |
ServiceRegistry.Filter |
A simple filter interface used by ServiceRegistry.getServiceProviders to select providers matching an arbitrary criterion. |
Constructor | Description |
---|---|
ServiceRegistry |
Constructs a ServiceRegistry instance with a set of categories taken from the categories argument. |
Modifier and Type | Method | Description |
---|---|---|
boolean |
contains |
Returns true if provider is currently registered. |
void |
deregisterAll() |
Deregisters all currently registered service providers from all categories. |
void |
deregisterAll |
Deregisters all service provider object currently registered under the given category. |
void |
deregisterServiceProvider |
Removes a service provider object from all categories that contain it. |
<T> boolean |
deregisterServiceProvider |
Removes a service provider object from the given category. |
void |
finalize() |
Deprecated, for removal: This API element is subject to removal in a future version. Finalization has been deprecated for removal. |
Iterator |
getCategories() |
Returns an Iterator of Class objects indicating the current set of categories. |
<T> T |
getServiceProviderByClass |
Returns the currently registered service provider object that is of the given class type. |
<T> Iterator |
getServiceProviders |
Returns an Iterator containing all registered service providers in the given category. |
<T> Iterator |
getServiceProviders |
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. |
static <T> Iterator |
lookupProviders |
Locates and incrementally instantiates the available providers of a given service using the context class loader. |
static <T> Iterator |
lookupProviders |
Searches for implementations of a particular service class using the given class loader. |
void |
registerServiceProvider |
Adds a service provider object to the registry. |
<T> boolean |
registerServiceProvider |
Adds a service provider object to the registry. |
void |
registerServiceProviders |
Adds a set of service provider objects, taken from an Iterator to the registry. |
<T> boolean |
setOrdering |
Sets a pairwise ordering between two service provider objects within a given category. |
<T> boolean |
unsetOrdering |
Sets a pairwise ordering between two service provider objects within a given category. |
public ServiceRegistry(Iterator<Class<?>> categories)
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.categories
- an Iterator
containing Class
objects to be used to define categories.IllegalArgumentException
- if categories
is null
, or if one of the categories is not an allowed service type.public static <T> Iterator<T> lookupProviders(Class<T> providerClass, ClassLoader 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.
T
- the type of the providerClass.providerClass
- a Class
object indicating the class or interface of the service providers being detected.loader
- 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.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.IllegalArgumentException
- if providerClass
is null
, or if it is not one of the allowed service types.public static <T> Iterator<T> lookupProviders(Class<T> providerClass)
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.
T
- the type of the providerClass.providerClass
- a Class
object indicating the class or interface of the service providers being detected.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.IllegalArgumentException
- if providerClass
is null
, or if it is not one of the allowed service types.public Iterator<Class<?>> getCategories()
Iterator
of Class
objects indicating the current set of categories. The iterator will be empty if no categories exist.Iterator
containing Class
objects.public <T> boolean registerServiceProvider(T provider, Class<T> 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.
T
- the type of the provider.provider
- the service provide object to be registered.category
- the category under which to register the provider.IllegalArgumentException
- if provider
is null
.IllegalArgumentException
- if there is no category corresponding to category
.ClassCastException
- if provider does not implement the Class
defined by category
.public void registerServiceProvider(Object provider)
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 or when the registry is finalized.
provider
- the service provider object to be registered.IllegalArgumentException
- if provider
is null
.public void registerServiceProviders(Iterator<?> providers)
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 or when the registry is finalized.
providers
- an Iterator containing service provider objects to be registered.IllegalArgumentException
- if providers
is null
or contains a null
entry.public <T> boolean deregisterServiceProvider(T provider, Class<T> category)
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.
T
- the type of the provider.provider
- the service provider object to be deregistered.category
- the category from which to deregister the provider.true
if the provider was previously registered in the same category category, false
otherwise.IllegalArgumentException
- if provider
is null
.IllegalArgumentException
- if there is no category corresponding to category
.ClassCastException
- if provider does not implement the class defined by category
.public void deregisterServiceProvider(Object provider)
provider
- the service provider object to be deregistered.IllegalArgumentException
- if provider
is null
.public boolean contains(Object provider)
true
if provider
is currently registered.provider
- the service provider object to be queried.true
if the given provider has been registered.IllegalArgumentException
- if provider
is null
.public <T> Iterator<T> getServiceProviders(Class<T> category, boolean useOrdering)
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.T
- the type of the category.category
- the category to be retrieved from.useOrdering
- true
if pairwise orderings should be taken account in ordering the returned objects.Iterator
containing service provider objects from the given category, possibly in order.IllegalArgumentException
- if there is no category corresponding to category
.public <T> Iterator<T> getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering)
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)
.
T
- the type of the category.category
- the category to be retrieved from.filter
- an instance of ServiceRegistry.Filter
whose filter
method will be invoked.useOrdering
- true
if pairwise orderings should be taken account in ordering the returned objects.Iterator
containing service provider objects from the given category, possibly in order.IllegalArgumentException
- if there is no category corresponding to category
.public <T> T getServiceProviderByClass(Class<T> providerClass)
null
is returned.T
- the type of the provider.providerClass
- the Class
of the desired service provider object.Class
type, or null
is none is present.IllegalArgumentException
- if providerClass
is null
.public <T> boolean setOrdering(Class<T> category, T firstProvider, T secondProvider)
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
.
T
- the type of the category.category
- a Class
object indicating the category under which the preference is to be established.firstProvider
- the preferred provider.secondProvider
- the provider to which firstProvider
is preferred.true
if a previously unset ordering was established.IllegalArgumentException
- if either provider is null
or they are the same object.IllegalArgumentException
- if there is no category corresponding to category
.public <T> boolean unsetOrdering(Class<T> category, T firstProvider, T secondProvider)
false
is returned. The ordering will be used by the getServiceProviders
methods when their useOrdering
argument is true
.
T
- the type of the category.category
- a Class
object indicating the category under which the preference is to be disestablished.firstProvider
- the formerly preferred provider.secondProvider
- the provider to which firstProvider
was formerly preferred.true
if a previously set ordering was disestablished.IllegalArgumentException
- if either provider is null
or they are the same object.IllegalArgumentException
- if there is no category corresponding to category
.public void deregisterAll(Class<?> category)
category
- the category to be emptied.IllegalArgumentException
- if there is no category corresponding to category
.public void deregisterAll()
@Deprecated(since="9", forRemoval=true) public void finalize() throws Throwable
Object.finalize()
for background information and details about migration options.deregisterAll
method is called to deregister all currently registered service providers. This method should not be called from application code.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/imageio/spi/ServiceRegistry.html