001/*
002 * Copyright (C) 2012 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.reflect;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static com.google.common.base.StandardSystemProperty.JAVA_CLASS_PATH;
020import static com.google.common.base.StandardSystemProperty.PATH_SEPARATOR;
021import static java.util.logging.Level.WARNING;
022
023import com.google.common.annotations.Beta;
024import com.google.common.annotations.VisibleForTesting;
025import com.google.common.base.CharMatcher;
026import com.google.common.base.Predicate;
027import com.google.common.base.Splitter;
028import com.google.common.collect.FluentIterable;
029import com.google.common.collect.ImmutableList;
030import com.google.common.collect.ImmutableMap;
031import com.google.common.collect.ImmutableSet;
032import com.google.common.collect.Maps;
033import com.google.common.collect.MultimapBuilder;
034import com.google.common.collect.SetMultimap;
035import com.google.common.collect.Sets;
036import com.google.common.io.ByteSource;
037import com.google.common.io.CharSource;
038import com.google.common.io.Resources;
039import java.io.File;
040import java.io.IOException;
041import java.net.MalformedURLException;
042import java.net.URISyntaxException;
043import java.net.URL;
044import java.net.URLClassLoader;
045import java.nio.charset.Charset;
046import java.util.Enumeration;
047import java.util.HashSet;
048import java.util.LinkedHashMap;
049import java.util.Map;
050import java.util.NoSuchElementException;
051import java.util.Set;
052import java.util.jar.Attributes;
053import java.util.jar.JarEntry;
054import java.util.jar.JarFile;
055import java.util.jar.Manifest;
056import java.util.logging.Logger;
057import org.checkerframework.checker.nullness.compatqual.NullableDecl;
058
059/**
060 * Scans the source of a {@link ClassLoader} and finds all loadable classes and resources.
061 *
062 * <p><b>Warning:</b> Current limitations:
063 *
064 * <ul>
065 *   <li>Looks only for files and JARs in URLs available from {@link URLClassLoader} instances or
066 *       the {@linkplain ClassLoader#getSystemClassLoader() system class loader}.
067 *   <li>Only understands {@code file:} URLs.
068 * </ul>
069 *
070 * <p>In the case of directory classloaders, symlinks are supported but cycles are not traversed.
071 * This guarantees discovery of each <em>unique</em> loadable resource. However, not all possible
072 * aliases for resources on cyclic paths will be listed.
073 *
074 * @author Ben Yu
075 * @since 14.0
076 */
077@Beta
078public final class ClassPath {
079  private static final Logger logger = Logger.getLogger(ClassPath.class.getName());
080
081  private static final Predicate<ClassInfo> IS_TOP_LEVEL =
082      new Predicate<ClassInfo>() {
083        @Override
084        public boolean apply(ClassInfo info) {
085          return info.className.indexOf('$') == -1;
086        }
087      };
088
089  /** Separator for the Class-Path manifest attribute value in jar files. */
090  private static final Splitter CLASS_PATH_ATTRIBUTE_SEPARATOR =
091      Splitter.on(" ").omitEmptyStrings();
092
093  private static final String CLASS_FILE_NAME_EXTENSION = ".class";
094
095  private final ImmutableSet<ResourceInfo> resources;
096
097  private ClassPath(ImmutableSet<ResourceInfo> resources) {
098    this.resources = resources;
099  }
100
101  /**
102   * Returns a {@code ClassPath} representing all classes and resources loadable from {@code
103   * classloader} and its ancestor class loaders.
104   *
105   * <p><b>Warning:</b> {@code ClassPath} can find classes and resources only from:
106   *
107   * <ul>
108   *   <li>{@link URLClassLoader} instances' {@code file:} URLs
109   *   <li>the {@linkplain ClassLoader#getSystemClassLoader() system class loader}. To search the
110   *       system class loader even when it is not a {@link URLClassLoader} (as in Java 9), {@code
111   *       ClassPath} searches the files from the {@code java.class.path} system property.
112   * </ul>
113   *
114   * @throws IOException if the attempt to read class path resources (jar files or directories)
115   *     failed.
116   */
117  public static ClassPath from(ClassLoader classloader) throws IOException {
118    DefaultScanner scanner = new DefaultScanner();
119    scanner.scan(classloader);
120    return new ClassPath(scanner.getResources());
121  }
122
123  /**
124   * Returns all resources loadable from the current class path, including the class files of all
125   * loadable classes but excluding the "META-INF/MANIFEST.MF" file.
126   */
127  public ImmutableSet<ResourceInfo> getResources() {
128    return resources;
129  }
130
131  /**
132   * Returns all classes loadable from the current class path.
133   *
134   * @since 16.0
135   */
136  public ImmutableSet<ClassInfo> getAllClasses() {
137    return FluentIterable.from(resources).filter(ClassInfo.class).toSet();
138  }
139
140  /** Returns all top level classes loadable from the current class path. */
141  public ImmutableSet<ClassInfo> getTopLevelClasses() {
142    return FluentIterable.from(resources).filter(ClassInfo.class).filter(IS_TOP_LEVEL).toSet();
143  }
144
145  /** Returns all top level classes whose package name is {@code packageName}. */
146  public ImmutableSet<ClassInfo> getTopLevelClasses(String packageName) {
147    checkNotNull(packageName);
148    ImmutableSet.Builder<ClassInfo> builder = ImmutableSet.builder();
149    for (ClassInfo classInfo : getTopLevelClasses()) {
150      if (classInfo.getPackageName().equals(packageName)) {
151        builder.add(classInfo);
152      }
153    }
154    return builder.build();
155  }
156
157  /**
158   * Returns all top level classes whose package name is {@code packageName} or starts with {@code
159   * packageName} followed by a '.'.
160   */
161  public ImmutableSet<ClassInfo> getTopLevelClassesRecursive(String packageName) {
162    checkNotNull(packageName);
163    String packagePrefix = packageName + '.';
164    ImmutableSet.Builder<ClassInfo> builder = ImmutableSet.builder();
165    for (ClassInfo classInfo : getTopLevelClasses()) {
166      if (classInfo.getName().startsWith(packagePrefix)) {
167        builder.add(classInfo);
168      }
169    }
170    return builder.build();
171  }
172
173  /**
174   * Represents a class path resource that can be either a class file or any other resource file
175   * loadable from the class path.
176   *
177   * @since 14.0
178   */
179  @Beta
180  public static class ResourceInfo {
181    private final File file;
182    private final String resourceName;
183
184    final ClassLoader loader;
185
186    static ResourceInfo of(File file, String resourceName, ClassLoader loader) {
187      if (resourceName.endsWith(CLASS_FILE_NAME_EXTENSION)) {
188        return new ClassInfo(file, resourceName, loader);
189      } else {
190        return new ResourceInfo(file, resourceName, loader);
191      }
192    }
193
194    ResourceInfo(File file, String resourceName, ClassLoader loader) {
195      this.file = checkNotNull(file);
196      this.resourceName = checkNotNull(resourceName);
197      this.loader = checkNotNull(loader);
198    }
199
200    /**
201     * Returns the url identifying the resource.
202     *
203     * <p>See {@link ClassLoader#getResource}
204     *
205     * @throws NoSuchElementException if the resource cannot be loaded through the class loader,
206     *     despite physically existing in the class path.
207     */
208    public final URL url() {
209      URL url = loader.getResource(resourceName);
210      if (url == null) {
211        throw new NoSuchElementException(resourceName);
212      }
213      return url;
214    }
215
216    /**
217     * Returns a {@link ByteSource} view of the resource from which its bytes can be read.
218     *
219     * @throws NoSuchElementException if the resource cannot be loaded through the class loader,
220     *     despite physically existing in the class path.
221     * @since 20.0
222     */
223    public final ByteSource asByteSource() {
224      return Resources.asByteSource(url());
225    }
226
227    /**
228     * Returns a {@link CharSource} view of the resource from which its bytes can be read as
229     * characters decoded with the given {@code charset}.
230     *
231     * @throws NoSuchElementException if the resource cannot be loaded through the class loader,
232     *     despite physically existing in the class path.
233     * @since 20.0
234     */
235    public final CharSource asCharSource(Charset charset) {
236      return Resources.asCharSource(url(), charset);
237    }
238
239    /** Returns the fully qualified name of the resource. Such as "com/mycomp/foo/bar.txt". */
240    public final String getResourceName() {
241      return resourceName;
242    }
243
244    /** Returns the file that includes this resource. */
245    final File getFile() {
246      return file;
247    }
248
249    @Override
250    public int hashCode() {
251      return resourceName.hashCode();
252    }
253
254    @Override
255    public boolean equals(Object obj) {
256      if (obj instanceof ResourceInfo) {
257        ResourceInfo that = (ResourceInfo) obj;
258        return resourceName.equals(that.resourceName) && loader == that.loader;
259      }
260      return false;
261    }
262
263    // Do not change this arbitrarily. We rely on it for sorting ResourceInfo.
264    @Override
265    public String toString() {
266      return resourceName;
267    }
268  }
269
270  /**
271   * Represents a class that can be loaded through {@link #load}.
272   *
273   * @since 14.0
274   */
275  @Beta
276  public static final class ClassInfo extends ResourceInfo {
277    private final String className;
278
279    ClassInfo(File file, String resourceName, ClassLoader loader) {
280      super(file, resourceName, loader);
281      this.className = getClassName(resourceName);
282    }
283
284    /**
285     * Returns the package name of the class, without attempting to load the class.
286     *
287     * <p>Behaves identically to {@link Package#getName()} but does not require the class (or
288     * package) to be loaded.
289     */
290    public String getPackageName() {
291      return Reflection.getPackageName(className);
292    }
293
294    /**
295     * Returns the simple name of the underlying class as given in the source code.
296     *
297     * <p>Behaves identically to {@link Class#getSimpleName()} but does not require the class to be
298     * loaded.
299     */
300    public String getSimpleName() {
301      int lastDollarSign = className.lastIndexOf('$');
302      if (lastDollarSign != -1) {
303        String innerClassName = className.substring(lastDollarSign + 1);
304        // local and anonymous classes are prefixed with number (1,2,3...), anonymous classes are
305        // entirely numeric whereas local classes have the user supplied name as a suffix
306        return CharMatcher.inRange('0', '9').trimLeadingFrom(innerClassName);
307      }
308      String packageName = getPackageName();
309      if (packageName.isEmpty()) {
310        return className;
311      }
312
313      // Since this is a top level class, its simple name is always the part after package name.
314      return className.substring(packageName.length() + 1);
315    }
316
317    /**
318     * Returns the fully qualified name of the class.
319     *
320     * <p>Behaves identically to {@link Class#getName()} but does not require the class to be
321     * loaded.
322     */
323    public String getName() {
324      return className;
325    }
326
327    /**
328     * Loads (but doesn't link or initialize) the class.
329     *
330     * @throws LinkageError when there were errors in loading classes that this class depends on.
331     *     For example, {@link NoClassDefFoundError}.
332     */
333    public Class<?> load() {
334      try {
335        return loader.loadClass(className);
336      } catch (ClassNotFoundException e) {
337        // Shouldn't happen, since the class name is read from the class path.
338        throw new IllegalStateException(e);
339      }
340    }
341
342    @Override
343    public String toString() {
344      return className;
345    }
346  }
347
348  /**
349   * Abstract class that scans through the class path represented by a {@link ClassLoader} and calls
350   * {@link #scanDirectory} and {@link #scanJarFile} for directories and jar files on the class path
351   * respectively.
352   */
353  abstract static class Scanner {
354
355    // We only scan each file once independent of the classloader that resource might be associated
356    // with. Use concurrent set so that subclasses can be thread-safe.
357    private final Set<File> scannedUris = Sets.newConcurrentHashSet();
358
359    public final void scan(ClassLoader classloader) throws IOException {
360      for (Map.Entry<File, ClassLoader> entry : getClassPathEntries(classloader).entrySet()) {
361        scan(entry.getKey(), entry.getValue());
362      }
363    }
364
365    @VisibleForTesting
366    final void scan(File file, ClassLoader classloader) throws IOException {
367      if (scannedUris.add(file.getCanonicalFile())) {
368        scanFrom(file, classloader);
369      }
370    }
371
372    /**
373     * Called each time a resource (uniqueness not guaranteed if the class path includes redundant
374     * entries)
375     */
376    protected abstract void scanResource(ResourceInfo resource) throws IOException;
377
378    protected void scanFrom(File file, ClassLoader classloader) throws IOException {
379      try {
380        if (!file.exists()) {
381          return;
382        }
383      } catch (SecurityException e) {
384        logger.warning("Cannot access " + file + ": " + e);
385        // TODO(emcmanus): consider whether to log other failure cases too.
386        return;
387      }
388      if (file.isDirectory()) {
389        scanDirectory(classloader, file);
390      } else {
391        scanJar(file, classloader);
392      }
393    }
394
395    private void scanJar(File file, ClassLoader classloader) throws IOException {
396      JarFile jarFile;
397      try {
398        jarFile = new JarFile(file);
399      } catch (IOException e) {
400        // Not a jar file
401        return;
402      }
403      try {
404        for (File path : getClassPathFromManifest(file, jarFile.getManifest())) {
405          scan(path, classloader);
406        }
407        scanJarFile(classloader, jarFile);
408      } finally {
409        try {
410          jarFile.close();
411        } catch (IOException ignored) {
412        }
413      }
414    }
415
416    /**
417     * Returns the class path URIs specified by the {@code Class-Path} manifest attribute, according
418     * to <a
419     * href="http://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#Main_Attributes">JAR
420     * File Specification</a>. If {@code manifest} is null, it means the jar file has no manifest,
421     * and an empty set will be returned.
422     */
423    @VisibleForTesting
424    static ImmutableSet<File> getClassPathFromManifest(
425        File jarFile, @NullableDecl Manifest manifest) {
426      if (manifest == null) {
427        return ImmutableSet.of();
428      }
429      ImmutableSet.Builder<File> builder = ImmutableSet.builder();
430      String classpathAttribute =
431          manifest.getMainAttributes().getValue(Attributes.Name.CLASS_PATH.toString());
432      if (classpathAttribute != null) {
433        for (String path : CLASS_PATH_ATTRIBUTE_SEPARATOR.split(classpathAttribute)) {
434          URL url;
435          try {
436            url = getClassPathEntry(jarFile, path);
437          } catch (MalformedURLException e) {
438            // Ignore bad entry
439            logger.warning("Invalid Class-Path entry: " + path);
440            continue;
441          }
442          if (url.getProtocol().equals("file")) {
443            builder.add(toFile(url));
444          }
445        }
446      }
447      return builder.build();
448    }
449
450    @VisibleForTesting
451    static ImmutableMap<File, ClassLoader> getClassPathEntries(ClassLoader classloader) {
452      LinkedHashMap<File, ClassLoader> entries = Maps.newLinkedHashMap();
453      // Search parent first, since it's the order ClassLoader#loadClass() uses.
454      ClassLoader parent = classloader.getParent();
455      if (parent != null) {
456        entries.putAll(getClassPathEntries(parent));
457      }
458      for (URL url : getClassLoaderUrls(classloader)) {
459        if (url.getProtocol().equals("file")) {
460          File file = toFile(url);
461          if (!entries.containsKey(file)) {
462            entries.put(file, classloader);
463          }
464        }
465      }
466      return ImmutableMap.copyOf(entries);
467    }
468
469    private static ImmutableList<URL> getClassLoaderUrls(ClassLoader classloader) {
470      if (classloader instanceof URLClassLoader) {
471        return ImmutableList.copyOf(((URLClassLoader) classloader).getURLs());
472      }
473      if (classloader.equals(ClassLoader.getSystemClassLoader())) {
474        return parseJavaClassPath();
475      }
476      return ImmutableList.of();
477    }
478
479    /**
480     * Returns the URLs in the class path specified by the {@code java.class.path} {@linkplain
481     * System#getProperty system property}.
482     */
483    @VisibleForTesting // TODO(b/65488446): Make this a public API.
484    static ImmutableList<URL> parseJavaClassPath() {
485      ImmutableList.Builder<URL> urls = ImmutableList.builder();
486      for (String entry : Splitter.on(PATH_SEPARATOR.value()).split(JAVA_CLASS_PATH.value())) {
487        try {
488          try {
489            urls.add(new File(entry).toURI().toURL());
490          } catch (SecurityException e) { // File.toURI checks to see if the file is a directory
491            urls.add(new URL("file", null, new File(entry).getAbsolutePath()));
492          }
493        } catch (MalformedURLException e) {
494          logger.log(WARNING, "malformed classpath entry: " + entry, e);
495        }
496      }
497      return urls.build();
498    }
499
500    /**
501     * Returns the absolute uri of the Class-Path entry value as specified in <a
502     * href="http://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#Main_Attributes">JAR
503     * File Specification</a>. Even though the specification only talks about relative urls,
504     * absolute urls are actually supported too (for example, in Maven surefire plugin).
505     */
506    @VisibleForTesting
507    static URL getClassPathEntry(File jarFile, String path) throws MalformedURLException {
508      return new URL(jarFile.toURI().toURL(), path);
509    }
510
511    @VisibleForTesting
512    void scanJarFile(ClassLoader classloader, JarFile file) throws IOException {
513      Enumeration<JarEntry> entries = file.entries();
514      while (entries.hasMoreElements()) {
515        JarEntry entry = entries.nextElement();
516        if (entry.isDirectory() || entry.getName().equals(JarFile.MANIFEST_NAME)) {
517          continue;
518        }
519        scanResource(ResourceInfo.of(new File(file.getName()), entry.getName(), classloader));
520      }
521    }
522
523    private void scanDirectory(ClassLoader classloader, File directory) throws IOException {
524      Set<File> currentPath = new HashSet<>();
525      currentPath.add(directory.getCanonicalFile());
526      scanDirectory(directory, classloader, "", currentPath);
527    }
528
529    /**
530     * Recursively scan the given directory, adding resources for each file encountered. Symlinks
531     * which have already been traversed in the current tree path will be skipped to eliminate
532     * cycles; otherwise symlinks are traversed.
533     *
534     * @param directory the root of the directory to scan
535     * @param classloader the classloader that includes resources found in {@code directory}
536     * @param packagePrefix resource path prefix inside {@code classloader} for any files found
537     *     under {@code directory}
538     * @param currentPath canonical files already visited in the current directory tree path, for
539     *     cycle elimination
540     */
541    private void scanDirectory(
542        File directory, ClassLoader classloader, String packagePrefix, Set<File> currentPath)
543        throws IOException {
544      File[] files = directory.listFiles();
545      if (files == null) {
546        logger.warning("Cannot read directory " + directory);
547        // IO error, just skip the directory
548        return;
549      }
550      for (File f : files) {
551        String name = f.getName();
552        if (f.isDirectory()) {
553          File deref = f.getCanonicalFile();
554          if (currentPath.add(deref)) {
555            scanDirectory(deref, classloader, packagePrefix + name + "/", currentPath);
556            currentPath.remove(deref);
557          }
558        } else {
559          String resourceName = packagePrefix + name;
560          if (!resourceName.equals(JarFile.MANIFEST_NAME)) {
561            scanResource(ResourceInfo.of(f, resourceName, classloader));
562          }
563        }
564      }
565    }
566  }
567
568  @VisibleForTesting
569  static final class DefaultScanner extends Scanner {
570    private final SetMultimap<ClassLoader, ResourceInfo> resources =
571        MultimapBuilder.hashKeys().linkedHashSetValues().build();
572
573    ImmutableSet<ResourceInfo> getResources() {
574      return ImmutableSet.copyOf(resources.values());
575    }
576
577    @Override
578    protected void scanResource(ResourceInfo resource) {
579      resources.put(resource.loader, resource);
580    }
581  }
582
583  @VisibleForTesting
584  static String getClassName(String filename) {
585    int classNameEnd = filename.length() - CLASS_FILE_NAME_EXTENSION.length();
586    return filename.substring(0, classNameEnd).replace('/', '.');
587  }
588
589  // TODO(benyu): Try java.nio.file.Paths#get() when Guava drops JDK 6 support.
590  @VisibleForTesting
591  static File toFile(URL url) {
592    checkArgument(url.getProtocol().equals("file"));
593    try {
594      return new File(url.toURI()); // Accepts escaped characters like %20.
595    } catch (URISyntaxException e) { // URL.toURI() doesn't escape chars.
596      return new File(url.getPath()); // Accepts non-escaped chars like space.
597    }
598  }
599}