public class ServiceRegistry extends Object
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.SomeServicecontaining 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.
RegisterableService
Modifier and Type | Class and Description |
---|---|
static interface |
ServiceRegistry.Filter
A simple filter interface used by
ServiceRegistry.getServiceProviders to select
providers matching an arbitrary criterion. |
Constructor and Description |
---|
ServiceRegistry(Iterator<Class<?>> categories)
Constructs a
ServiceRegistry instance with a
set of categories taken from the categories
argument. |
Modifier and Type | Method and Description |
---|---|
boolean |
contains(Object provider)
Returns
true if provider is currently
registered. |
void |
deregisterAll()
Deregisters all currently registered service providers from all
categories.
|
void |
deregisterAll(Class<?> category)
Deregisters all service provider object currently registered
under the given category.
|
void |
deregisterServiceProvider(Object provider)
Removes a service provider object from all categories that
contain it.
|
<T> boolean |
deregisterServiceProvider(T provider,
Class<T> category)
Removes a service provider object from the given category.
|
void |
finalize()
Finalizes this object prior to garbage collection.
|
Iterator<Class<?>> |
getCategories()
Returns an
Iterator of Class objects
indicating the current set of categories. |
<T> T |
getServiceProviderByClass(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 an
Iterator containing all registered
service providers in the given category. |
<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. |
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.
|
void |
registerServiceProvider(Object provider)
Adds a service provider object to the registry.
|
<T> boolean |
registerServiceProvider(T provider,
Class<T> category)
Adds a service provider object to the registry.
|
void |
registerServiceProviders(Iterator<?> providers)
Adds a set of service provider objects, taken from an
Iterator to the registry. |
<T> boolean |
setOrdering(Class<T> category,
T firstProvider,
T secondProvider)
Sets a pairwise ordering between two service provider objects
within a given category.
|
<T> boolean |
unsetOrdering(Class<T> category,
T firstProvider,
T secondProvider)
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.categories
- an Iterator
containing
Class
objects to be used to define categories.IllegalArgumentException
- if
categories
is null
.public static <T> Iterator<T> lookupProviders(Class<T> providerClass, ClassLoader 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.
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
.public static <T> Iterator<T> lookupProviders(Class<T> providerClass)
ClassLoader cl = Thread.currentThread().getContextClassLoader(); return Service.providers(service, cl);
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
.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()
public void finalize() throws Throwable
deregisterAll
method is called to deregister all
currently registered service providers. This method should not
be called from application code.finalize
in class Object
Throwable
- if an error occurs during superclass
finalization.WeakReference
,
PhantomReference
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2021, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.