org.apache.commons.discovery.tools
public class DiscoverSingleton extends Object
Discover singleton service providers. This
DiscoverSingleton instances are cached by the Discovery service, keyed by a combination of
In the context of this package, a service interface is defined by a Service Provider Interface (SPI). The SPI is expressed as a Java interface, abstract class, or (base) class that defines an expected programming interface.
DiscoverSingleton provides the find
methods for locating and
instantiating a singleton instance of an implementation of a service (SPI).
Each form of find
varies slightly, but they all perform the
same basic function.
The simplest find
methods are intended for direct use by
components looking for a service. If you are not sure which finder(s)
to use, you can narrow your search to one of these:
DiscoverSingleton.find
methods proceed as follows:
ScopedProperties
class provides a way to bind
properties by classloader, in a secure hierarchy similar in concept
to the way classloader find class and resource files.
See ScopedProperties
for more details.
If the ScopedProperties are not set by users, then behaviour
is equivalent to System.getProperty()
.
Properties properties
property, if provided
as a parameter, whose name is the same as the SPI's fully qualifed class
name (as given by SPI.class.getName()).
SPI.class.getName()
. This is implemented
internally, so there is not a dependency on JDK 1.3+.
defaultImpl
) is null,
then an exception is thrown.
defaultImpl
) is non-null,
then load the default implementation class. The class loaded is the
first class loaded by the following sequence of class loaders:
This limits the scope in which the default class loader can be found to the SPI, DiscoverSingleton, and System class loaders. The assumption here is that the default implementation is closely associated with the SPI or system, and is not defined in the user's application space.
An exception is thrown if the class cannot be loaded.
Variances for various forms of the find
methods are discussed with each such method.
Variances include the following concepts:
Properties
may be specified
directly, or by property file name. A property file is loaded using the
same sequence of class loaders used to load the SPI implementation:
The groupContext is used to qualify the name of the property file
name: groupContext + '.' + propertiesFileName
. If that
file is not found, then the unqualified propertyFileName is used.
In addition, groupContext is used to qualify the name of the system
property used to find the service implementation by prepending the value
of groupContext
to the property name:
groupContext> + '.' + SPI.class.getName()
.
Again, if a system property cannot be found by that name, then the
unqualified property name is used.
IMPLEMENTATION NOTE - This implementation is modelled after the SAXParserFactory and DocumentBuilderFactory implementations (corresponding to the JAXP pluggability APIs) found in Apache Xerces.
Version: $Revision: 165666 $ $Date: 2005-05-02 20:37:26 +0100 (Mon, 02 May 2005) $
Method Summary | |
---|---|
static Object | find(Class spiClass)
Find implementation of SPI.
|
static Object | find(Class spiClass, Properties properties)
Find implementation of SPI.
|
static Object | find(Class spiClass, String defaultImpl)
Find implementation of SPI.
|
static Object | find(Class spiClass, Properties properties, String defaultImpl)
Find implementation of SPI.
|
static Object | find(Class spiClass, String propertiesFileName, String defaultImpl)
Find implementation of SPI.
|
static Object | find(ClassLoaders loaders, SPInterface spi, PropertiesHolder properties, DefaultClassHolder defaultImpl)
Find implementation of SPI.
|
static void | release()
Release all internal references to previously created service
instances associated with the current thread context class loader.
|
static void | release(Class spiClass)
Release any internal references to a previously created service
instance associated with the current thread context class loader.
|
Parameters: spiClass Service Provider Interface Class.
Returns: Instance of a class implementing the SPI.
Throws: DiscoveryException Thrown if the name of a class implementing the SPI cannot be found, if the class cannot be loaded and instantiated, or if the resulting class does not implement (or extend) the SPI.
Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation, and passed to implementation.init() method if implementation implements Service interface.
Returns: Instance of a class implementing the SPI.
Throws: DiscoveryException Thrown if the name of a class implementing the SPI cannot be found, if the class cannot be loaded and instantiated, or if the resulting class does not implement (or extend) the SPI.
Parameters: spiClass Service Provider Interface Class. defaultImpl Default implementation.
Returns: Instance of a class implementing the SPI.
Throws: DiscoveryException Thrown if the name of a class implementing the SPI cannot be found, if the class cannot be loaded and instantiated, or if the resulting class does not implement (or extend) the SPI.
Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation, and passed to implementation.init() method if implementation implements Service interface. defaultImpl Default implementation.
Returns: Instance of a class implementing the SPI.
Throws: DiscoveryException Thrown if the name of a class implementing the SPI cannot be found, if the class cannot be loaded and instantiated, or if the resulting class does not implement (or extend) the SPI.
Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation, and passed to implementation.init() method if implementation implements Service interface. defaultImpl Default implementation.
Returns: Instance of a class implementing the SPI.
Throws: DiscoveryException Thrown if the name of a class implementing the SPI cannot be found, if the class cannot be loaded and instantiated, or if the resulting class does not implement (or extend) the SPI.
Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation, and passed to implementation.init() method if implementation implements Service interface. defaultImpl Default implementation.
Returns: Instance of a class implementing the SPI.
Throws: DiscoveryException Thrown if the name of a class implementing the SPI cannot be found, if the class cannot be loaded and instantiated, or if the resulting class does not implement (or extend) the SPI.
release()
method is called for service instances that
implement the Service
interface.
This is useful in environments like servlet containers,
which implement application reloading by throwing away a ClassLoader.
Dangling references to objects in that class loader would prevent
garbage collection.Service
, then call
release()
.