| |
|
| java.lang.Object
 javax.imageio.spi.ServiceRegistry
All known Subclasses: javax.imageio.spi.IIORegistry,
| ServiceRegistry | | public class ServiceRegistry (Code) | | A registry for service provider instances.
A service is a well-known set of interfaces and (usually
abstract) classes. A service provider is a specific
implementation of a service. The classes in a provider typically
implement the interface or subclass the class defined by the
service itself.
Service providers are stored in one or more categories,
each of which is defined by a class of interface (described by a
Class object) that all of its members must implement.
The set of categories may be changed dynamically.
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.GreenServiceProvider class
implements the com.mycompany.mypkg.MyService
interface. If a GreenServiceProvider instance is
registered, it will be stored in the category defined by the
MyService class. If a new instance of
GreenServiceProvider is registered, it will replace
the previous instance. In practice, service provider objects are
usually singletons so this behavior is appropriate.
To declare a service provider, a services
subdirectory is placed within the META-INF directory
that is present in every JAR file. This directory contains a file
for each service provider interface that has one or more
implementation classes present in the JAR file. For example, if
the JAR file contained a class named
com.mycompany.mypkg.MyServiceImpl which implements the
javax.someapi.SomeService interface, the JAR file
would contain a file named:
META-INF/services/javax.someapi.SomeService
containing the line:
com.mycompany.mypkg.MyService
The service provider classes should be to 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 more details on declaring service providers, and the JAR
format in general, see the
JAR File Specification.
See Also: RegisterableService
version:
0.5 |
| Inner Class :public interface Filter | |
| Constructor Summary | |
| public | ServiceRegistry(Iterator<Class<?>> categories)
Constructs a ServiceRegistry instance with a
set of categories taken from the categories
argument. |
| Method Summary | |
| public boolean | contains(Object provider)
Returns true if provider is currently
registered.
Parameters:
provider - the service provider object to be queried. | | public void | deregisterAll(Class 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 boolean | deregisterServiceProvider(T provider, Class<T> category)
Removes a service provider object from the given category. | | public void | deregisterServiceProvider(Object provider)
Removes a service provider object from all categories that
contain it. | | public void | finalize()
Finalizes this object prior to garbage collection. | | public Iterator<Class<?>> | getCategories()
Returns an Iterator of Class objects
indicating the current set of categories. | | public T | getServiceProviderByClass(Class<T> providerClass)
Returns the currently registered service provider object that
is of the given class type. | | public Iterator<T> | getServiceProviders(Class<T> category, boolean useOrdering)
Returns an Iterator containing all registered
service providers in the given category. | | public Iterator<T> | getServiceProviders(Class<T> category, 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:
category - the category to be retrieved from.
Parameters:
filter - an instance of ServiceRegistry.Filterwhose filter method will be invoked.
Parameters:
useOrdering - true if pairwise orderingsshould be taken account in ordering the returned objects. | | public static Iterator<T> | lookupProviders(Class<T> providerClass, ClassLoader loader)
Searches for implementations of a particular service class
using the given class loader.
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. | | public static Iterator<T> | lookupProviders(Class<T> providerClass)
Locates and incrementally instantiates the available providers
of a given service using the context class loader. | | public boolean | registerServiceProvider(T provider, Class<T> category)
Adds a service provider object to the registry. | | public void | registerServiceProvider(Object provider)
Adds a service provider object to the registry. | | public void | registerServiceProviders(Iterator providers)
Adds a set of service provider objects, taken from an
Iterator to the registry. | | public boolean | setOrdering(Class<T> category, T firstProvider, T secondProvider)
Sets a pairwise ordering between two service provider objects
within a given category. | | public boolean | unsetOrdering(Class<T> category, T firstProvider, T secondProvider)
Sets a pairwise ordering between two service provider objects
within a given category. |
| ServiceRegistry | | public ServiceRegistry(Iterator<Class<?>> categories)(Code) | | Constructs a ServiceRegistry instance with a
set of categories taken from the categories
argument.
Parameters:
categories - an Iterator containingClass objects to be used to define categories.
exception:
IllegalArgumentException - ifcategories is null. |
| contains | | public boolean contains(Object provider)(Code) | | Returns true if provider is currently
registered.
Parameters:
provider - the service provider object to be queried. true if the given provider has beenregistered.
exception:
IllegalArgumentException - if provider isnull. |
| deregisterAll | | public void deregisterAll(Class category)(Code) | | Deregisters all service provider object currently registered
under the given category.
Parameters:
category - the category to be emptied.
exception:
IllegalArgumentException - if there is no categorycorresponding to category. |
| deregisterAll | | public void deregisterAll()(Code) | | Deregisters all currently registered service providers from all
categories.
|
| deregisterServiceProvider | | public boolean deregisterServiceProvider(T provider, Class<T> category)(Code) | | 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:
provider - the service provider object to be deregistered.
Parameters:
category - the category from which to deregister theprovider. true if the provider was previouslyregistered in the same category category,false otherwise.
exception:
IllegalArgumentException - if provider isnull.
exception:
IllegalArgumentException - if there is no categorycorresponding to category.
exception:
ClassCastException - if provider does not implementthe class defined by category. |
| deregisterServiceProvider | | public void deregisterServiceProvider(Object provider)(Code) | | Removes a service provider object from all categories that
contain it.
Parameters:
provider - the service provider object to be deregistered.
exception:
IllegalArgumentException - if provider isnull. |
| finalize | | public void finalize() throws Throwable(Code) | | Finalizes this object prior to garbage collection. The
deregisterAll method is called to deregister all
currently registered service providers. This method should not
be called from application code.
exception:
Throwable - if an error occurs during superclassfinalization. |
| getCategories | | public Iterator<Class<?>> getCategories()(Code) | | Returns an Iterator of Class objects
indicating the current set of categories. The iterator will be
empty if no categories exist.
an Iterator containingClassobjects. |
| getServiceProviderByClass | | public T getServiceProviderByClass(Class<T> providerClass)(Code) | | 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:
providerClass - the Class of the desiredservice provider object. a currently registered service provider object with thedesired Classtype, or null is none ispresent.
exception:
IllegalArgumentException - if providerClass isnull. |
| getServiceProviders | | public Iterator<T> getServiceProviders(Class<T> category, boolean useOrdering)(Code) | | 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:
category - the category to be retrieved from.
Parameters:
useOrdering - true if pairwise orderingsshould be taken account in ordering the returned objects. an Iterator containing service providerobjects from the given category, possibly in order.
exception:
IllegalArgumentException - if there is no categorycorresponding to category. |
| getServiceProviders | | public Iterator<T> getServiceProviders(Class<T> category, Filter filter, boolean useOrdering)(Code) | | 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:
category - the category to be retrieved from.
Parameters:
filter - an instance of ServiceRegistry.Filterwhose filter method will be invoked.
Parameters:
useOrdering - true if pairwise orderingsshould be taken account in ordering the returned objects. an Iterator containing service providerobjects from the given category, possibly in order.
exception:
IllegalArgumentException - if there is no categorycorresponding to category. |
| lookupProviders | | public static Iterator<T> lookupProviders(Class<T> providerClass, ClassLoader loader)(Code) | | Searches for implementations of a particular service class
using the given class loader.
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:
providerClass - a Classobject indicating theclass or interface of the service providers being detected.
Parameters:
loader - the class loader to be used to loadprovider-configuration files and instantiate provider classes,or null if the system class loader (or, failing thatthe bootstrap class loader) is to be used. An Iterator that yields provider objectsfor the given service, in some arbitrary order. The iteratorwill throw an Error if a provider-configurationfile violates the specified format or if a provider classcannot be found and instantiated.
exception:
IllegalArgumentException - ifproviderClass is null. |
| lookupProviders | | public static Iterator<T> lookupProviders(Class<T> providerClass)(Code) | | 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);
Parameters:
providerClass - a Classobject indicating theclass or interface of the service providers being detected. An Iterator that yields provider objectsfor the given service, in some arbitrary order. The iteratorwill throw an Error if a provider-configurationfile violates the specified format or if a provider classcannot be found and instantiated.
exception:
IllegalArgumentException - ifproviderClass is null. |
| registerServiceProvider | | public boolean registerServiceProvider(T provider, Class<T> category)(Code) | | 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:
provider - the service provide object to be registered.
Parameters:
category - the category under which to register theprovider. true if no provider of the same class was previouslyregistered in the same category category.
exception:
IllegalArgumentException - if provider isnull.
exception:
IllegalArgumentException - if there is no categorycorresponding to category.
exception:
ClassCastException - if provider does not implementthe Class defined by category. |
| registerServiceProvider | | public void registerServiceProvider(Object provider)(Code) | | 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 or when the registry is
finalized.
Parameters:
provider - the service provider object to be registered.
exception:
IllegalArgumentException - ifprovider is null. |
| registerServiceProviders | | public void registerServiceProviders(Iterator providers)(Code) | | 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 or when the registry is
finalized.
Parameters:
providers - an Iterator containing service providerobjects to be registered.
exception:
IllegalArgumentException - if providersis null or contains a null entry. |
| setOrdering | | public boolean setOrdering(Class<T> category, T firstProvider, T secondProvider)(Code) | | 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:
category - a Class object indicating thecategory under which the preference is to be established.
Parameters:
firstProvider - the preferred provider.
Parameters:
secondProvider - the provider to whichfirstProvider is preferred. true if a previously unset orderingwas established.
exception:
IllegalArgumentException - if either provider isnull or they are the same object.
exception:
IllegalArgumentException - if there is no categorycorresponding to category. |
| unsetOrdering | | public boolean unsetOrdering(Class<T> category, T firstProvider, T secondProvider)(Code) | | 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:
category - a Class object indicating thecategory under which the preference is to be disestablished.
Parameters:
firstProvider - the formerly preferred provider.
Parameters:
secondProvider - the provider to whichfirstProvider was formerly preferred. true if a previously set ordering wasdisestablished.
exception:
IllegalArgumentException - if either provider isnull or they are the same object.
exception:
IllegalArgumentException - if there is no categorycorresponding to category. |
|
|
|