| Frames | No Frames |
1: /* ServiceLoader.java -- Allows loading of plug-in services. 2: Copyright (C) 2006, 2007 Free Software Foundation 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package java.util; 39: 40: import gnu.classpath.ServiceFactory; 41: 42: /** 43: * <p> 44: * Facilities for loading service providers. A service is 45: * defined by a set of interfaces or abstract classes, and 46: * a service provider gives a concrete implementation of this. 47: * Service providers may be installed as part of the runtime 48: * environment using JAR files in the extension directories, 49: * or may be simply supplied on the classpath. 50: * </p> 51: * <p> 52: * In terms of loading a service, the service is defined by 53: * a single interface or abstract class which the provider 54: * implements. This may not constitute the entire service, 55: * but is simply a mechanism by which a provider of the 56: * service can be loaded and its capabilities determined. 57: * The variety of possible services means that no more 58: * requirements are made of the service provider other than 59: * that it must have an accessible zero argument constructor 60: * in order to allow an instance to be created. 61: * </p> 62: * <p> 63: * Service providers are listed in a file named after the 64: * service type in the directory <code>META-INF/services</code>. 65: * The file contains a list of classes, and must be encoded 66: * using UTF-8. Whitespace is ignored. Comments can be 67: * included by using a <code>'#'</code> prefix; anything occurring 68: * on the same line after this symbol is ignored. Duplicate classes 69: * are ignored. 70: * </p> 71: * <p> 72: * The classes are loaded using the same classloader that was 73: * queried in order to locate the configuration file. As a result, 74: * the providers do not need to reside in the same JAR file as the 75: * resource; they merely have to be accessible to this classloader, 76: * which may differ from the one that loaded the file itself. 77: * </p> 78: * <p> 79: * Providers are located and instantiated lazily, as calls to the 80: * {@link #iterator()} are made. Providers are cached, and those in 81: * the cache are returned first. The cache may be cleared by calling 82: * {@link #reload()}. Service loaders always execute in the security 83: * context of the caller, so ideally calls should be made from a trusted 84: * source. 85: * </p> 86: * <p> 87: * Note that this class is not thread-safe, and that strange errors may 88: * occur as the result of the use of remote URLs occurring on the classpath, 89: * which lead to erroneous web pages. 90: * </p> 91: * 92: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 93: * @since 1.6 94: */ 95: public final class ServiceLoader<S> 96: implements Iterable<S> 97: { 98: 99: /** 100: * The class of the service provider. 101: */ 102: private Class<S> spi; 103: 104: /** 105: * The class loader for the service provider. 106: */ 107: private ClassLoader loader; 108: 109: /** 110: * The cache of service providers. 111: */ 112: private List<S> cache; 113: 114: /** 115: * The {@link gnu.classpath.ServiceFactory} iterator 116: * from which providers are obtained. 117: */ 118: private Iterator<S> serviceIt; 119: 120: /** 121: * Constructs a new {@link ServiceLoader} with 122: * the specified provider and class loader. 123: * 124: * @param spi the service to load. 125: * @param loader the class loader to use. 126: */ 127: private ServiceLoader(Class<S> spi, ClassLoader loader) 128: { 129: this.spi = spi; 130: this.loader = loader; 131: cache = new ArrayList<S>(); 132: } 133: 134: /** 135: * Lazily loads the available providers. The iterator first returns 136: * providers from the cache, in instantiation order, followed by any 137: * remaining providers, which are added to the cache after loading. 138: * The actual loading and parsing of the configuration file takes 139: * place in the {@link Iterator#hasNext()} and {@link Iterator#next()} 140: * methods, which means that they may result in a 141: * {@link ServiceConfigurationError} being thrown. If such an error 142: * does occur, subsequent invocations will attempt to recover. 143: * The {@link remove()} method is not supported and instead throws 144: * an {@link UnsupportedOperationException}. 145: * 146: * @return an iterator that lazily loads service providers. 147: */ 148: public Iterator<S> iterator() 149: { 150: return new Iterator<S>() 151: { 152: /** 153: * The cache iterator. 154: */ 155: private Iterator<S> cacheIt = cache.iterator(); 156: 157: public boolean hasNext() 158: { 159: if (cacheIt.hasNext()) 160: return true; 161: if (serviceIt == null) 162: serviceIt = 163: ServiceFactory.lookupProviders(spi, loader, true); 164: return serviceIt.hasNext(); 165: } 166: 167: public S next() 168: { 169: if (cacheIt.hasNext()) 170: return cacheIt.next(); 171: if (serviceIt == null) 172: serviceIt = 173: ServiceFactory.lookupProviders(spi, loader, true); 174: S nextService = serviceIt.next(); 175: cache.add(nextService); 176: return nextService; 177: } 178: 179: public void remove() 180: { 181: throw new UnsupportedOperationException(); 182: } 183: }; 184: } 185: 186: /** 187: * Creates a new service loader for the given service, 188: * using the context class loader of the current thread. 189: * This is equivalent to calling <code>ServiceLoader.load(service, 190: * Thread.currentThread().getContextClassLoader())</code>. 191: * 192: * @param service the interface or abstract class that represents 193: * the service. 194: * @return a new {@link ServiceLoader} instance. 195: */ 196: public static <S> ServiceLoader<S> load(Class<S> service) 197: { 198: return load(service, 199: Thread.currentThread().getContextClassLoader()); 200: } 201: 202: /** 203: * Creates a new service loader for the given service, 204: * using the specified class loader. The class loader is 205: * used to access the configuration file and the service 206: * provider instances themselves. If the loader is 207: * <code>null</code>, the system class loader (or, if 208: * this is also <code>null</code>, the bootstrap class 209: * loader). 210: * 211: * @param service the interface or abstract class that represents 212: * the service. 213: * @param loader the class loader used to load the configuration 214: * file and service providers. 215: * @return a new {@link ServiceLoader} instance. 216: */ 217: public static <S> ServiceLoader<S> load(Class<S> service, 218: ClassLoader loader) 219: { 220: if (loader == null) 221: loader = ClassLoader.getSystemClassLoader(); 222: return new ServiceLoader(service, loader); 223: } 224: 225: /** 226: * Creates a new service loader for the given service, 227: * using the extension class loader. If the extension 228: * class loader can not be found, the system class loader 229: * is used (or, if this is <code>null</code>, the 230: * bootstrap class loader). The primary use of this method 231: * is to only obtain installed services, ignoring any which 232: * may appear on the classpath. This is equivalent to calling 233: * <code>load(service, extClassLoader)</code> where 234: * <code>extClassLoader</code> is the extension class loader 235: * (or <code>null</code> if this is unavailable). 236: * 237: * @param service the interface or abstract class that represents 238: * the service. 239: * @return a new {@link ServiceLoader} instance. 240: */ 241: public static <S> ServiceLoader<S> loadInstalled(Class<S> service) 242: { 243: /* We expect the extension class loader to be the parent 244: * of the system class loader, as in 245: * ClassLoader.getDefaultSystemClassLoader() */ 246: return load(service, 247: ClassLoader.getSystemClassLoader().getParent()); 248: } 249: 250: /** 251: * Clears the cache of the provider, so that all providers 252: * are again read from the configuration file and instantiated. 253: */ 254: public void reload() 255: { 256: cache.clear(); 257: } 258: 259: /** 260: * Returns a textual representation of this 261: * {@link ServiceLoader}. 262: * 263: * @return a textual representation of the 264: * service loader. 265: */ 266: public String toString() 267: { 268: return getClass().getName() + 269: "[spi=" + spi + 270: ",loader=" + loader + 271: "]"; 272: } 273: 274: }