1   /*
    2    * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package com.sun.tools.javac.nio;
   27   
   28   import java.io.IOException;
   29   import java.nio.file.FileSystem;
   30   import java.nio.file.Path;
   31   import javax.tools.FileObject;
   32   import javax.tools.JavaFileManager;
   33   import javax.tools.JavaFileObject;
   34   
   35   /**
   36    *  File manager based on {@linkplain File java.nio.file.Path}.
   37    *
   38    *  Eventually, this should be moved to javax.tools.
   39    *  Also, JavaCompiler might reasonably provide a method getPathFileManager,
   40    *  similar to {@link javax.tools.JavaCompiler#getStandardFileManager
   41    *  getStandardFileManager}. However, would need to be handled carefully
   42    *  as another forward reference from langtools to jdk.
   43    *
   44    *  <p><b>This is NOT part of any supported API.
   45    *  If you write code that depends on this, you do so at your own risk.
   46    *  This code and its internal interfaces are subject to change or
   47    *  deletion without notice.</b>
   48    */
   49   public interface PathFileManager extends JavaFileManager {
   50       /**
   51        * Get the default file system used to create paths. If no value has been
   52        * set, the default file system is {@link FileSystems#getDefault}.
   53        */
   54       FileSystem getDefaultFileSystem();
   55   
   56       /**
   57        * Set the default file system used to create paths.
   58        * @param fs the default file system used to create any new paths.
   59        */
   60       void setDefaultFileSystem(FileSystem fs);
   61   
   62       /**
   63        * Get file objects representing the given files.
   64        *
   65        * @param paths a list of paths
   66        * @return a list of file objects
   67        * @throws IllegalArgumentException if the list of paths includes
   68        * a directory
   69        */
   70       Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(
   71           Iterable<? extends Path> paths);
   72   
   73       /**
   74        * Get file objects representing the given paths.
   75        * Convenience method equivalent to:
   76        *
   77        * <pre>
   78        *     getJavaFileObjectsFromPaths({@linkplain java.util.Arrays#asList Arrays.asList}(paths))
   79        * </pre>
   80        *
   81        * @param paths an array of paths
   82        * @return a list of file objects
   83        * @throws IllegalArgumentException if the array of files includes
   84        * a directory
   85        * @throws NullPointerException if the given array contains null
   86        * elements
   87        */
   88       Iterable<? extends JavaFileObject> getJavaFileObjects(Path... paths);
   89   
   90       /**
   91        * Return the Path for a file object that has been obtained from this
   92        * file manager.
   93        *
   94        * @param fo A file object that has been obtained from this file manager.
   95        * @return The underlying Path object.
   96        * @throws IllegalArgumentException is the file object was not obtained from
   97        * from this file manager.
   98        */
   99       Path getPath(FileObject fo);
  100   
  101       /**
  102        * Get the search path associated with the given location.
  103        *
  104        * @param location a location
  105        * @return a list of paths or {@code null} if this location has no
  106        * associated search path
  107        * @see #setLocation
  108        */
  109       Iterable<? extends Path> getLocation(Location location);
  110   
  111       /**
  112        * Associate the given search path with the given location.  Any
  113        * previous value will be discarded.
  114        *
  115        * @param location a location
  116        * @param searchPath a list of files, if {@code null} use the default
  117        * search path for this location
  118        * @see #getLocation
  119        * @throws IllegalArgumentException if location is an output
  120        * location and searchpath does not contain exactly one element
  121        * @throws IOException if location is an output location and searchpath
  122        * does not represent an existing directory
  123        */
  124       void setLocation(Location location, Iterable<? extends Path> searchPath) throws IOException;
  125   }