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.
ServiceRegistry instance with a
set of categories taken from the categories
argument.true if provider is currently
registered.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.
The equals method implements an equivalence relation
on non-null object references:
x, x.equals(x) should return
true.
x and y, x.equals(y)
should return true if and only if
y.equals(x) returns true.
x, y, and z, if
x.equals(y) returns true and
y.equals(z) returns true, then
x.equals(z) should return true.
x and y, multiple invocations of
x.equals(y) consistently return true
or consistently return false, provided no
information used in equals comparisons on the
objects is modified.
x,
x.equals(null) should return false.
The equals method for class Object implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x and
y, this method returns true if and only
if x and y refer to the same object
(x == y has the value true).
Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.
deregisterAll method is called to deregister all
currently registered service providers. This method should not
be called from application code.Iterator of Class objects
indicating the current set of categories. The iterator will be
empty if no categories exist.null
is returned.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.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).
java.util.Hashtable.
The general contract of hashCode is:
hashCode method on each of
the two objects must produce the same integer result.
As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)
ClassLoader cl = Thread.currentThread().getContextClassLoader(); return Service.providers(service, cl);
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.
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
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.
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.
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.
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.
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
false is returned.
The ordering will be used by the
getServiceProviders methods when their
useOrdering argument is true.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.