Class ServiceRegistry
- Direct Known Subclasses:
- IIORegistry
 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
- See Also:
- 
Nested Class SummaryNested ClassesModifier and TypeClassDescriptionstatic interfaceA simple filter interface used byServiceRegistry.getServiceProvidersto select providers matching an arbitrary criterion.
- 
Constructor SummaryConstructorsConstructorDescriptionServiceRegistry(Iterator<Class<?>> categories) Constructs aServiceRegistryinstance with a set of categories taken from thecategoriesargument.
- 
Method SummaryModifier and TypeMethodDescriptionbooleanReturnstrueifprovideris currently registered.voidDeregisters all currently registered service providers from all categories.voidderegisterAll(Class<?> category) Deregisters all service provider object currently registered under the given category.voidderegisterServiceProvider(Object provider) Removes a service provider object from all categories that contain it.<T> booleanderegisterServiceProvider(T provider, Class<T> category) Removes a service provider object from the given category.voidfinalize()Deprecated, for removal: This API element is subject to removal in a future version.Finalization has been deprecated for removal.Returns anIteratorofClassobjects indicating the current set of categories.<T> TgetServiceProviderByClass(Class<T> providerClass) Returns the currently registered service provider object that is of the given class type.<T> Iterator<T> getServiceProviders(Class<T> category, boolean useOrdering) Returns anIteratorcontaining all registered service providers in the given category.<T> Iterator<T> getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering) Returns anIteratorcontaining service provider objects within a given category that satisfy a criterion imposed by the suppliedServiceRegistry.Filterobject'sfiltermethod.static <T> Iterator<T> lookupProviders(Class<T> providerClass) Locates and incrementally instantiates the available providers of a given service using the context class loader.static <T> Iterator<T> lookupProviders(Class<T> providerClass, ClassLoader loader) Searches for implementations of a particular service class using the given class loader.voidregisterServiceProvider(Object provider) Adds a service provider object to the registry.<T> booleanregisterServiceProvider(T provider, Class<T> category) Adds a service provider object to the registry.voidregisterServiceProviders(Iterator<?> providers) Adds a set of service provider objects, taken from anIteratorto the registry.<T> booleansetOrdering(Class<T> category, T firstProvider, T secondProvider) Sets a pairwise ordering between two service provider objects within a given category.<T> booleanunsetOrdering(Class<T> category, T firstProvider, T secondProvider) Sets a pairwise ordering between two service provider objects within a given category.
- 
Constructor Details- 
ServiceRegistryConstructs aServiceRegistryinstance with a set of categories taken from thecategoriesargument. The categories must all be members of the set of service types listed in the class specification.- Parameters:
- categories- an- Iteratorcontaining- Classobjects to be used to define categories.
- Throws:
- IllegalArgumentException- if- categoriesis- null, or if one of the categories is not an allowed service type.
 
 
- 
- 
Method Details- 
lookupProvidersSearches 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, IllegalArgumentExceptionwill 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 getResourcesmethod 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. - Type Parameters:
- T- the type of the providerClass.
- Parameters:
- providerClass- a- Classobject 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- nullif the system class loader (or, failing that the bootstrap class loader) is to be used.
- Returns:
- An Iteratorthat yields provider objects for the given service, in some arbitrary order. The iterator will throw anErrorif a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.
- Throws:
- IllegalArgumentException- if- providerClassis- null, or if it is not one of the allowed service types.
 
- 
lookupProvidersLocates 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, IllegalArgumentExceptionwill be thrown.- Type Parameters:
- T- the type of the providerClass.
- Parameters:
- providerClass- a- Classobject indicating the class or interface of the service providers being detected.
- Returns:
- An Iteratorthat yields provider objects for the given service, in some arbitrary order. The iterator will throw anErrorif a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.
- Throws:
- IllegalArgumentException- if- providerClassis- null, or if it is not one of the allowed service types.
 
- 
getCategories
- 
registerServiceProviderAdds a service provider object to the registry. The provider is associated with the given category.If providerimplements theRegisterableServiceinterface, itsonRegistrationmethod will be called. ItsonDeregistrationmethod will be called each time it is deregistered from a category, for example if a category is removed or the registry is garbage collected.- Type Parameters:
- T- the type of the provider.
- Parameters:
- provider- the service provide object to be registered.
- category- the category under which to register the provider.
- Returns:
- true if no provider of the same class was previously registered in the same category category.
- Throws:
- IllegalArgumentException- if- provideris- null.
- IllegalArgumentException- if there is no category corresponding to- category.
- ClassCastException- if provider does not implement the- Classdefined by- category.
 
- 
registerServiceProviderAdds a service provider object to the registry. The provider is associated within each category present in the registry whoseClassit implements.If providerimplements theRegisterableServiceinterface, itsonRegistrationmethod will be called once for each category it is registered under. ItsonDeregistrationmethod will be called each time it is deregistered from a category or when the registry is finalized.- Parameters:
- provider- the service provider object to be registered.
- Throws:
- IllegalArgumentException- if- provideris- null.
 
- 
registerServiceProvidersAdds a set of service provider objects, taken from anIteratorto the registry. Each provider is associated within each category present in the registry whoseClassit implements.For each entry of providersthat implements theRegisterableServiceinterface, itsonRegistrationmethod will be called once for each category it is registered under. ItsonDeregistrationmethod will be called each time it is deregistered from a category or when the registry is finalized.- Parameters:
- providers- an Iterator containing service provider objects to be registered.
- Throws:
- IllegalArgumentException- if- providersis- nullor contains a- nullentry.
 
- 
deregisterServiceProviderRemoves a service provider object from the given category. If the provider was not previously registered, nothing happens andfalseis returned. Otherwise,trueis returned. If an object of the same class asproviderbut not equal (using==) toprovideris registered, it will not be deregistered.If providerimplements theRegisterableServiceinterface, itsonDeregistrationmethod will be called.- Type Parameters:
- T- the type of the provider.
- Parameters:
- provider- the service provider object to be deregistered.
- category- the category from which to deregister the provider.
- Returns:
- trueif the provider was previously registered in the same category category,- falseotherwise.
- Throws:
- IllegalArgumentException- if- provideris- null.
- IllegalArgumentException- if there is no category corresponding to- category.
- ClassCastException- if provider does not implement the class defined by- category.
 
- 
deregisterServiceProviderRemoves a service provider object from all categories that contain it.- Parameters:
- provider- the service provider object to be deregistered.
- Throws:
- IllegalArgumentException- if- provideris- null.
 
- 
containsReturnstrueifprovideris currently registered.- Parameters:
- provider- the service provider object to be queried.
- Returns:
- trueif the given provider has been registered.
- Throws:
- IllegalArgumentException- if- provideris- null.
 
- 
getServiceProvidersReturns anIteratorcontaining all registered service providers in the given category. IfuseOrderingisfalse, 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.- Type Parameters:
- T- the type of the category.
- Parameters:
- category- the category to be retrieved from.
- useOrdering-- trueif pairwise orderings should be taken account in ordering the returned objects.
- Returns:
- an Iteratorcontaining service provider objects from the given category, possibly in order.
- Throws:
- IllegalArgumentException- if there is no category corresponding to- category.
 
- 
getServiceProviderspublic <T> Iterator<T> getServiceProviders(Class<T> category, ServiceRegistry.Filter filter, boolean useOrdering) Returns anIteratorcontaining service provider objects within a given category that satisfy a criterion imposed by the suppliedServiceRegistry.Filterobject'sfiltermethod.The useOrderingargument controls the ordering of the results using the same rules asgetServiceProviders(Class, boolean).- Type Parameters:
- T- the type of the category.
- Parameters:
- category- the category to be retrieved from.
- filter- an instance of- ServiceRegistry.Filterwhose- filtermethod will be invoked.
- useOrdering-- trueif pairwise orderings should be taken account in ordering the returned objects.
- Returns:
- an Iteratorcontaining service provider objects from the given category, possibly in order.
- Throws:
- IllegalArgumentException- if there is no category corresponding to- category.
 
- 
getServiceProviderByClassReturns 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,nullis returned.- Type Parameters:
- T- the type of the provider.
- Parameters:
- providerClass- the- Classof the desired service provider object.
- Returns:
- a currently registered service provider object with the
 desired Classtype, ornullis none is present.
- Throws:
- IllegalArgumentException- if- providerClassis- null.
 
- 
setOrderingSets 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 andfalseis returned. If the providers previously were ordered in the reverse direction, that ordering is removed.The ordering will be used by the getServiceProvidersmethods when theiruseOrderingargument istrue.- Type Parameters:
- T- the type of the category.
- Parameters:
- category- a- Classobject indicating the category under which the preference is to be established.
- firstProvider- the preferred provider.
- secondProvider- the provider to which- firstProvideris preferred.
- Returns:
- trueif a previously unset ordering was established.
- Throws:
- IllegalArgumentException- if either provider is- nullor they are the same object.
- IllegalArgumentException- if there is no category corresponding to- category.
 
- 
unsetOrderingSets 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 andfalseis returned.The ordering will be used by the getServiceProvidersmethods when theiruseOrderingargument istrue.- Type Parameters:
- T- the type of the category.
- Parameters:
- category- a- Classobject indicating the category under which the preference is to be disestablished.
- firstProvider- the formerly preferred provider.
- secondProvider- the provider to which- firstProviderwas formerly preferred.
- Returns:
- trueif a previously set ordering was disestablished.
- Throws:
- IllegalArgumentException- if either provider is- nullor they are the same object.
- IllegalArgumentException- if there is no category corresponding to- category.
 
- 
deregisterAllDeregisters all service provider object currently registered under the given category.- Parameters:
- category- the category to be emptied.
- Throws:
- IllegalArgumentException- if there is no category corresponding to- category.
 
- 
deregisterAllpublic void deregisterAll()Deregisters all currently registered service providers from all categories.
- 
finalizeDeprecated, for removal: This API element is subject to removal in a future version.Finalization has been deprecated for removal. SeeObject.finalize()for background information and details about migration options.Finalizes this object prior to garbage collection. ThederegisterAllmethod is called to deregister all currently registered service providers. This method should not be called from application code.
 
-