org.apache.commons.discovery.tools.DiscoverClass Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-discovery Show documentation
Show all versions of commons-discovery Show documentation
Its an port to fix bugs in OSGi support. ... The Apache Commons Discovery 0.5 component is about discovering, or finding,
implementations for pluggable interfaces.
The newest version!
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.discovery.tools;
import java.lang.reflect.InvocationTargetException;
import java.util.LinkedList;
import java.util.List;
import java.util.Properties;
import org.apache.commons.discovery.DiscoveryException;
import org.apache.commons.discovery.ResourceClass;
import org.apache.commons.discovery.ResourceClassIterator;
import org.apache.commons.discovery.ResourceNameIterator;
import org.apache.commons.discovery.defaults.Defaults;
import org.apache.commons.discovery.defaults.MyLogFactory;
import org.apache.commons.discovery.resource.ClassLoaders;
import org.apache.commons.discovery.resource.classes.DiscoverClasses;
import org.apache.commons.discovery.resource.names.DiscoverServiceNames;
/*
* 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) $
*/
public class DiscoverClass {
/*
* Readable placeholder for a null value.
*/
public static final PropertiesHolder nullProperties = null;
/*
* The class loaders holder.
*/
private final ClassLoaders classLoaders;
/*
* Create a class instance with dynamic environment
* (thread context class loader is determined on each call).
*
* Dynamically construct class loaders on each call.
*/
public DiscoverClass() {
this(null);
}
/*
* 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.
*
* @param classLoaders The class loaders holder
*/
public DiscoverClass(ClassLoaders classLoaders) {
this.classLoaders = classLoaders;
}
/*
* Return the class loaders holder for the given SPI.
*
* @param spiClass The SPI type
* @return The class loaders holder for the given SPI
*/
public ClassLoaders getClassLoaders(@SuppressWarnings("unused") Class spiClass) {
return classLoaders;
}
/*
* Find class implementing SPI.
*
* @param The SPI type
* @param Any class extending T
* @param spiClass Service Provider Interface Class.
* @return Class implementing the SPI.
* @exception 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.
*/
public Class find(Class spiClass) throws DiscoveryException {
return find(getClassLoaders(spiClass),
new SPInterface(spiClass),
nullProperties,
(DefaultClassHolder) null);
}
/*
* Find class implementing SPI.
*
* @param The SPI type
* @param Any class extending T
* @param spiClass Service Provider Interface Class.
* @param properties Used to determine name of SPI implementation.
* @return Class implementing the SPI.
* @exception 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.
*/
public Class find(Class spiClass, Properties properties) throws DiscoveryException {
return find(getClassLoaders(spiClass),
new SPInterface(spiClass),
new PropertiesHolder(properties),
(DefaultClassHolder) null);
}
/*
* Find class implementing SPI.
*
* @param The SPI type
* @param Any class extending T
* @param spiClass Service Provider Interface Class.
* @param defaultImpl Default implementation name.
* @return Class implementing the SPI.
* @exception 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.
*/
public Class find(Class spiClass, String defaultImpl) throws DiscoveryException {
return find(getClassLoaders(spiClass),
new SPInterface(spiClass),
nullProperties,
new DefaultClassHolder(defaultImpl));
}
/*
* Find class implementing SPI.
*
* @param The SPI type
* @param Any class extending T
* @param spiClass Service Provider Interface Class.
* @param properties Used to determine name of SPI implementation,.
* @param defaultImpl Default implementation class.
* @return Class implementing the SPI.
* @exception 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.
*/
public Class find(Class spiClass, Properties properties, String defaultImpl)
throws DiscoveryException {
return find(getClassLoaders(spiClass),
new SPInterface(spiClass),
new PropertiesHolder(properties),
new DefaultClassHolder(defaultImpl));
}
/*
* Find class implementing SPI.
*
* @param The SPI type
* @param Any class extending T
* @param spiClass Service Provider Interface Class.
* @param propertiesFileName Used to determine name of SPI implementation,.
* @param defaultImpl Default implementation class.
* @return Class implementing the SPI.
* @exception 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.
*/
public Class find(Class spiClass, String propertiesFileName, String defaultImpl)
throws DiscoveryException {
return find(getClassLoaders(spiClass),
new SPInterface(spiClass),
new PropertiesHolder(propertiesFileName),
new DefaultClassHolder(defaultImpl));
}
/*
* Find class implementing SPI.
*
* @param The SPI type
* @param Any class extending T
* @param loaders The class loaders holder
* @param spi Service Provider Interface Class.
* @param properties Used to determine name of SPI implementation,.
* @param defaultImpl Default implementation class.
* @return Class implementing the SPI.
* @exception 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.
*/
public static Class find(ClassLoaders loaders,
SPInterface spi,
PropertiesHolder properties,
DefaultClassHolder defaultImpl) throws DiscoveryException {
if (loaders == null) {
loaders = ClassLoaders.getLibLoaders(spi.getSPClass(),
DiscoverClass.class,
true);
}
Properties props = (properties == null)
? null
: properties.getProperties(spi, loaders);
String[] classNames = discoverClassNames(spi, props);
Exception error = null;
if (classNames.length > 0) {
DiscoverClasses classDiscovery = new DiscoverClasses(loaders);
for (String className : classNames) {
ResourceClassIterator classes =
classDiscovery.findResourceClasses(className);
// If it's set as a property.. it had better be there!
if (classes.hasNext()) {
ResourceClass info = classes.nextResourceClass();
try {
return info.loadClass();
} catch (Exception e) {
error = e;
}
}
}
} else {
ResourceNameIterator classIter =
(new DiscoverServiceNames(loaders)).findResourceNames(spi.getSPName());
ResourceClassIterator classes =
(new DiscoverClasses(loaders)).findResourceClasses(classIter);
if (!classes.hasNext() && defaultImpl != null) {
Class impl = Defaults.instance().findClass(spi.getSPName());
if (impl != null) return (Class) impl;
return defaultImpl.getDefaultClass(spi, loaders);
}
// Services we iterate through until we find one that loads..
while (classes.hasNext()) {
ResourceClass info = classes.nextResourceClass();
try {
return info.loadClass();
} catch (Exception e) {
error = e;
}
}
}
Class impl = Defaults.instance().findClass(spi.getSPName());
if (impl != null) return (Class) impl;
throw new DiscoveryException("No implementation defined for " + spi.getSPName(), error);
// return null;
}
/*
* Create new instance of class implementing SPI.
*
* @param The SPI type
* @param spiClass Service Provider Interface Class.
* @return Instance of a class implementing the SPI.
* @exception 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.
* @throws InstantiationException see {@link Class#newInstance()}
* @throws IllegalAccessException see {@link Class#newInstance()}
* @throws NoSuchMethodException see {@link Class#newInstance()}
* @throws InvocationTargetException see {@link Class#newInstance()}
*/
public T newInstance(Class spiClass)
throws DiscoveryException,
InstantiationException,
IllegalAccessException,
NoSuchMethodException,
InvocationTargetException {
return newInstance(getClassLoaders(spiClass),
new SPInterface(spiClass),
nullProperties,
(DefaultClassHolder) null);
}
/*
* Create new instance of class implementing SPI.
*
* @param The SPI type
* @param spiClass Service Provider Interface Class.
* @param properties Used to determine name of SPI implementation,
* and passed to implementation.init() method if
* implementation implements Service interface.
* @return Instance of a class implementing the SPI.
* @exception 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.
* @throws InstantiationException see {@link Class#newInstance()}
* @throws IllegalAccessException see {@link Class#newInstance()}
* @throws NoSuchMethodException see {@link Class#newInstance()}
* @throws InvocationTargetException see {@link Class#newInstance()}
*/
public T newInstance(Class spiClass, Properties properties) throws DiscoveryException,
InstantiationException,
IllegalAccessException,
NoSuchMethodException,
InvocationTargetException {
return newInstance(getClassLoaders(spiClass),
new SPInterface(spiClass),
new PropertiesHolder(properties),
(DefaultClassHolder) null);
}
/*
* Create new instance of class implementing SPI.
*
* @param The SPI type
* @param spiClass Service Provider Interface Class.
* @param defaultImpl Default implementation.
* @return Instance of a class implementing the SPI.
* @exception 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.
* @throws InstantiationException see {@link Class#newInstance()}
* @throws IllegalAccessException see {@link Class#newInstance()}
* @throws NoSuchMethodException see {@link Class#newInstance()}
* @throws InvocationTargetException see {@link Class#newInstance()}
*/
public T newInstance(Class spiClass, String defaultImpl) throws DiscoveryException,
InstantiationException,
IllegalAccessException,
NoSuchMethodException,
InvocationTargetException {
return newInstance(getClassLoaders(spiClass),
new SPInterface(spiClass),
nullProperties,
new DefaultClassHolder(defaultImpl));
}
/*
* Create new instance of class implementing SPI.
*
* @param The SPI type
* @param spiClass Service Provider Interface Class.
* @param properties Used to determine name of SPI implementation,
* and passed to implementation.init() method if
* implementation implements Service interface.
* @param defaultImpl Default implementation.
* @return Instance of a class implementing the SPI.
* @exception 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.
* @throws InstantiationException see {@link Class#newInstance()}
* @throws IllegalAccessException see {@link Class#newInstance()}
* @throws NoSuchMethodException see {@link Class#newInstance()}
* @throws InvocationTargetException see {@link Class#newInstance()}
*/
public T newInstance(Class spiClass, Properties properties, String defaultImpl) throws DiscoveryException,
InstantiationException,
IllegalAccessException,
NoSuchMethodException,
InvocationTargetException {
return newInstance(getClassLoaders(spiClass),
new SPInterface(spiClass),
new PropertiesHolder(properties),
new DefaultClassHolder(defaultImpl));
}
/*
* Create new instance of class implementing SPI.
*
* @param The SPI type
* @param spiClass Service Provider Interface Class.
* @param propertiesFileName Used to determine name of SPI implementation,
* and passed to implementation.init() method if
* implementation implements Service interface.
* @param defaultImpl Default implementation.
* @return Instance of a class implementing the SPI.
* @exception 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.
* @throws InstantiationException see {@link Class#newInstance()}
* @throws IllegalAccessException see {@link Class#newInstance()}
* @throws NoSuchMethodException see {@link Class#newInstance()}
* @throws InvocationTargetException see {@link Class#newInstance()}
*/
public T newInstance(Class spiClass, String propertiesFileName, String defaultImpl)
throws DiscoveryException,
InstantiationException,
IllegalAccessException,
NoSuchMethodException,
InvocationTargetException {
return newInstance(getClassLoaders(spiClass),
new SPInterface(spiClass),
new PropertiesHolder(propertiesFileName),
new DefaultClassHolder(defaultImpl));
}
/*
* Create new instance of class implementing SPI.
*
* @param The SPI type
* @param loaders The class loaders holder
* @param spi Service Provider Interface Class.
* @param properties Used to determine name of SPI implementation,
* and passed to implementation.init() method if
* implementation implements Service interface.
* @param defaultImpl Default implementation.
* @return Instance of a class implementing the SPI.
* @exception 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.
* @throws InstantiationException see {@link Class#newInstance()}
* @throws IllegalAccessException see {@link Class#newInstance()}
* @throws NoSuchMethodException see {@link Class#newInstance()}
* @throws InvocationTargetException see {@link Class#newInstance()}
*/
public static T newInstance(ClassLoaders loaders,
SPInterface spi,
PropertiesHolder properties,
DefaultClassHolder defaultImpl) throws DiscoveryException,
InstantiationException,
IllegalAccessException,
NoSuchMethodException,
InvocationTargetException {
return spi.newInstance(find(loaders, spi, properties, defaultImpl));
}
/*
* 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());
*
*
* @param The SPI type
* @param spi The SPI representation
* @param properties Properties that may define the implementation
* class name(s).
* @return String[] Name of classes implementing the SPI.
* @exception DiscoveryException Thrown if the name of a class implementing
* the SPI cannot be found.
*/
public static String[] discoverClassNames(SPInterface spi,
Properties properties) {
List names = new LinkedList();
String spiName = spi.getSPName();
String propertyName = spi.getPropertyName();
boolean includeAltProperty = !spiName.equals(propertyName);
// Try the (managed) system property spiName
String className = getManagedProperty(spiName);
if (className != null) {
names.add(className);
}
if (includeAltProperty) {
// Try the (managed) system property propertyName
className = getManagedProperty(propertyName);
if (className != null) {
names.add(className);
}
}
if (properties != null) {
// Try the properties parameter spiName
className = properties.getProperty(spiName);
if (className != null) {
names.add(className);
}
if (includeAltProperty) {
// Try the properties parameter propertyName
className = properties.getProperty(propertyName);
if (className != null) {
names.add(className);
}
}
}
String[] results = new String[names.size()];
names.toArray(results);
return results;
}
/*
* Load the class whose name is given by the value of a (Managed)
* System Property.
*
* @param propertyName the name of the system property whose value is
* the name of the class to load.
* @return The managed property value
* @see ManagedProperties
*/
public static String getManagedProperty(String propertyName) {
String value;
try {
value = ManagedProperties.getProperty(propertyName);
} catch (SecurityException e) {
value = null;
}
return value;
}
}