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