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:

    • Get the name of an implementation class. The name is the first non-null value obtained from the following resources:
      • The value of the (scoped) system property whose name is the same as the SPI's fully qualified class name (as given by SPI.class.getName()). The 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().

      • The value of a 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()).
      • The value obtained using the JDK1.3+ 'Service Provider' specification (http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html) to locate a service named SPI.class.getName(). This is implemented internally, so there is not a dependency on JDK 1.3+.
    • 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:
      • Thread Context Class Loader
      • DiscoverSingleton's Caller's Class Loader
      • SPI's Class Loader
      • DiscoverSingleton's (this class or wrapper) Class Loader
      • System Class Loader
      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:
      • SPI's Class Loader
      • DiscoverSingleton's (this class or wrapper) Class Loader
      • System Class Loader

      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: 1090010 $ $Date: 2011-04-07 23:05:58 +0200 (Thu, 07 Apr 2011) $
    • Constructor Summary

      Constructors 
      Constructor Description
      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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> java.lang.String[] discoverClassNames​(SPInterface<T> spi, java.util.Properties properties)
      Discover names of SPI implementation Classes from properties.
      <T,​S extends T>
      java.lang.Class<S>
      find​(java.lang.Class<T> spiClass)
      Find class implementing SPI.
      <T,​S extends T>
      java.lang.Class<S>
      find​(java.lang.Class<T> spiClass, java.lang.String defaultImpl)
      Find class implementing SPI.
      <T,​S extends T>
      java.lang.Class<S>
      find​(java.lang.Class<T> spiClass, java.lang.String propertiesFileName, java.lang.String defaultImpl)
      Find class implementing SPI.
      <T,​S extends T>
      java.lang.Class<S>
      find​(java.lang.Class<T> spiClass, java.util.Properties properties)
      Find class implementing SPI.
      <T,​S extends T>
      java.lang.Class<S>
      find​(java.lang.Class<T> spiClass, java.util.Properties properties, java.lang.String defaultImpl)
      Find class implementing SPI.
      static <T,​S extends T>
      java.lang.Class<S>
      find​(ClassLoaders loaders, SPInterface<T> spi, PropertiesHolder properties, DefaultClassHolder<T> defaultImpl)
      Find class implementing SPI.
      ClassLoaders getClassLoaders​(java.lang.Class<?> spiClass)
      Return the class loaders holder for the given SPI.
      static java.lang.String getManagedProperty​(java.lang.String propertyName)
      Load the class whose name is given by the value of a (Managed) System Property.
      <T> T newInstance​(java.lang.Class<T> spiClass)
      Create new instance of class implementing SPI.
      <T> T newInstance​(java.lang.Class<T> spiClass, java.lang.String defaultImpl)
      Create new instance of class implementing SPI.
      <T> T newInstance​(java.lang.Class<T> spiClass, java.lang.String propertiesFileName, java.lang.String defaultImpl)
      Create new instance of class implementing SPI.
      <T> T newInstance​(java.lang.Class<T> spiClass, java.util.Properties properties)
      Create new instance of class implementing SPI.
      <T> T newInstance​(java.lang.Class<T> spiClass, java.util.Properties properties, java.lang.String defaultImpl)
      Create new instance of class implementing SPI.
      static <T> T newInstance​(ClassLoaders loaders, SPInterface<T> spi, PropertiesHolder properties, DefaultClassHolder<T> defaultImpl)
      Create new instance of class implementing SPI.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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.
        Parameters:
        classLoaders - The class loaders holder
    • Method Detail

      • getClassLoaders

        public ClassLoaders getClassLoaders​(java.lang.Class<?> spiClass)
        Return the class loaders holder for the given SPI.
        Parameters:
        spiClass - The SPI type
        Returns:
        The class loaders holder for the given SPI
      • find

        public <T,​S extends T> java.lang.Class<S> find​(java.lang.Class<T> spiClass)
                                                      throws DiscoveryException
        Find class implementing SPI.
        Type Parameters:
        T - The SPI type
        S - Any class extending T
        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 <T,​S extends T> java.lang.Class<S> find​(java.lang.Class<T> spiClass,
                                                             java.util.Properties properties)
                                                      throws DiscoveryException
        Find class implementing SPI.
        Type Parameters:
        T - The SPI type
        S - Any class extending T
        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 <T,​S extends T> java.lang.Class<S> find​(java.lang.Class<T> spiClass,
                                                             java.lang.String defaultImpl)
                                                      throws DiscoveryException
        Find class implementing SPI.
        Type Parameters:
        T - The SPI type
        S - Any class extending T
        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 <T,​S extends T> java.lang.Class<S> find​(java.lang.Class<T> spiClass,
                                                             java.util.Properties properties,
                                                             java.lang.String defaultImpl)
                                                      throws DiscoveryException
        Find class implementing SPI.
        Type Parameters:
        T - The SPI type
        S - Any class extending T
        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 <T,​S extends T> java.lang.Class<S> find​(java.lang.Class<T> spiClass,
                                                             java.lang.String propertiesFileName,
                                                             java.lang.String defaultImpl)
                                                      throws DiscoveryException
        Find class implementing SPI.
        Type Parameters:
        T - The SPI type
        S - Any class extending T
        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 <T,​S extends T> java.lang.Class<S> find​(ClassLoaders loaders,
                                                                    SPInterface<T> spi,
                                                                    PropertiesHolder properties,
                                                                    DefaultClassHolder<T> defaultImpl)
                                                             throws DiscoveryException
        Find class implementing SPI.
        Type Parameters:
        T - The SPI type
        S - Any class extending T
        Parameters:
        loaders - The class loaders holder
        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.
      • newInstance

        public <T> T newInstance​(java.lang.Class<T> spiClass)
                          throws DiscoveryException,
                                 java.lang.InstantiationException,
                                 java.lang.IllegalAccessException,
                                 java.lang.NoSuchMethodException,
                                 java.lang.reflect.InvocationTargetException
        Create new instance of class implementing SPI.
        Type Parameters:
        T - The SPI type
        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.
        java.lang.InstantiationException - see Class.newInstance()
        java.lang.IllegalAccessException - see Class.newInstance()
        java.lang.NoSuchMethodException - see Class.newInstance()
        java.lang.reflect.InvocationTargetException - see Class.newInstance()
      • newInstance

        public <T> T newInstance​(java.lang.Class<T> spiClass,
                                 java.util.Properties properties)
                          throws DiscoveryException,
                                 java.lang.InstantiationException,
                                 java.lang.IllegalAccessException,
                                 java.lang.NoSuchMethodException,
                                 java.lang.reflect.InvocationTargetException
        Create new instance of class implementing SPI.
        Type Parameters:
        T - The SPI type
        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.
        java.lang.InstantiationException - see Class.newInstance()
        java.lang.IllegalAccessException - see Class.newInstance()
        java.lang.NoSuchMethodException - see Class.newInstance()
        java.lang.reflect.InvocationTargetException - see Class.newInstance()
      • newInstance

        public <T> T newInstance​(java.lang.Class<T> spiClass,
                                 java.lang.String defaultImpl)
                          throws DiscoveryException,
                                 java.lang.InstantiationException,
                                 java.lang.IllegalAccessException,
                                 java.lang.NoSuchMethodException,
                                 java.lang.reflect.InvocationTargetException
        Create new instance of class implementing SPI.
        Type Parameters:
        T - The SPI type
        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.
        java.lang.InstantiationException - see Class.newInstance()
        java.lang.IllegalAccessException - see Class.newInstance()
        java.lang.NoSuchMethodException - see Class.newInstance()
        java.lang.reflect.InvocationTargetException - see Class.newInstance()
      • newInstance

        public <T> T newInstance​(java.lang.Class<T> spiClass,
                                 java.util.Properties properties,
                                 java.lang.String defaultImpl)
                          throws DiscoveryException,
                                 java.lang.InstantiationException,
                                 java.lang.IllegalAccessException,
                                 java.lang.NoSuchMethodException,
                                 java.lang.reflect.InvocationTargetException
        Create new instance of class implementing SPI.
        Type Parameters:
        T - The SPI type
        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.
        java.lang.InstantiationException - see Class.newInstance()
        java.lang.IllegalAccessException - see Class.newInstance()
        java.lang.NoSuchMethodException - see Class.newInstance()
        java.lang.reflect.InvocationTargetException - see Class.newInstance()
      • newInstance

        public <T> T newInstance​(java.lang.Class<T> spiClass,
                                 java.lang.String propertiesFileName,
                                 java.lang.String defaultImpl)
                          throws DiscoveryException,
                                 java.lang.InstantiationException,
                                 java.lang.IllegalAccessException,
                                 java.lang.NoSuchMethodException,
                                 java.lang.reflect.InvocationTargetException
        Create new instance of class implementing SPI.
        Type Parameters:
        T - The SPI type
        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.
        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.
        java.lang.InstantiationException - see Class.newInstance()
        java.lang.IllegalAccessException - see Class.newInstance()
        java.lang.NoSuchMethodException - see Class.newInstance()
        java.lang.reflect.InvocationTargetException - see Class.newInstance()
      • newInstance

        public static <T> T newInstance​(ClassLoaders loaders,
                                        SPInterface<T> spi,
                                        PropertiesHolder properties,
                                        DefaultClassHolder<T> defaultImpl)
                                 throws DiscoveryException,
                                        java.lang.InstantiationException,
                                        java.lang.IllegalAccessException,
                                        java.lang.NoSuchMethodException,
                                        java.lang.reflect.InvocationTargetException
        Create new instance of class implementing SPI.
        Type Parameters:
        T - The SPI type
        Parameters:
        loaders - The class loaders holder
        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.
        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.
        java.lang.InstantiationException - see Class.newInstance()
        java.lang.IllegalAccessException - see Class.newInstance()
        java.lang.NoSuchMethodException - see Class.newInstance()
        java.lang.reflect.InvocationTargetException - see Class.newInstance()
      • discoverClassNames

        public static <T> java.lang.String[] discoverClassNames​(SPInterface<T> spi,
                                                                java.util.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());
        Type Parameters:
        T - The SPI type
        Parameters:
        spi - The SPI representation
        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.
      • getManagedProperty

        public static java.lang.String getManagedProperty​(java.lang.String propertyName)
        Load the class whose name is given by the value of a (Managed) System Property.
        Parameters:
        propertyName - the name of the system property whose value is the name of the class to load.
        Returns:
        The managed property value
        See Also:
        ManagedProperties