Skip to content

Commit

Permalink
Document issues with ClassPath, and recommend ClassGraph.
Browse files Browse the repository at this point in the history 
Relevant to #2130 and #3349.

RELNOTES=n/a
PiperOrigin-RevId: 369241326
  • Loading branch information
@cpovirk
cpovirk authored and Google Java Core Libraries committed Apr 19, 2021
1 parent 418224d commit 0ea7ced
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 8 deletions.
29 changes: 25 additions & 4 deletions android/guava/src/com/google/common/reflect/ClassPath.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,14 +56,35 @@
/**
* Scans the source of a {@link ClassLoader} and finds all loadable classes and resources.
*
* <p><b>Warning:</b> Current limitations:
* <h2>Prefer <a href="https://github.com/classgraph/classgraph/wiki">ClassGraph</a> over {@code
* ClassPath}</h2>
*
* <p>We recommend using <a href="https://github.com/classgraph/classgraph/wiki">ClassGraph</a>
* instead of {@code ClassPath}. ClassGraph improves upon {@code ClassPath} in several ways,
* including addressing many of its limitations. Limitations of {@code ClassPath} include:
*
* <ul>
* <li>Looks only for files and JARs in URLs available from {@link URLClassLoader} instances or
* the {@linkplain ClassLoader#getSystemClassLoader() system class loader}.
* <li>Only understands {@code file:} URLs.
* <li>It looks only for files and JARs in URLs available from {@link URLClassLoader} instances or
* the {@linkplain ClassLoader#getSystemClassLoader() system class loader}. This means it does
* not look for classes in the <i>module path</i>.
* <li>It understands only {@code file:} URLs. This means that it does not understand <a
* href="https://openjdk.java.net/jeps/220">{@code jrt:/} URLs</a>, among <a
* href="https://github.com/classgraph/classgraph/wiki/Classpath-specification-mechanisms">others</a>.
* <li>It does not know how to look for classes when running under an Android VM. (ClassGraph does
* not support this directly, either, but ClassGraph documents how to <a
* href="https://github.com/classgraph/classgraph/wiki/Build-Time-Scanning">perform build-time
* classpath scanning and make the results available to an Android app</a>.)
* <li>Like all of Guava, it is not tested under Windows. We have gotten <a
* href="https://github.com/google/guava/issues/2130">a report of a specific bug under
* Windows</a>.
* <li>It <a href="https://github.com/google/guava/issues/2712">returns only one resource for a
* given path</a>, even if resources with that path appear in multiple jars or directories.
* <li>It assumes that <a href="https://github.com/google/guava/issues/3349">any class with a
* {@code $} in its name is a nested class</a>.
* </ul>
*
* <h2>{@code ClassPath} and symlinks</h2>
*
* <p>In the case of directory classloaders, symlinks are supported but cycles are not traversed.
* This guarantees discovery of each <em>unique</em> loadable resource. However, not all possible
* aliases for resources on cyclic paths will be listed.
Expand Down
29 changes: 25 additions & 4 deletions guava/src/com/google/common/reflect/ClassPath.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,14 +56,35 @@
/**
* Scans the source of a {@link ClassLoader} and finds all loadable classes and resources.
*
* <p><b>Warning:</b> Current limitations:
* <h2>Prefer <a href="https://github.com/classgraph/classgraph/wiki">ClassGraph</a> over {@code
* ClassPath}</h2>
*
* <p>We recommend using <a href="https://github.com/classgraph/classgraph/wiki">ClassGraph</a>
* instead of {@code ClassPath}. ClassGraph improves upon {@code ClassPath} in several ways,
* including addressing many of its limitations. Limitations of {@code ClassPath} include:
*
* <ul>
* <li>Looks only for files and JARs in URLs available from {@link URLClassLoader} instances or
* the {@linkplain ClassLoader#getSystemClassLoader() system class loader}.
* <li>Only understands {@code file:} URLs.
* <li>It looks only for files and JARs in URLs available from {@link URLClassLoader} instances or
* the {@linkplain ClassLoader#getSystemClassLoader() system class loader}. This means it does
* not look for classes in the <i>module path</i>.
* <li>It understands only {@code file:} URLs. This means that it does not understand <a
* href="https://openjdk.java.net/jeps/220">{@code jrt:/} URLs</a>, among <a
* href="https://github.com/classgraph/classgraph/wiki/Classpath-specification-mechanisms">others</a>.
* <li>It does not know how to look for classes when running under an Android VM. (ClassGraph does
* not support this directly, either, but ClassGraph documents how to <a
* href="https://github.com/classgraph/classgraph/wiki/Build-Time-Scanning">perform build-time
* classpath scanning and make the results available to an Android app</a>.)
* <li>Like all of Guava, it is not tested under Windows. We have gotten <a
* href="https://github.com/google/guava/issues/2130">a report of a specific bug under
* Windows</a>.
* <li>It <a href="https://github.com/google/guava/issues/2712">returns only one resource for a
* given path</a>, even if resources with that path appear in multiple jars or directories.
* <li>It assumes that <a href="https://github.com/google/guava/issues/3349">any class with a
* {@code $} in its name is a nested class</a>.
* </ul>
*
* <h2>{@code ClassPath} and symlinks</h2>
*
* <p>In the case of directory classloaders, symlinks are supported but cycles are not traversed.
* This guarantees discovery of each <em>unique</em> loadable resource. However, not all possible
* aliases for resources on cyclic paths will be listed.
Expand Down

1 comment on commit 0ea7ced

@jbduncan
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Please sign in to comment.