org.apache.commons.discovery.tools

Class DiscoverClass


public class DiscoverClass
extends java.lang.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:

  • If the name of the implementation class is non-null, load that class. The class loaded is the first class loaded by the following sequence of class loaders: An exception is thrown if the class cannot be loaded.
  • If the name of the implementation class is null, AND the default implementation class name (defaultImpl) is null, then an exception is thrown.
  • If the name of the implementation class is null, AND the default implementation class (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.

  • Verify that the loaded class implements the SPI: an exception is thrown if the loaded class does not implement the SPI.
  • IMPLEMENTATION NOTE - This implementation is modelled after the SAXParserFactory and DocumentBuilderFactory implementations (corresponding to the JAXP pluggability APIs) found in Apache Xerces.

    Version:
    $Revision: 480374 $ $Date: 2006-11-28 19:33:25 -0800 (Tue, 28 Nov 2006) $
    Authors:
    Richard A. Sitze
    Craig R. McClanahan
    Costin Manolache

    Field Summary

    static DefaultClassHolder
    nullDefaultImpl
    Readable placeholder for a null value.
    static PropertiesHolder
    nullProperties
    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.
    Class
    find(Class spiClass)
    Find class implementing SPI.
    Class
    find(Class spiClass, Properties properties)
    Find class implementing SPI.
    Class
    find(Class spiClass, Properties properties, String defaultImpl)
    Find class implementing SPI.
    Class
    find(Class spiClass, String defaultImpl)
    Find class implementing SPI.
    Class
    find(Class spiClass, String propertiesFileName, String defaultImpl)
    Find class implementing SPI.
    static Class
    find(ClassLoaders loaders, SPInterface spi, PropertiesHolder properties, DefaultClassHolder defaultImpl)
    Find class implementing SPI.
    ClassLoaders
    getClassLoaders(Class spiClass)
    static String
    getManagedProperty(String propertyName)
    Load the class whose name is given by the value of a (Managed) System Property.
    Object
    newInstance(Class spiClass)
    Create new instance of class implementing SPI.
    Object
    newInstance(Class spiClass, Properties properties)
    Create new instance of class implementing SPI.
    Object
    newInstance(Class spiClass, Properties properties, String defaultImpl)
    Create new instance of class implementing SPI.
    Object
    newInstance(Class spiClass, String defaultImpl)
    Create new instance of class implementing SPI.
    Object
    newInstance(Class spiClass, String propertiesFileName, String defaultImpl)
    Create new instance of class implementing SPI.
    static Object
    newInstance(ClassLoaders loaders, SPInterface spi, PropertiesHolder properties, DefaultClassHolder defaultImpl)
    Create new instance of class implementing SPI.

    Field Details

    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 Details

    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 Details

    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:
    • ManagedProperty.getProperty(SPI.class.getName());
    • properties.getProperty(SPI.class.getName());
    Parameters:
    properties - Properties that may define the implementation class name(s).
    Returns:
    String[] Name of classes implementing the SPI.

    find

    public Class find(Class spiClass)
                throws DiscoveryException
    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)
                throws DiscoveryException
    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,
                      Properties properties,
                      String defaultImpl)
                throws DiscoveryException
    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 defaultImpl)
                throws DiscoveryException
    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,
                      String propertiesFileName,
                      String defaultImpl)
                throws DiscoveryException
    Find class implementing SPI.
    Parameters:
    spiClass - Service Provider Interface Class.
    propertiesFileName - 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)
                throws DiscoveryException
    Find class implementing SPI.
    Parameters:
    spi - 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:

    newInstance

    public Object newInstance(Class spiClass)
                throws DiscoveryException,
                       InstantiationException,
                       IllegalAccessException,
                       NoSuchMethodException,
                       InvocationTargetException
    Create new instance of class implementing SPI.
    Parameters:
    spiClass - Service Provider Interface Class.
    Returns:
    Instance of a class implementing the SPI.

    newInstance

    public Object newInstance(Class spiClass,
                              Properties properties)
                throws DiscoveryException,
                       InstantiationException,
                       IllegalAccessException,
                       NoSuchMethodException,
                       InvocationTargetException
    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.

    newInstance

    public Object newInstance(Class spiClass,
                              Properties properties,
                              String defaultImpl)
                throws DiscoveryException,
                       InstantiationException,
                       IllegalAccessException,
                       NoSuchMethodException,
                       InvocationTargetException
    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.

    newInstance

    public Object newInstance(Class spiClass,
                              String defaultImpl)
                throws DiscoveryException,
                       InstantiationException,
                       IllegalAccessException,
                       NoSuchMethodException,
                       InvocationTargetException
    Create new instance of class implementing SPI.
    Parameters:
    spiClass - Service Provider Interface Class.
    defaultImpl - Default implementation.
    Returns:
    Instance of a class implementing the SPI.

    newInstance

    public Object newInstance(Class spiClass,
                              String propertiesFileName,
                              String defaultImpl)
                throws DiscoveryException,
                       InstantiationException,
                       IllegalAccessException,
                       NoSuchMethodException,
                       InvocationTargetException
    Create new instance of class implementing SPI.
    Parameters:
    spiClass - Service Provider Interface Class.
    propertiesFileName - 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.

    newInstance

    public static Object newInstance(ClassLoaders loaders,
                                     SPInterface spi,
                                     PropertiesHolder properties,
                                     DefaultClassHolder defaultImpl)
                throws DiscoveryException,
                       InstantiationException,
                       IllegalAccessException,
                       NoSuchMethodException,
                       InvocationTargetException
    Create new instance of class implementing SPI.
    Parameters:
    spi - 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.

    Copyright (c) 2002 - Apache Software Foundation