8163190: Clarify JavaFileManager use of \"module location\"

Reviewed-by: jlahoda

langtools/src/java.compiler/share/classes/javax/tools/ForwardingJavaFileManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -165,12 +165,12 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
         fileManager.close();
     }
 
-    public Location getModuleLocation(Location location, String moduleName) throws IOException {
+    public Location getLocationForModule(Location location, String moduleName) throws IOException {
-        return fileManager.getModuleLocation(location, moduleName);
+        return fileManager.getLocationForModule(location, moduleName);
     }
 
-    public Location getModuleLocation(Location location, JavaFileObject fo, String pkgName) throws IOException {
+    public Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
-        return fileManager.getModuleLocation(location, fo, pkgName);
+        return fileManager.getLocationForModule(location, fo, pkgName);
     }
 
     public <S> ServiceLoader<S> getServiceLoader(Location location, Class<S> service) throws  IOException {
@@ -181,7 +181,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
         return fileManager.inferModuleName(location);
     }
 
-    public Iterable<Set<Location>> listModuleLocations(Location location) throws IOException {
+    public Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
-        return fileManager.listModuleLocations(location);
+        return fileManager.listLocationsForModules(location);
     }
 }

langtools/src/java.compiler/share/classes/javax/tools/JavaFileManager.java

@@ -109,6 +109,28 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
     /**
      * Interface for locations of file objects.  Used by file managers
      * to determine where to place or search for file objects.
+     *
+     * <p>Informally, a {@code Location} corresponds to a "search path", such as a class
+     * path or module path, as used by command-line tools that use the default file system.
+     *
+     * <p>Some locations are typically used to identify a place in which
+     * a tool can find files to be read; others are typically used to identify
+     * a place where a tool can write files. If a location is used to identify
+     * a place for reading files, those files may be organized in a simple
+     * <em>package/class</em> hierarchy: such locations are described as
+     * <strong>package-oriented</strong>.
+     * Alternatively, the files may be organized in a <em>module/package/class</em>
+     * hierarchy: such locations are described as <strong>module-oriented</strong>.
+     * If a location is typically used to identify a place where a tool can write files,
+     * it is up to the tool that writes the files to specify how those files will be
+     * organized.
+     *
+     * <p>You can access the classes in a package-oriented location using methods like
+     * {@link JavaFileManager#getJavaFileForInput} or {@link JavaFileManager#list}.
+     * It is not possible to directly list the classes in a module-oriented
+     * location. Instead, you can get a package-oriented location for any specific module
+     * using methods like {@link JavaFileManager#getLocationForModule} or
+     * {@link JavaFileManager#listLocationsForModule}.
      */
     interface Location {
         /**
@@ -119,30 +141,41 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
         String getName();
 
         /**
-         * Determines if this is an output location.  An output
+         * Determines if this is an output location.
-         * location is a location that is conventionally used for
+         * An output location is a location that is conventionally used for
          * output.
          *
+         * @apiNote An output location may be used to write files in either
+         * a package-oriented organization or in a module-oriented organization.
+         *
          * @return true if this is an output location, false otherwise
          */
         boolean isOutputLocation();
 
         /**
-         * Indicates if this location is expected to contain modules,
+         * Indicates if this location is module-oriented location, and therefore
-         * as compared to a location which contains packages and classes.
+         * expected to contain classes in a <em>module/package/class</em>
+         * hierarchy, as compared to a package-oriented location, which
+         * is expected to contain classes in a <em>package/class</em> hierarchy.
+         * The result of this method is undefined if this is an output
+         * location.
+         *
+         * @implNote This implementation returns true if the name includes
+         * the word "MODULE".
          *
          * @return true if this location is expected to contain modules
          * @since 9
          */
-        default boolean isModuleLocation() {
+        default boolean isModuleOrientedLocation() {
-            return false;
+            return getName().matches("\\bMODULE\\b");
         }
     }
 
     /**
      * Returns a class loader for loading plug-ins from the given
-     * location.  For example, to load annotation processors, a
+     * package-oriented location.
-     * compiler will request a class loader for the {@link
+     * For example, to load annotation processors,
+     * a compiler will request a class loader for the {@link
      * StandardLocation#ANNOTATION_PROCESSOR_PATH
      * ANNOTATION_PROCESSOR_PATH} location.
      *
@@ -154,13 +187,14 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * in the current security context
      * @throws IllegalStateException if {@link #close} has been called
      * and this file manager cannot be reopened
+     * @throws IllegalArgumentException if the location is a module-oriented location
      */
     ClassLoader getClassLoader(Location location);
 
     /**
      * Lists all file objects matching the given criteria in the given
-     * location.  List file objects in "subpackages" if recurse is
+     * package-oriented location.
-     * true.
+     * List file objects in "subpackages" if recurse is true.
      *
      * <p>Note: even if the given location is unknown to this file
      * manager, it may not return {@code null}.  Also, an unknown
@@ -174,6 +208,7 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * @throws IOException if an I/O error occurred, or if {@link
      * #close} has been called and this file manager cannot be
      * reopened
+     * @throws IllegalArgumentException if the location is a module-oriented location
      * @throws IllegalStateException if {@link #close} has been called
      * and this file manager cannot be reopened
      */
@@ -184,14 +219,15 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
         throws IOException;
 
     /**
-     * Infers a binary name of a file object based on a location.  The
+     * Infers a binary name of a file object based on a package-oriented location.
-     * binary name returned might not be a valid binary name according to
+     * The binary name returned might not be a valid binary name according to
      * <cite>The Java&trade; Language Specification</cite>.
      *
      * @param location a location
      * @param file a file object
      * @return a binary name or {@code null} the file object is not
      * found in the given location
+     * @throws IllegalArgumentException if the location is a module-oriented location
      * @throws IllegalStateException if {@link #close} has been called
      * and this file manager cannot be reopened
      */
@@ -239,7 +275,7 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
     /**
      * Returns a {@linkplain JavaFileObject file object} for input
      * representing the specified class of the specified kind in the
-     * given location.
+     * given package-oriented location.
      *
      * @param location a location
      * @param className the name of a class
@@ -250,7 +286,8 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * file does not exist
      * @throws IllegalArgumentException if the location is not known
      * to this file manager and the file manager does not support
-     * unknown locations, or if the kind is not valid
+     * unknown locations, or if the kind is not valid, or if the
+     * location is a module-oriented location
      * @throws IOException if an I/O error occurred, or if {@link
      * #close} has been called and this file manager cannot be
      * reopened
@@ -265,7 +302,7 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
     /**
      * Returns a {@linkplain JavaFileObject file object} for output
      * representing the specified class of the specified kind in the
-     * given location.
+     * given package-oriented location.
      *
      * <p>Optionally, this file manager might consider the sibling as
      * a hint for where to place the output.  The exact semantics of
@@ -276,7 +313,7 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * the originating source file as sibling when calling this
      * method.
      *
-     * @param location a location
+     * @param location a package-oriented location
      * @param className the name of a class
      * @param kind the kind of file, must be one of {@link
      * JavaFileObject.Kind#SOURCE SOURCE} or {@link
@@ -287,7 +324,8 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * @throws IllegalArgumentException if sibling is not known to
      * this file manager, or if the location is not known to this file
      * manager and the file manager does not support unknown
-     * locations, or if the kind is not valid
+     * locations, or if the kind is not valid, or if the location is
+     * not an output location
      * @throws IOException if an I/O error occurred, or if {@link
      * #close} has been called and this file manager cannot be
      * reopened
@@ -303,7 +341,7 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
     /**
      * Returns a {@linkplain FileObject file object} for input
      * representing the specified <a href="JavaFileManager.html#relative_name">relative
-     * name</a> in the specified package in the given location.
+     * name</a> in the specified package in the given package-oriented location.
      *
      * <p>If the returned object represents a {@linkplain
      * JavaFileObject.Kind#SOURCE source} or {@linkplain
@@ -325,14 +363,15 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * a valid result would be a file object representing the file
      * <code>"C:\Documents&nbsp;and&nbsp;Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties"</code>.
      *
-     * @param location a location
+     * @param location a package-oriented location
      * @param packageName a package name
      * @param relativeName a relative name
      * @return a file object, might return {@code null} if the file
      * does not exist
      * @throws IllegalArgumentException if the location is not known
      * to this file manager and the file manager does not support
-     * unknown locations, or if {@code relativeName} is not valid
+     * unknown locations, or if {@code relativeName} is not valid,
+     * or if the location is a module-oriented location
      * @throws IOException if an I/O error occurred, or if {@link
      * #close} has been called and this file manager cannot be
      * reopened
@@ -368,7 +407,7 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * relative name or next to the sibling argument.  See {@link
      * #getFileForInput getFileForInput} for an example.
      *
-     * @param location a location
+     * @param location an output location
      * @param packageName a package name
      * @param relativeName a relative name
      * @param sibling a file object to be used as hint for placement;
@@ -377,7 +416,8 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      * @throws IllegalArgumentException if sibling is not known to
      * this file manager, or if the location is not known to this file
      * manager and the file manager does not support unknown
-     * locations, or if {@code relativeName} is not valid
+     * locations, or if {@code relativeName} is not valid,
+     * or if the location is not an output location
      * @throws IOException if an I/O error occurred, or if {@link
      * #close} has been called and this file manager cannot be
      * reopened
@@ -416,7 +456,12 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
     void close() throws IOException;
 
     /**
-     * Gets a location for a named module within a module-oriented location.
+     * Gets a location for a named module within a location, which may be either
+     * a module-oriented location or an output location.
+     * The result will be an output location if the given location is
+     * an output location, or it will be a package-oriented location.
+     *
+     * @implSpec This implementation throws {@code UnsupportedOperationException}.
      *
      * @param location the module-oriented location
      * @param moduleName the name of the module to be found
@@ -424,33 +469,49 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
      *
      * @throws IOException if an I/O error occurred
      * @throws UnsupportedOperationException if this operation if not supported by this file manager
+     * @throws IllegalArgumentException if the location is neither an output location nor a
+     * module-oriented location
      * @since 9
      */ // TODO: describe failure modes
-    default Location getModuleLocation(Location location, String moduleName) throws IOException {
+    default Location getLocationForModule(Location location, String moduleName) throws IOException {
         throw new UnsupportedOperationException();
     }
 
     /**
      * Gets a location for the module containing a specific file representing a Java
-     * source or class.
+     * source or class, to be found in a module-oriented location.
+     * The result will be a package-oriented location.
      *
-     * @param location a module-oriented location
+     * @apiNote the package name is used to identify the position of the file object
+     * within the <em>module/package/class</em> hierarchy identified by by the location.
+     *
+     * @implSpec This implementation throws {@code UnsupportedOperationException}.
+     *
+     * @param location the module-oriented location
      * @param fo the file
      * @param pkgName the package name for the class(es) defined in this file
      * @return the module containing the file
      *
      * @throws IOException if an I/O error occurred
      * @throws UnsupportedOperationException if this operation if not supported by this file manager
+     * @throws IllegalArgumentException if the location is not a module-oriented location
      * @since 9
-     */ // TODO: describe failure modes
+     */
-    default Location getModuleLocation(Location location, JavaFileObject fo, String pkgName) throws IOException {
+    default Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
         throw new UnsupportedOperationException();
     }
 
     /**
      * Get a service loader for a specific service class from a given location.
      *
-     * @param location the location
+     * If the location is a module-oriented location, the service loader will use the
+     * service declarations in the modules found in that location. Otherwise, a service loader
+     * is created using the package-oriented location, in which case, the services are
+     * determined using the provider-configuration files in {@code META-INF/services}.
+     *
+     * @implSpec This implementation throws {@code UnsupportedOperationException}.
+     *
+     * @param location the module-oriented location
      * @param service  the {@code Class} object of the service class
      * @param <S> the service class
      * @return a service loader for the given service class
@@ -465,13 +526,16 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
 
     /**
      * Infer the name of the module from its location, as returned by
-     * getModuleLocation or listModuleLocations.
+     * {@code getLocationForModule} or {@code listModuleLocations}.
      *
-     * @param location a location representing a module
+     * @implSpec This implementation throws {@code UnsupportedOperationException}.
+     *
+     * @param location a package-oriented location representing a module
      * @return the name of the module
      *
      * @throws IOException if an I/O error occurred
      * @throws UnsupportedOperationException if this operation if not supported by this file manager
+     * @throws IllegalArgumentException if the location is not one known to this file manager
      * @since 9
      */ // TODO: describe failure modes
     default String inferModuleName(Location location) throws IOException {
@@ -479,16 +543,20 @@ public interface JavaFileManager extends Closeable, Flushable, OptionChecker {
     }
 
     /**
-     * Lists the modules in a module-oriented location.
+     * Lists the locations for all the modules in a module-oriented location.
+     * The locations that are returned will be package-oriented locations.
      *
-     * @param location  the location for which to list the modules
+     * @implSpec This implementation throws {@code UnsupportedOperationException}.
+     *
+     * @param location  the module-oriented location for which to list the modules
      * @return  a series of sets of locations containing modules
      *
      * @throws IOException if an I/O error occurred
      * @throws UnsupportedOperationException if this operation if not supported by this file manager
+     * @throws IllegalArgumentException if the location is not a module-oriented location
      * @since 9
      */ // TODO: describe failure modes
-    default Iterable<Set<Location>> listModuleLocations(Location location) throws IOException {
+    default Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
         throw new UnsupportedOperationException();
     }
 

langtools/src/java.compiler/share/classes/javax/tools/StandardLocation.java

@@ -109,7 +109,9 @@ public enum StandardLocation implements Location {
      * property must hold: {@code locationFor(x) ==
      * locationFor(y)} if and only if {@code x.equals(y)}.
      * The returned location will be an output location if and only if
-     * name ends with {@code "_OUTPUT"}.
+     * name ends with {@code "_OUTPUT"}. It will be considered to
+     * be a module-oriented location if the name contains the word
+     * {@code "MODULE"}.
      *
      * @param name a name
      * @return a location
@@ -149,7 +151,7 @@ public enum StandardLocation implements Location {
     }
 
     @Override
-    public boolean isModuleLocation() {
+    public boolean isModuleOrientedLocation() {
         switch (this) {
             case MODULE_SOURCE_PATH:
             case ANNOTATION_PROCESSOR_MODULE_PATH:

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/api/ClientCodeWrapper.java

@@ -348,9 +348,9 @@ public class ClientCodeWrapper {
         }
 
         @Override @DefinedBy(Api.COMPILER)
-        public Location getModuleLocation(Location location, String moduleName) throws IOException {
+        public Location getLocationForModule(Location location, String moduleName) throws IOException {
             try {
-                return clientJavaFileManager.getModuleLocation(location, moduleName);
+                return clientJavaFileManager.getLocationForModule(location, moduleName);
             } catch (ClientCodeException e) {
                 throw e;
             } catch (RuntimeException | Error e) {
@@ -359,9 +359,9 @@ public class ClientCodeWrapper {
         }
 
         @Override @DefinedBy(Api.COMPILER)
-        public Location getModuleLocation(Location location, JavaFileObject fo, String pkgName) throws IOException {
+        public Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
             try {
-                return clientJavaFileManager.getModuleLocation(location, fo, pkgName);
+                return clientJavaFileManager.getLocationForModule(location, fo, pkgName);
             } catch (ClientCodeException e) {
                 throw e;
             } catch (RuntimeException | Error e) {
@@ -381,9 +381,9 @@ public class ClientCodeWrapper {
         }
 
         @Override @DefinedBy(Api.COMPILER)
-        public Iterable<Set<Location>> listModuleLocations(Location location) throws IOException {
+        public Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
             try {
-                return clientJavaFileManager.listModuleLocations(location);
+                return clientJavaFileManager.listLocationsForModules(location);
             } catch (ClientCodeException e) {
                 throw e;
             } catch (RuntimeException | Error e) {

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/code/ModuleFinder.java

@@ -131,7 +131,7 @@ public class ModuleFinder {
                     if (outerIter.hasNext()) {
                         outer = outerIter.next();
                         try {
-                            innerIter = fileManager.listModuleLocations(outer).iterator();
+                            innerIter = fileManager.listLocationsForModules(outer).iterator();
                         } catch (IOException e) {
                             System.err.println("error listing module locations for " + outer + ": " + e);  // FIXME
                         }
@@ -282,7 +282,7 @@ public class ModuleFinder {
                         if (moduleLocationIterator.outer == StandardLocation.MODULE_SOURCE_PATH) {
                             msym.sourceLocation = l;
                             if (fileManager.hasLocation(StandardLocation.CLASS_OUTPUT)) {
-                                msym.classLocation = fileManager.getModuleLocation(StandardLocation.CLASS_OUTPUT, msym.name.toString());
+                                msym.classLocation = fileManager.getLocationForModule(StandardLocation.CLASS_OUTPUT, msym.name.toString());
                             }
                         } else {
                             msym.classLocation = l;

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Modules.java

@@ -364,7 +364,7 @@ public class Modules extends JCTree.Visitor {
                         if (msym.sourceLocation == null) {
                             msym.sourceLocation = locn;
                             if (fileManager.hasLocation(StandardLocation.CLASS_OUTPUT)) {
-                                msym.classLocation = fileManager.getModuleLocation(
+                                msym.classLocation = fileManager.getLocationForModule(
                                         StandardLocation.CLASS_OUTPUT, msym.name.toString());
                             }
                         }
@@ -466,7 +466,7 @@ public class Modules extends JCTree.Visitor {
     private Location getModuleLocation(JavaFileObject fo, Name pkgName) throws IOException {
         // For now, just check module source path.
         // We may want to check source path as well.
-        return fileManager.getModuleLocation(StandardLocation.MODULE_SOURCE_PATH,
+        return fileManager.getLocationForModule(StandardLocation.MODULE_SOURCE_PATH,
                 fo, (pkgName == null) ? null : pkgName.toString());
     }
 

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/JavacFileManager.java

@@ -671,7 +671,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
 
     @Override @DefinedBy(Api.COMPILER)
     public ClassLoader getClassLoader(Location location) {
-        nullCheck(location);
+        checkNotModuleOrientedLocation(location);
         Iterable<? extends File> path = getLocation(location);
         if (path == null)
             return null;
@@ -694,6 +694,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
                                          boolean recurse)
         throws IOException
     {
+        checkNotModuleOrientedLocation(location);
         // validatePackageName(packageName);
         nullCheck(packageName);
         nullCheck(kinds);
@@ -715,8 +716,8 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
 
     @Override @DefinedBy(Api.COMPILER)
     public String inferBinaryName(Location location, JavaFileObject file) {
+        checkNotModuleOrientedLocation(location);
         Objects.requireNonNull(file);
-        Objects.requireNonNull(location);
         // Need to match the path semantics of list(location, ...)
         Iterable<? extends Path> path = getLocationAsPaths(location);
         if (path == null) {
@@ -750,7 +751,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
                                               JavaFileObject.Kind kind)
         throws IOException
     {
-        nullCheck(location);
+        checkNotModuleOrientedLocation(location);
         // validateClassName(className);
         nullCheck(className);
         nullCheck(kind);
@@ -765,7 +766,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
                                       String relativeName)
         throws IOException
     {
-        nullCheck(location);
+        checkNotModuleOrientedLocation(location);
         // validatePackageName(packageName);
         nullCheck(packageName);
         if (!isRelativeUri(relativeName))
@@ -798,7 +799,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
                                                FileObject sibling)
         throws IOException
     {
-        nullCheck(location);
+        checkOutputLocation(location);
         // validateClassName(className);
         nullCheck(className);
         nullCheck(kind);
@@ -814,7 +815,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
                                        FileObject sibling)
         throws IOException
     {
-        nullCheck(location);
+        checkOutputLocation(location);
         // validatePackageName(packageName);
         nullCheck(packageName);
         if (!isRelativeUri(relativeName))
@@ -948,10 +949,14 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
     }
 
     @Override @DefinedBy(Api.COMPILER)
-    public Location getModuleLocation(Location location, String moduleName) throws IOException {
+    public Location getLocationForModule(Location location, String moduleName) throws IOException {
-        nullCheck(location);
+        Objects.requireNonNull(location);
+        if (!location.isOutputLocation() && !location.isModuleOrientedLocation())
+            throw new IllegalArgumentException(
+                    "location is not an output location or a module-oriented location: "
+                            + location.getName());
         nullCheck(moduleName);
-        return locations.getModuleLocation(location, moduleName);
+        return locations.getLocationForModule(location, moduleName);
     }
 
     @Override @DefinedBy(Api.COMPILER)
@@ -959,7 +964,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
         nullCheck(location);
         nullCheck(service);
         Module.getModule(getClass()).addUses(service);
-        if (location.isModuleLocation()) {
+        if (location.isModuleOrientedLocation()) {
             Collection<Path> paths = locations.getLocation(location);
             ModuleFinder finder = ModuleFinder.of(paths.toArray(new Path[paths.size()]));
             Layer bootLayer = Layer.boot();
@@ -972,8 +977,8 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
     }
 
     @Override @DefinedBy(Api.COMPILER)
-    public Location getModuleLocation(Location location, JavaFileObject fo, String pkgName) throws IOException {
+    public Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
-        nullCheck(location);
+        checkModuleOrientedLocation(location);
         if (!(fo instanceof PathFileObject))
             throw new IllegalArgumentException(fo.getName());
         int depth = 1; // allow 1 for filename
@@ -993,7 +998,7 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
             Path subpath = p.subpath(0, fc - depth);
             Path dir = (root == null) ? subpath : root.resolve(subpath);
             // need to find dir in location
-            return locations.getModuleLocation(location, dir);
+            return locations.getLocationForModule(location, dir);
         } else {
             return null;
         }
@@ -1001,14 +1006,14 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
 
     @Override @DefinedBy(Api.COMPILER)
     public String inferModuleName(Location location) {
-        nullCheck(location);
+        checkNotModuleOrientedLocation(location);
         return locations.inferModuleName(location);
     }
 
     @Override @DefinedBy(Api.COMPILER)
-    public Iterable<Set<Location>> listModuleLocations(Location location) throws IOException {
+    public Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
-        nullCheck(location);
+        checkModuleOrientedLocation(location);
-        return locations.listModuleLocations(location);
+        return locations.listLocationsForModules(location);
     }
 
     @Override @DefinedBy(Api.COMPILER)
@@ -1087,6 +1092,24 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
         return e.toString();
     }
 
+    private void checkOutputLocation(Location location) {
+        Objects.requireNonNull(location);
+        if (!location.isOutputLocation())
+            throw new IllegalArgumentException("location is not an output location: " + location.getName());
+    }
+
+    private void checkModuleOrientedLocation(Location location) {
+        Objects.requireNonNull(location);
+        if (!location.isModuleOrientedLocation())
+            throw new IllegalArgumentException("location is not module-oriented: " + location.getName());
+    }
+
+    private void checkNotModuleOrientedLocation(Location location) {
+        Objects.requireNonNull(location);
+        if (location.isModuleOrientedLocation())
+            throw new IllegalArgumentException("location is module-oriented: " + location.getName());
+    }
+
     /* Converters between files and paths.
      * These are temporary until we can update the StandardJavaFileManager API.
      */

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/file/Locations.java

@@ -415,16 +415,16 @@ public class Locations {
         abstract void setPaths(Iterable<? extends Path> files) throws IOException;
 
         /**
-         * @see JavaFileManager#getModuleLocation(Location, String)
+         * @see JavaFileManager#getLocationForModule(Location, String)
          */
-        Location getModuleLocation(String moduleName) throws IOException {
+        Location getLocationForModule(String moduleName) throws IOException {
             return null;
         }
 
         /**
-         * @see JavaFileManager#getModuleLocation(Location, JavaFileObject, String)
+         * @see JavaFileManager#getLocationForModule(Location, JavaFileObject, String)
          */
-        Location getModuleLocation(Path dir) {
+        Location getLocationForModule(Path dir) {
             return null;
         }
 
@@ -436,9 +436,9 @@ public class Locations {
         }
 
         /**
-         * @see JavaFileManager#listModuleLocations
+         * @see JavaFileManager#listLocationsForModules
          */
-        Iterable<Set<Location>> listModuleLocations() throws IOException {
+        Iterable<Set<Location>> listLocationsForModules() throws IOException {
             return null;
         }
     }
@@ -524,7 +524,7 @@ public class Locations {
         }
 
         @Override
-        Location getModuleLocation(String name) {
+        Location getLocationForModule(String name) {
             if (moduleLocations == null)
                 moduleLocations = new HashMap<>();
             Location l = moduleLocations.get(name);
@@ -904,7 +904,7 @@ public class Locations {
         }
 
         @Override
-        Iterable<Set<Location>> listModuleLocations() {
+        Iterable<Set<Location>> listLocationsForModules() {
             if (searchPath == null)
                 return Collections.emptyList();
 
@@ -1320,17 +1320,17 @@ public class Locations {
         }
 
         @Override
-        Location getModuleLocation(String name) {
+        Location getLocationForModule(String name) {
             return (moduleLocations == null) ? null : moduleLocations.get(name);
         }
 
         @Override
-        Location getModuleLocation(Path dir) {
+        Location getLocationForModule(Path dir) {
             return (pathLocations == null) ? null : pathLocations.get(dir);
         }
 
         @Override
-        Iterable<Set<Location>> listModuleLocations() {
+        Iterable<Set<Location>> listLocationsForModules() {
             if (moduleLocations == null)
                 return Collections.emptySet();
             Set<Location> locns = new LinkedHashSet<>();
@@ -1411,13 +1411,13 @@ public class Locations {
         }
 
         @Override
-        Location getModuleLocation(String name) throws IOException {
+        Location getLocationForModule(String name) throws IOException {
             initSystemModules();
             return systemModules.get(name);
         }
 
         @Override
-        Iterable<Set<Location>> listModuleLocations() throws IOException {
+        Iterable<Set<Location>> listLocationsForModules() throws IOException {
             initSystemModules();
             Set<Location> locns = new LinkedHashSet<>();
             for (Location l: systemModules.values())
@@ -1591,14 +1591,14 @@ public class Locations {
         h.setPaths(files);
     }
 
-    Location getModuleLocation(Location location, String name) throws IOException {
+    Location getLocationForModule(Location location, String name) throws IOException {
         LocationHandler h = getHandler(location);
-        return (h == null ? null : h.getModuleLocation(name));
+        return (h == null ? null : h.getLocationForModule(name));
     }
 
-    Location getModuleLocation(Location location, Path dir) {
+    Location getLocationForModule(Location location, Path dir) {
         LocationHandler h = getHandler(location);
-        return (h == null ? null : h.getModuleLocation(dir));
+        return (h == null ? null : h.getLocationForModule(dir));
     }
 
     String inferModuleName(Location location) {
@@ -1606,9 +1606,9 @@ public class Locations {
         return (h == null ? null : h.inferModuleName());
     }
 
-    Iterable<Set<Location>> listModuleLocations(Location location) throws IOException {
+    Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
         LocationHandler h = getHandler(location);
-        return (h == null ? null : h.listModuleLocations());
+        return (h == null ? null : h.listLocationsForModules());
     }
 
     protected LocationHandler getHandler(Location location) {

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/ClassWriter.java

@@ -1626,7 +1626,7 @@ public class ClassWriter extends ClassFile {
         Location outLocn;
         if (multiModuleMode) {
             ModuleSymbol msym = c.owner.kind == MDL ? (ModuleSymbol) c.owner : c.packge().modle;
-            outLocn = fileManager.getModuleLocation(CLASS_OUTPUT, msym.name.toString());
+            outLocn = fileManager.getLocationForModule(CLASS_OUTPUT, msym.name.toString());
         } else {
             outLocn = CLASS_OUTPUT;
         }

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/JNIWriter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -179,7 +179,7 @@ public class JNIWriter {
         Location outLocn;
         if (multiModuleMode) {
             ModuleSymbol msym = c.owner.kind == MDL ? (ModuleSymbol) c.owner : c.packge().modle;
-            outLocn = fileManager.getModuleLocation(StandardLocation.NATIVE_HEADER_OUTPUT, msym.name.toString());
+            outLocn = fileManager.getLocationForModule(StandardLocation.NATIVE_HEADER_OUTPUT, msym.name.toString());
         } else {
             outLocn = StandardLocation.NATIVE_HEADER_OUTPUT;
         }

langtools/src/jdk.compiler/share/classes/com/sun/tools/javac/main/Arguments.java

@@ -415,11 +415,11 @@ public class Arguments {
                 java.util.List<String> modules = Arrays.asList(options.get(Option.MODULE).split(","));
                 try {
                     for (String module : modules) {
-                        Location sourceLoc = fm.getModuleLocation(StandardLocation.MODULE_SOURCE_PATH, module);
+                        Location sourceLoc = fm.getLocationForModule(StandardLocation.MODULE_SOURCE_PATH, module);
                         if (sourceLoc == null) {
                             log.error(Errors.ModuleNotFoundInModuleSourcePath(module));
                         } else {
-                            Location classLoc = fm.getModuleLocation(StandardLocation.CLASS_OUTPUT, module);
+                            Location classLoc = fm.getLocationForModule(StandardLocation.CLASS_OUTPUT, module);
 
                             for (JavaFileObject file : fm.list(sourceLoc, "", EnumSet.of(JavaFileObject.Kind.SOURCE), true)) {
                                 String className = fm.inferBinaryName(sourceLoc, file);

langtools/src/jdk.compiler/share/classes/com/sun/tools/sjavac/comp/SmartFileManager.java

@@ -204,8 +204,8 @@ public class SmartFileManager extends ForwardingJavaFileManager<JavaFileManager>
     }
 
     @Override @DefinedBy(Api.COMPILER)
-    public Location getModuleLocation(Location location, JavaFileObject fo, String pkgName) throws IOException {
+    public Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
-        return super.getModuleLocation(location, locUnwrap(fo), pkgName);
+        return super.getLocationForModule(location, locUnwrap(fo), pkgName);
     }
 
     private static String packageNameFromFileName(String fn) {

langtools/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/main/JavadocTool.java

@@ -393,7 +393,7 @@ public class JavadocTool extends com.sun.tools.javac.main.JavaCompiler {
                 for (ModuleSymbol msym : modules.allModules()) {
                     PackageSymbol p = syms.getPackage(msym, pack);
                     if (p != null && !p.members().isEmpty()) {
-                        return fm.getModuleLocation(location, msym.name.toString());
+                        return fm.getLocationForModule(location, msym.name.toString());
                     }
                 }
 

langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java

@@ -816,7 +816,7 @@ public class ElementsTable {
     private Location getModuleLocation(Location location, String msymName)
             throws ToolException {
         try {
-            return fm.getModuleLocation(location, msymName);
+            return fm.getLocationForModule(location, msymName);
         } catch (IOException ioe) {
             String text = messager.getText("main.doclet_could_not_get_location", msymName);
             throw new ToolException(ERROR, text, ioe);

langtools/src/jdk.jdeps/share/classes/com/sun/tools/javap/JavapTask.java

@@ -910,7 +910,7 @@ public class JavapTask implements DisassemblerTool.DisassemblerTask, Messages {
             StandardLocation.MODULE_PATH
         };
         for (Location segment: locns) {
-            for (Set<Location> set: fileManager.listModuleLocations(segment)) {
+            for (Set<Location> set: fileManager.listLocationsForModules(segment)) {
                 Location result = null;
                 for (Location l: set) {
                     String name = fileManager.inferModuleName(l);

langtools/src/jdk.jshell/share/classes/jdk/jshell/MemoryFileManager.java

@@ -73,7 +73,7 @@ class MemoryFileManager implements JavaFileManager {
 
     // Upcoming Jigsaw
     private Method inferModuleNameMethod = null;
-    private Method listModuleLocationsMethod = null;
+    private Method listLocationsForModulesMethod = null;
 
     Iterable<? extends Path> getLocationAsPaths(Location loc) {
         return this.stdFileManager.getLocationAsPaths(loc);
@@ -203,13 +203,13 @@ class MemoryFileManager implements JavaFileManager {
     }
 
     // Make compatible with Jigsaw
-    public Iterable<Set<Location>> listModuleLocations(Location location) throws IOException {
+    public Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
         try {
-            if (listModuleLocationsMethod == null) {
+            if (listLocationsForModulesMethod == null) {
-                listModuleLocationsMethod = JavaFileManager.class.getDeclaredMethod("listModuleLocations", Location.class);
+                listLocationsForModulesMethod = JavaFileManager.class.getDeclaredMethod("listLocationsForModules", Location.class);
             }
             @SuppressWarnings("unchecked")
-            Iterable<Set<Location>> result = (Iterable<Set<Location>>) listModuleLocationsMethod.invoke(stdFileManager, location);
+            Iterable<Set<Location>> result = (Iterable<Set<Location>>) listLocationsForModulesMethod.invoke(stdFileManager, location);
             return result;
         } catch (NoSuchMethodException | SecurityException ex) {
             throw new InternalError("Cannot lookup JavaFileManager method", ex);

langtools/src/jdk.jshell/share/classes/jdk/jshell/SourceCodeAnalysisImpl.java

@@ -102,11 +102,13 @@ import java.util.function.Function;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
+
 import static java.util.stream.Collectors.collectingAndThen;
 import static java.util.stream.Collectors.joining;
 import static java.util.stream.Collectors.toCollection;
 import static java.util.stream.Collectors.toList;
 import static java.util.stream.Collectors.toSet;
+
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
@@ -129,6 +131,8 @@ import static jdk.jshell.Util.REPL_DOESNOTMATTER_CLASS_NAME;
 import static jdk.jshell.SourceCodeAnalysis.Completeness.DEFINITELY_INCOMPLETE;
 import static jdk.jshell.TreeDissector.printType;
 
+import static java.util.stream.Collectors.joining;
+
 /**
  * The concrete implementation of SourceCodeAnalysis.
  * @author Robert Field

langtools/test/tools/javac/T8003967/DetectMutableStaticFields.java

@@ -170,7 +170,7 @@ public class DetectMutableStaticFields {
             ConstantPoolException,
             InvalidDescriptor {
         JavaFileManager.Location location =
-                fm.getModuleLocation(StandardLocation.SYSTEM_MODULES, moduleName);
+                fm.getLocationForModule(StandardLocation.SYSTEM_MODULES, moduleName);
         if (location == null)
             throw new AssertionError("can't find module " + moduleName);
 

langtools/test/tools/javac/api/T6397104.java

@@ -73,8 +73,8 @@ public class T6397104 {
             if (hasLocation) {
                 for (Location location : StandardLocation.values()) {
                     System.err.format("  location:%s, moduleLocn:%b%n",
-                        location, location.isModuleLocation());
+                        location, location.isModuleOrientedLocation());
-                    if (location.isModuleLocation()) {
+                    if (!location.isOutputLocation()) {
                         continue;
                     }
                     fm.setLocation(location, Arrays.asList(new File(".")));

langtools/test/tools/javac/api/TestClientCodeWrapper.java

@@ -62,7 +62,7 @@ public class TestClientCodeWrapper extends JavacTestingAbstractProcessor {
             defaultFileManager = fm;
 
             for (Method m: getMethodsExcept(JavaFileManager.class,
-                        "close", "getJavaFileForInput", "getModuleLocation", "getServiceLoader")) {
+                        "close", "getJavaFileForInput", "getLocationForModule", "getServiceLoader")) {
                 test(m);
             }
 
@@ -401,15 +401,15 @@ public class TestClientCodeWrapper extends JavacTestingAbstractProcessor {
         }
 
         @Override
-        public Location getModuleLocation(Location location, String moduleName) throws IOException {
+        public Location getLocationForModule(Location location, String moduleName) throws IOException {
-            throwUserExceptionIfNeeded(fileManagerMethod, "getModuleLocation");
+            throwUserExceptionIfNeeded(fileManagerMethod, "getLocationForModule");
-            return super.getModuleLocation(location, moduleName);
+            return super.getLocationForModule(location, moduleName);
         }
 
         @Override
-        public Location getModuleLocation(Location location, JavaFileObject fo, String pkgName) throws IOException {
+        public Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
-            throwUserExceptionIfNeeded(fileManagerMethod, "getModuleLocation");
+            throwUserExceptionIfNeeded(fileManagerMethod, "getLocationForModule");
-            return super.getModuleLocation(location, fo, pkgName);
+            return super.getLocationForModule(location, fo, pkgName);
         }
 
         @Override
@@ -419,9 +419,9 @@ public class TestClientCodeWrapper extends JavacTestingAbstractProcessor {
         }
 
         @Override
-        public Iterable<Set<Location>> listModuleLocations(Location location) throws IOException {
+        public Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
-            throwUserExceptionIfNeeded(fileManagerMethod, "listModuleLocations");
+            throwUserExceptionIfNeeded(fileManagerMethod, "listLocationsForModules");
-            return super.listModuleLocations(location);
+            return super.listLocationsForModules(location);
         }
 
         public FileObject wrap(FileObject fo) {