org.apache.commons.discovery.tools

Class DiscoverClass

public class DiscoverClass extends Object

Discover class that implements a given service interface, with discovery and configuration features similar to that employed by standard Java APIs such as JAXP.

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.

DiscoverClass provides the find methods for locating a class that implements a service interface (SPI). Each form of find varies slightly, but they all perform the same basic function. The DiscoverClass.find methods proceed as follows:

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) $

Author: Richard A. Sitze Craig R. McClanahan Costin Manolache

Field Summary
static DefaultClassHoldernullDefaultImpl
Readable placeholder for a null value.
static PropertiesHoldernullProperties
Readable placeholder for a null value.
Constructor Summary
DiscoverClass()
Create a class instance with dynamic environment (thread context class loader is determined on each call).
DiscoverClass(ClassLoaders classLoaders)
Create a class instance with dynamic environment (thread context class loader is determined on each call).
Method Summary
static String[]discoverClassNames(SPInterface spi, Properties properties)

Discover names of SPI implementation Classes from properties.

Classfind(Class spiClass)
Find class implementing SPI.
Classfind(Class spiClass, Properties properties)
Find class implementing SPI.
Classfind(Class spiClass, String defaultImpl)
Find class implementing SPI.
Classfind(Class spiClass, Properties properties, String defaultImpl)
Find class implementing SPI.
Classfind(Class spiClass, String propertiesFileName, String defaultImpl)
Find class implementing SPI.
static Classfind(ClassLoaders loaders, SPInterface spi, PropertiesHolder properties, DefaultClassHolder defaultImpl)
Find class implementing SPI.
ClassLoadersgetClassLoaders(Class spiClass)
static StringgetManagedProperty(String propertyName)
Load the class whose name is given by the value of a (Managed) System Property.
ObjectnewInstance(Class spiClass)
Create new instance of class implementing SPI.
ObjectnewInstance(Class spiClass, Properties properties)
Create new instance of class implementing SPI.
ObjectnewInstance(Class spiClass, String defaultImpl)
Create new instance of class implementing SPI.
ObjectnewInstance(Class spiClass, Properties properties, String defaultImpl)
Create new instance of class implementing SPI.
ObjectnewInstance(Class spiClass, String propertiesFileName, String defaultImpl)
Create new instance of class implementing SPI.
static ObjectnewInstance(ClassLoaders loaders, SPInterface spi, PropertiesHolder properties, DefaultClassHolder defaultImpl)
Create new instance of class implementing SPI.

Field Detail

nullDefaultImpl

public static final DefaultClassHolder nullDefaultImpl
Readable placeholder for a null value.

nullProperties

public static final PropertiesHolder nullProperties
Readable placeholder for a null value.

Constructor Detail

DiscoverClass

public DiscoverClass()
Create a class instance with dynamic environment (thread context class loader is determined on each call). Dynamically construct class loaders on each call.

DiscoverClass

public DiscoverClass(ClassLoaders classLoaders)
Create a class instance with dynamic environment (thread context class loader is determined on each call). Cache static list of class loaders for each call.

Method Detail

discoverClassNames

public static String[] discoverClassNames(SPInterface spi, Properties properties)

Discover names of SPI implementation Classes from properties. The names are the non-null values, in order, obtained from the following resources:

Parameters: properties Properties that may define the implementation class name(s).

Returns: String[] Name of classes implementing the SPI.

Throws: DiscoveryException Thrown if the name of a class implementing the SPI cannot be found.

find

public Class find(Class spiClass)
Find class implementing SPI.

Parameters: spiClass Service Provider Interface Class.

Returns: 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, or if the resulting class does not implement (or extend) the SPI.

find

public Class find(Class spiClass, Properties properties)
Find class implementing SPI.

Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation.

Returns: 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, or if the resulting class does not implement (or extend) the SPI.

find

public Class find(Class spiClass, String defaultImpl)
Find class implementing SPI.

Parameters: spiClass Service Provider Interface Class. defaultImpl Default implementation name.

Returns: 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, or if the resulting class does not implement (or extend) the SPI.

find

public Class find(Class spiClass, Properties properties, String defaultImpl)
Find class implementing SPI.

Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation,. defaultImpl Default implementation class.

Returns: 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, or if the resulting class does not implement (or extend) the SPI.

find

public Class find(Class spiClass, String propertiesFileName, String defaultImpl)
Find class implementing SPI.

Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation,. defaultImpl Default implementation class.

Returns: 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, or if the resulting class does not implement (or extend) the SPI.

find

public static Class find(ClassLoaders loaders, SPInterface spi, PropertiesHolder properties, DefaultClassHolder defaultImpl)
Find class implementing SPI.

Parameters: spiClass Service Provider Interface Class. properties Used to determine name of SPI implementation,. defaultImpl Default implementation class.

Returns: 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, or if the resulting class does not implement (or extend) the SPI.

getClassLoaders

public ClassLoaders getClassLoaders(Class spiClass)

getManagedProperty

public static String getManagedProperty(String propertyName)
Load the class whose name is given by the value of a (Managed) System Property.

Parameters: attribute the name of the system property whose value is the name of the class to load.

See Also:

newInstance

public Object newInstance(Class spiClass)
Create new instance of class implementing SPI.

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.

newInstance

public Object newInstance(Class spiClass, Properties properties)
Create new instance of class implementing 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.

newInstance

public Object newInstance(Class spiClass, String defaultImpl)
Create new instance of class implementing 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.

newInstance

public Object newInstance(Class spiClass, Properties properties, String defaultImpl)
Create new instance of class implementing 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.

newInstance

public Object newInstance(Class spiClass, String propertiesFileName, String defaultImpl)
Create new instance of class implementing 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.

newInstance

public static Object newInstance(ClassLoaders loaders, SPInterface spi, PropertiesHolder properties, DefaultClassHolder defaultImpl)
Create new instance of class implementing 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.

Copyright (c) 2002 - Apache Software Foundation