diff options
Diffstat (limited to 'libjava/classpath/java/util/ServiceLoader.java')
| -rw-r--r-- | libjava/classpath/java/util/ServiceLoader.java | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/libjava/classpath/java/util/ServiceLoader.java b/libjava/classpath/java/util/ServiceLoader.java new file mode 100644 index 00000000000..9935416359e --- /dev/null +++ b/libjava/classpath/java/util/ServiceLoader.java @@ -0,0 +1,274 @@ +/* ServiceLoader.java -- Allows loading of plug-in services. + Copyright (C) 2006, 2007 Free Software Foundation + +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +02110-1301 USA. + +Linking this library statically or dynamically with other modules is +making a combined work based on this library. Thus, the terms and +conditions of the GNU General Public License cover the whole +combination. + +As a special exception, the copyright holders of this library give you +permission to link this library with independent modules to produce an +executable, regardless of the license terms of these independent +modules, and to copy and distribute the resulting executable under +terms of your choice, provided that you also meet, for each linked +independent module, the terms and conditions of the license of that +module. An independent module is a module which is not derived from +or based on this library. If you modify this library, you may extend +this exception to your version of the library, but you are not +obligated to do so. If you do not wish to do so, delete this +exception statement from your version. */ + +package java.util; + +import gnu.classpath.ServiceFactory; + +/** + * <p> + * Facilities for loading service providers. A service is + * defined by a set of interfaces or abstract classes, and + * a service provider gives a concrete implementation of this. + * Service providers may be installed as part of the runtime + * environment using JAR files in the extension directories, + * or may be simply supplied on the classpath. + * </p> + * <p> + * In terms of loading a service, the service is defined by + * a single interface or abstract class which the provider + * implements. This may not constitute the entire service, + * but is simply a mechanism by which a provider of the + * service can be loaded and its capabilities determined. + * The variety of possible services means that no more + * requirements are made of the service provider other than + * that it must have an accessible zero argument constructor + * in order to allow an instance to be created. + * </p> + * <p> + * Service providers are listed in a file named after the + * service type in the directory <code>META-INF/services</code>. + * The file contains a list of classes, and must be encoded + * using UTF-8. Whitespace is ignored. Comments can be + * included by using a <code>'#'</code> prefix; anything occurring + * on the same line after this symbol is ignored. Duplicate classes + * are ignored. + * </p> + * <p> + * The classes are loaded using the same classloader that was + * queried in order to locate the configuration file. As a result, + * the providers do not need to reside in the same JAR file as the + * resource; they merely have to be accessible to this classloader, + * which may differ from the one that loaded the file itself. + * </p> + * <p> + * Providers are located and instantiated lazily, as calls to the + * {@link #iterator()} are made. Providers are cached, and those in + * the cache are returned first. The cache may be cleared by calling + * {@link #reload()}. Service loaders always execute in the security + * context of the caller, so ideally calls should be made from a trusted + * source. + * </p> + * <p> + * Note that this class is not thread-safe, and that strange errors may + * occur as the result of the use of remote URLs occurring on the classpath, + * which lead to erroneous web pages. + * </p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public final class ServiceLoader<S> + implements Iterable<S> +{ + + /** + * The class of the service provider. + */ + private Class<S> spi; + + /** + * The class loader for the service provider. + */ + private ClassLoader loader; + + /** + * The cache of service providers. + */ + private List<S> cache; + + /** + * The {@link gnu.classpath.ServiceFactory} iterator + * from which providers are obtained. + */ + private Iterator<S> serviceIt; + + /** + * Constructs a new {@link ServiceLoader} with + * the specified provider and class loader. + * + * @param spi the service to load. + * @param loader the class loader to use. + */ + private ServiceLoader(Class<S> spi, ClassLoader loader) + { + this.spi = spi; + this.loader = loader; + cache = new ArrayList<S>(); + } + + /** + * Lazily loads the available providers. The iterator first returns + * providers from the cache, in instantiation order, followed by any + * remaining providers, which are added to the cache after loading. + * The actual loading and parsing of the configuration file takes + * place in the {@link Iterator#hasNext()} and {@link Iterator#next()} + * methods, which means that they may result in a + * {@link ServiceConfigurationError} being thrown. If such an error + * does occur, subsequent invocations will attempt to recover. + * The {@link remove()} method is not supported and instead throws + * an {@link UnsupportedOperationException}. + * + * @return an iterator that lazily loads service providers. + */ + public Iterator<S> iterator() + { + return new Iterator<S>() + { + /** + * The cache iterator. + */ + private Iterator<S> cacheIt = cache.iterator(); + + public boolean hasNext() + { + if (cacheIt.hasNext()) + return true; + if (serviceIt == null) + serviceIt = + ServiceFactory.lookupProviders(spi, loader, true); + return serviceIt.hasNext(); + } + + public S next() + { + if (cacheIt.hasNext()) + return cacheIt.next(); + if (serviceIt == null) + serviceIt = + ServiceFactory.lookupProviders(spi, loader, true); + S nextService = serviceIt.next(); + cache.add(nextService); + return nextService; + } + + public void remove() + { + throw new UnsupportedOperationException(); + } + }; + } + + /** + * Creates a new service loader for the given service, + * using the context class loader of the current thread. + * This is equivalent to calling <code>ServiceLoader.load(service, + * Thread.currentThread().getContextClassLoader())</code>. + * + * @param service the interface or abstract class that represents + * the service. + * @return a new {@link ServiceLoader} instance. + */ + public static <S> ServiceLoader<S> load(Class<S> service) + { + return load(service, + Thread.currentThread().getContextClassLoader()); + } + + /** + * Creates a new service loader for the given service, + * using the specified class loader. The class loader is + * used to access the configuration file and the service + * provider instances themselves. If the loader is + * <code>null</code>, the system class loader (or, if + * this is also <code>null</code>, the bootstrap class + * loader). + * + * @param service the interface or abstract class that represents + * the service. + * @param loader the class loader used to load the configuration + * file and service providers. + * @return a new {@link ServiceLoader} instance. + */ + public static <S> ServiceLoader<S> load(Class<S> service, + ClassLoader loader) + { + if (loader == null) + loader = ClassLoader.getSystemClassLoader(); + return new ServiceLoader(service, loader); + } + + /** + * Creates a new service loader for the given service, + * using the extension class loader. If the extension + * class loader can not be found, the system class loader + * is used (or, if this is <code>null</code>, the + * bootstrap class loader). The primary use of this method + * is to only obtain installed services, ignoring any which + * may appear on the classpath. This is equivalent to calling + * <code>load(service, extClassLoader)</code> where + * <code>extClassLoader</code> is the extension class loader + * (or <code>null</code> if this is unavailable). + * + * @param service the interface or abstract class that represents + * the service. + * @return a new {@link ServiceLoader} instance. + */ + public static <S> ServiceLoader<S> loadInstalled(Class<S> service) + { + /* We expect the extension class loader to be the parent + * of the system class loader, as in + * ClassLoader.getDefaultSystemClassLoader() */ + return load(service, + ClassLoader.getSystemClassLoader().getParent()); + } + + /** + * Clears the cache of the provider, so that all providers + * are again read from the configuration file and instantiated. + */ + public void reload() + { + cache.clear(); + } + + /** + * Returns a textual representation of this + * {@link ServiceLoader}. + * + * @return a textual representation of the + * service loader. + */ + public String toString() + { + return getClass().getName() + + "[spi=" + spi + + ",loader=" + loader + + "]"; + } + +} |