Source code

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