content: /*
   * Copyright (c) 2007, 2013, 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package java.nio.file.spi;
  
  import java.nio.file.*;
  import java.nio.file.attribute.*;
  import java.nio.channels.*;
  import java.net.URI;
  import java.io.InputStream;
  import java.io.OutputStream;
  import java.io.IOException;
  import java.util.*;
  import java.util.concurrent.ExecutorService;
  import java.security.AccessController;
  import java.security.PrivilegedAction;
  
  /**
   * Service-provider class for file systems. The methods defined by the {@link
   * Files} class will typically delegate to an instance of this
   * class.
   *
   * <p> A file system provider is a concrete implementation of this class that
   * implements the abstract methods defined by this class. A provider is
   * identified by a {@code URI} {@link #getScheme() scheme}. The default provider
   * is identified by the URI scheme "file". It creates the {@link FileSystem} that
   * provides access to the file systems accessible to the Java virtual machine.
   * The {@link FileSystems} class defines how file system providers are located
   * and loaded. The default provider is typically a system-default provider but
   * may be overridden if the system property {@code
   * java.nio.file.spi.DefaultFileSystemProvider} is set. In that case, the
   * provider has a one argument constructor whose formal parameter type is {@code
   * FileSystemProvider}. All other providers have a zero argument constructor
   * that initializes the provider.
   *
   * <p> A provider is a factory for one or more {@link FileSystem} instances. Each
   * file system is identified by a {@code URI} where the URI's scheme matches
   * the provider's {@link #getScheme scheme}. The default file system, for example,
   * is identified by the URI {@code "file:///"}. A memory-based file system,
   * for example, may be identified by a URI such as {@code "memory:///?name=logfs"}.
   * The {@link #newFileSystem newFileSystem} method may be used to create a file
   * system, and the {@link #getFileSystem getFileSystem} method may be used to
   * obtain a reference to an existing file system created by the provider. Where
   * a provider is the factory for a single file system then it is provider dependent
   * if the file system is created when the provider is initialized, or later when
   * the {@code newFileSystem} method is invoked. In the case of the default
   * provider, the {@code FileSystem} is created when the provider is initialized.
   *
   * <p> All of the methods in this class are safe for use by multiple concurrent
   * threads.
   *
   * @since 1.7
   */
  
  public abstract class FileSystemProvider {
      // lock using when loading providers
      private static final Object lock = new Object();
  
      // installed providers
      private static volatile List<FileSystemProvider> installedProviders;
  
      // used to avoid recursive loading of instaled providers
      private static boolean loadingProviders  = false;
  
      private static Void checkPermission() {
          SecurityManager sm = System.getSecurityManager();
          if (sm != null)
              sm.checkPermission(new RuntimePermission("fileSystemProvider"));
          return null;
      }
      private FileSystemProvider(Void ignore) { }
  
      /**
       * Initializes a new instance of this class.
       *
       * <p> During construction a provider may safely access files associated
       * with the default provider but care needs to be taken to avoid circular
       * loading of other installed providers. If circular loading of installed
       * providers is detected then an unspecified error is thrown.
       *
       * @throws  SecurityException
       *          If a security manager has been installed and it denies
       *          {@link RuntimePermission}<tt>("fileSystemProvider")</tt>
       */
      protected FileSystemProvider() {
          this(checkPermission());
      }
  
      // loads all installed providers
      private static List<FileSystemProvider> loadInstalledProviders() {
          List<FileSystemProvider> list = new ArrayList<FileSystemProvider>();
  
          ServiceLoader<FileSystemProvider> sl = ServiceLoader
              .load(FileSystemProvider.class, ClassLoader.getSystemClassLoader());
  
          // ServiceConfigurationError may be throw here
          for (FileSystemProvider provider: sl) {
              String scheme = provider.getScheme();
  
              // add to list if the provider is not "file" and isn't a duplicate
              if (!scheme.equalsIgnoreCase("file")) {
                  boolean found = false;
                  for (FileSystemProvider p: list) {
                      if (p.getScheme().equalsIgnoreCase(scheme)) {
                          found = true;
                          break;
                      }
                  }
                  if (!found) {
                      list.add(provider);
                  }
              }
          }
          return list;
      }
  
      /**
       * Returns a list of the installed file system providers.
       *
       * <p> The first invocation of this method causes the default provider to be
       * initialized (if not already initialized) and loads any other installed
       * providers as described by the {@link FileSystems} class.
       *
       * @return  An unmodifiable list of the installed file system providers. The
       *          list contains at least one element, that is the default file
       *          system provider
       *
       * @throws  ServiceConfigurationError
       *          When an error occurs while loading a service provider
       */
      public static List<FileSystemProvider> installedProviders() {
          if (installedProviders == null) {
              // ensure default provider is initialized
              FileSystemProvider defaultProvider = FileSystems.getDefault().provider();
  
              synchronized (lock) {
                  if (installedProviders == null) {
                      if (loadingProviders) {
                          throw new Error("Circular loading of installed providers detected");
                      }
                      loadingProviders = true;
  
                      List<FileSystemProvider> list = AccessController
                          .doPrivileged(new PrivilegedAction<List<FileSystemProvider>>() {
                              @Override
                              public List<FileSystemProvider> run() {
                                  return loadInstalledProviders();
                          }});
  
                      // insert the default provider at the start of the list
                      list.add(0, defaultProvider);
  
                      installedProviders = Collections.unmodifiableList(list);
                  }
              }
          }
          return installedProviders;
      }
  
      /**
       * Returns the URI scheme that identifies this provider.
       *
       * @return  The URI scheme
       */
      public abstract String getScheme();
  
      /**
       * Constructs a new {@code FileSystem} object identified by a URI. This
       * method is invoked by the {@link FileSystems#newFileSystem(URI,Map)}
       * method to open a new file system identified by a URI.
       *
       * <p> The {@code uri} parameter is an absolute, hierarchical URI, with a
       * scheme equal (without regard to case) to the scheme supported by this
       * provider. The exact form of the URI is highly provider dependent. The
       * {@code env} parameter is a map of provider specific properties to configure
       * the file system.
       *
       * <p> This method throws {@link FileSystemAlreadyExistsException} if the
       * file system already exists because it was previously created by an
       * invocation of this method. Once a file system is {@link
       * FileSystem#close closed} it is provider-dependent if the
       * provider allows a new file system to be created with the same URI as a
       * file system it previously created.
       *
       * @param   uri
       *          URI reference
       * @param   env
       *          A map of provider specific properties to configure the file system;
       *          may be empty
       *
       * @return  A new file system
       *
       * @throws  IllegalArgumentException
       *          If the pre-conditions for the {@code uri} parameter aren't met,
       *          or the {@code env} parameter does not contain properties required
       *          by the provider, or a property value is invalid
       * @throws  IOException
       *          An I/O error occurs creating the file system
       * @throws  SecurityException
       *          If a security manager is installed and it denies an unspecified
       *          permission required by the file system provider implementation
       * @throws  FileSystemAlreadyExistsException
       *          If the file system has already been created
       */
      public abstract FileSystem newFileSystem(URI uri, Map<String,?> env)
          throws IOException;
  
      /**
       * Returns an existing {@code FileSystem} created by this provider.
       *
       * <p> This method returns a reference to a {@code FileSystem} that was
       * created by invoking the {@link #newFileSystem(URI,Map) newFileSystem(URI,Map)}
       * method. File systems created the {@link #newFileSystem(Path,Map)
       * newFileSystem(Path,Map)} method are not returned by this method.
       * The file system is identified by its {@code URI}. Its exact form
       * is highly provider dependent. In the case of the default provider the URI's
       * path component is {@code "/"} and the authority, query and fragment components
       * are undefined (Undefined components are represented by {@code null}).
       *
       * <p> Once a file system created by this provider is {@link
       * FileSystem#close closed} it is provider-dependent if this
       * method returns a reference to the closed file system or throws {@link
       * FileSystemNotFoundException}. If the provider allows a new file system to
       * be created with the same URI as a file system it previously created then
       * this method throws the exception if invoked after the file system is
       * closed (and before a new instance is created by the {@link #newFileSystem
       * newFileSystem} method).
       *
       * <p> If a security manager is installed then a provider implementation
       * may require to check a permission before returning a reference to an
       * existing file system. In the case of the {@link FileSystems#getDefault
       * default} file system, no permission check is required.
       *
       * @param   uri
       *          URI reference
       *
       * @return  The file system
       *
       * @throws  IllegalArgumentException
       *          If the pre-conditions for the {@code uri} parameter aren't met
       * @throws  FileSystemNotFoundException
       *          If the file system does not exist
       * @throws  SecurityException
       *          If a security manager is installed and it denies an unspecified
       *          permission.
       */
      public abstract FileSystem getFileSystem(URI uri);
  
      /**
       * Return a {@code Path} object by converting the given {@link URI}. The
       * resulting {@code Path} is associated with a {@link FileSystem} that
       * already exists or is constructed automatically.
       *
       * <p> The exact form of the URI is file system provider dependent. In the
       * case of the default provider, the URI scheme is {@code "file"} and the
       * given URI has a non-empty path component, and undefined query, and
       * fragment components. The resulting {@code Path} is associated with the
       * default {@link FileSystems#getDefault default} {@code FileSystem}.
       *
       * <p> If a security manager is installed then a provider implementation
       * may require to check a permission. In the case of the {@link
       * FileSystems#getDefault default} file system, no permission check is
       * required.
       *
       * @param   uri
       *          The URI to convert
       *
       * @return  The resulting {@code Path}
       *
       * @throws  IllegalArgumentException
       *          If the URI scheme does not identify this provider or other
       *          preconditions on the uri parameter do not hold
       * @throws  FileSystemNotFoundException
       *          The file system, identified by the URI, does not exist and
       *          cannot be created automatically
       * @throws  SecurityException
       *          If a security manager is installed and it denies an unspecified
       *          permission.
       */
      public abstract Path getPath(URI uri);
  
      /**
       * Constructs a new {@code FileSystem} to access the contents of a file as a
       * file system.
       *
       * <p> This method is intended for specialized providers of pseudo file
       * systems where the contents of one or more files is treated as a file
       * system. The {@code env} parameter is a map of provider specific properties
       * to configure the file system.
       *
       * <p> If this provider does not support the creation of such file systems
       * or if the provider does not recognize the file type of the given file then
       * it throws {@code UnsupportedOperationException}. The default implementation
       * of this method throws {@code UnsupportedOperationException}.
       *
       * @param   path
       *          The path to the file
       * @param   env
       *          A map of provider specific properties to configure the file system;
       *          may be empty
       *
       * @return  A new file system
       *
       * @throws  UnsupportedOperationException
       *          If this provider does not support access to the contents as a
       *          file system or it does not recognize the file type of the
       *          given file
       * @throws  IllegalArgumentException
       *          If the {@code env} parameter does not contain properties required
       *          by the provider, or a property value is invalid
       * @throws  IOException
       *          If an I/O error occurs
       * @throws  SecurityException
       *          If a security manager is installed and it denies an unspecified
       *          permission.
       */
      public FileSystem newFileSystem(Path path, Map<String,?> env)
          throws IOException
      {
          throw new UnsupportedOperationException();
      }
  
      /**
       * Opens a file, returning an input stream to read from the file. This
       * method works in exactly the manner specified by the {@link
       * Files#newInputStream} method.
       *
       * <p> The default implementation of this method opens a channel to the file
       * as if by invoking the {@link #newByteChannel} method and constructs a
       * stream that reads bytes from the channel. This method should be overridden
       * where appropriate.
       *
       * @param   path
       *          the path to the file to open
       * @param   options
       *          options specifying how the file is opened
       *
       * @return  a new input stream
       *
       * @throws  IllegalArgumentException
       *          if an invalid combination of options is specified
       * @throws  UnsupportedOperationException
       *          if an unsupported option is specified
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to the file.
       */
      public InputStream newInputStream(Path path, OpenOption... options)
          throws IOException
      {
          if (options.length > 0) {
              for (OpenOption opt: options) {
                  // All OpenOption values except for APPEND and WRITE are allowed
                  if (opt == StandardOpenOption.APPEND ||
                      opt == StandardOpenOption.WRITE)
                      throw new UnsupportedOperationException("'" + opt + "' not allowed");
              }
          }
          return Channels.newInputStream(Files.newByteChannel(path, options));
      }
  
      /**
       * Opens or creates a file, returning an output stream that may be used to
       * write bytes to the file. This method works in exactly the manner
       * specified by the {@link Files#newOutputStream} method.
       *
       * <p> The default implementation of this method opens a channel to the file
       * as if by invoking the {@link #newByteChannel} method and constructs a
       * stream that writes bytes to the channel. This method should be overridden
       * where appropriate.
       *
       * @param   path
       *          the path to the file to open or create
       * @param   options
       *          options specifying how the file is opened
       *
       * @return  a new output stream
       *
       * @throws  IllegalArgumentException
       *          if {@code options} contains an invalid combination of options
       * @throws  UnsupportedOperationException
       *          if an unsupported option is specified
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkWrite(String) checkWrite}
       *          method is invoked to check write access to the file. The {@link
       *          SecurityManager#checkDelete(String) checkDelete} method is
       *          invoked to check delete access if the file is opened with the
       *          {@code DELETE_ON_CLOSE} option.
       */
      public OutputStream newOutputStream(Path path, OpenOption... options)
          throws IOException
      {
          int len = options.length;
          Set<OpenOption> opts = new HashSet<OpenOption>(len + 3);
          if (len == 0) {
              opts.add(StandardOpenOption.CREATE);
              opts.add(StandardOpenOption.TRUNCATE_EXISTING);
          } else {
              for (OpenOption opt: options) {
                  if (opt == StandardOpenOption.READ)
                      throw new IllegalArgumentException("READ not allowed");
                  opts.add(opt);
              }
          }
          opts.add(StandardOpenOption.WRITE);
          return Channels.newOutputStream(newByteChannel(path, opts));
      }
  
      /**
       * Opens or creates a file for reading and/or writing, returning a file
       * channel to access the file. This method works in exactly the manner
       * specified by the {@link FileChannel#open(Path,Set,FileAttribute[])
       * FileChannel.open} method. A provider that does not support all the
       * features required to construct a file channel throws {@code
       * UnsupportedOperationException}. The default provider is required to
       * support the creation of file channels. When not overridden, the default
       * implementation throws {@code UnsupportedOperationException}.
       *
       * @param   path
       *          the path of the file to open or create
       * @param   options
       *          options specifying how the file is opened
       * @param   attrs
       *          an optional list of file attributes to set atomically when
       *          creating the file
       *
       * @return  a new file channel
       *
       * @throws  IllegalArgumentException
       *          If the set contains an invalid combination of options
       * @throws  UnsupportedOperationException
       *          If this provider that does not support creating file channels,
       *          or an unsupported open option or file attribute is specified
       * @throws  IOException
       *          If an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default file system, the {@link
       *          SecurityManager#checkRead(String)} method is invoked to check
       *          read access if the file is opened for reading. The {@link
       *          SecurityManager#checkWrite(String)} method is invoked to check
       *          write access if the file is opened for writing
       */
      public FileChannel newFileChannel(Path path,
                                        Set<? extends OpenOption> options,
                                        FileAttribute<?>... attrs)
          throws IOException
      {
          throw new UnsupportedOperationException();
      }
  
      /**
       * Opens or creates a file for reading and/or writing, returning an
       * asynchronous file channel to access the file. This method works in
       * exactly the manner specified by the {@link
       * AsynchronousFileChannel#open(Path,Set,ExecutorService,FileAttribute[])
       * AsynchronousFileChannel.open} method.
       * A provider that does not support all the features required to construct
       * an asynchronous file channel throws {@code UnsupportedOperationException}.
       * The default provider is required to support the creation of asynchronous
       * file channels. When not overridden, the default implementation of this
       * method throws {@code UnsupportedOperationException}.
       *
       * @param   path
       *          the path of the file to open or create
       * @param   options
       *          options specifying how the file is opened
       * @param   executor
       *          the thread pool or {@code null} to associate the channel with
       *          the default thread pool
       * @param   attrs
       *          an optional list of file attributes to set atomically when
       *          creating the file
       *
       * @return  a new asynchronous file channel
       *
       * @throws  IllegalArgumentException
       *          If the set contains an invalid combination of options
       * @throws  UnsupportedOperationException
       *          If this provider that does not support creating asynchronous file
       *          channels, or an unsupported open option or file attribute is
       *          specified
       * @throws  IOException
       *          If an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default file system, the {@link
       *          SecurityManager#checkRead(String)} method is invoked to check
       *          read access if the file is opened for reading. The {@link
       *          SecurityManager#checkWrite(String)} method is invoked to check
       *          write access if the file is opened for writing
       */
      public AsynchronousFileChannel newAsynchronousFileChannel(Path path,
                                                                Set<? extends OpenOption> options,
                                                                ExecutorService executor,
                                                                FileAttribute<?>... attrs)
          throws IOException
      {
          throw new UnsupportedOperationException();
      }
  
      /**
       * Opens or creates a file, returning a seekable byte channel to access the
       * file. This method works in exactly the manner specified by the {@link
       * Files#newByteChannel(Path,Set,FileAttribute[])} method.
       *
       * @param   path
       *          the path to the file to open or create
       * @param   options
       *          options specifying how the file is opened
       * @param   attrs
       *          an optional list of file attributes to set atomically when
       *          creating the file
       *
       * @return  a new seekable byte channel
       *
       * @throws  IllegalArgumentException
       *          if the set contains an invalid combination of options
       * @throws  UnsupportedOperationException
       *          if an unsupported open option is specified or the array contains
       *          attributes that cannot be set atomically when creating the file
       * @throws  FileAlreadyExistsException
       *          if a file of that name already exists and the {@link
       *          StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
       *          <i>(optional specific exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to the path if the file is
       *          opened for reading. The {@link SecurityManager#checkWrite(String)
       *          checkWrite} method is invoked to check write access to the path
       *          if the file is opened for writing. The {@link
       *          SecurityManager#checkDelete(String) checkDelete} method is
       *          invoked to check delete access if the file is opened with the
       *          {@code DELETE_ON_CLOSE} option.
       */
      public abstract SeekableByteChannel newByteChannel(Path path,
          Set<? extends OpenOption> options, FileAttribute<?>... attrs) throws IOException;
  
      /**
       * Opens a directory, returning a {@code DirectoryStream} to iterate over
       * the entries in the directory. This method works in exactly the manner
       * specified by the {@link
       * Files#newDirectoryStream(Path, DirectoryStream.Filter)}
       * method.
       *
       * @param   dir
       *          the path to the directory
       * @param   filter
       *          the directory stream filter
       *
       * @return  a new and open {@code DirectoryStream} object
       *
       * @throws  NotDirectoryException
       *          if the file could not otherwise be opened because it is not
       *          a directory <i>(optional specific exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to the directory.
       */
      public abstract DirectoryStream<Path> newDirectoryStream(Path dir,
           DirectoryStream.Filter<? super Path> filter) throws IOException;
  
      /**
       * Creates a new directory. This method works in exactly the manner
       * specified by the {@link Files#createDirectory} method.
       *
       * @param   dir
       *          the directory to create
       * @param   attrs
       *          an optional list of file attributes to set atomically when
       *          creating the directory
       *
       * @throws  UnsupportedOperationException
       *          if the array contains an attribute that cannot be set atomically
       *          when creating the directory
       * @throws  FileAlreadyExistsException
       *          if a directory could not otherwise be created because a file of
       *          that name already exists <i>(optional specific exception)</i>
       * @throws  IOException
       *          if an I/O error occurs or the parent directory does not exist
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkWrite(String) checkWrite}
       *          method is invoked to check write access to the new directory.
       */
      public abstract void createDirectory(Path dir, FileAttribute<?>... attrs)
          throws IOException;
  
      /**
       * Creates a symbolic link to a target. This method works in exactly the
       * manner specified by the {@link Files#createSymbolicLink} method.
       *
       * <p> The default implementation of this method throws {@code
       * UnsupportedOperationException}.
       *
       * @param   link
       *          the path of the symbolic link to create
       * @param   target
       *          the target of the symbolic link
       * @param   attrs
       *          the array of attributes to set atomically when creating the
       *          symbolic link
       *
       * @throws  UnsupportedOperationException
       *          if the implementation does not support symbolic links or the
       *          array contains an attribute that cannot be set atomically when
       *          creating the symbolic link
       * @throws  FileAlreadyExistsException
       *          if a file with the name already exists <i>(optional specific
       *          exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager
       *          is installed, it denies {@link LinkPermission}<tt>("symbolic")</tt>
       *          or its {@link SecurityManager#checkWrite(String) checkWrite}
       *          method denies write access to the path of the symbolic link.
       */
      public void createSymbolicLink(Path link, Path target, FileAttribute<?>... attrs)
          throws IOException
      {
          throw new UnsupportedOperationException();
      }
  
      /**
       * Creates a new link (directory entry) for an existing file. This method
       * works in exactly the manner specified by the {@link Files#createLink}
       * method.
       *
       * <p> The default implementation of this method throws {@code
       * UnsupportedOperationException}.
       *
       * @param   link
       *          the link (directory entry) to create
       * @param   existing
       *          a path to an existing file
       *
       * @throws  UnsupportedOperationException
       *          if the implementation does not support adding an existing file
       *          to a directory
       * @throws  FileAlreadyExistsException
       *          if the entry could not otherwise be created because a file of
       *          that name already exists <i>(optional specific exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager
       *          is installed, it denies {@link LinkPermission}<tt>("hard")</tt>
       *          or its {@link SecurityManager#checkWrite(String) checkWrite}
       *          method denies write access to either the  link or the
       *          existing file.
       */
      public void createLink(Path link, Path existing) throws IOException {
          throw new UnsupportedOperationException();
      }
  
      /**
       * Deletes a file. This method works in exactly the  manner specified by the
       * {@link Files#delete} method.
       *
       * @param   path
       *          the path to the file to delete
       *
       * @throws  NoSuchFileException
       *          if the file does not exist <i>(optional specific exception)</i>
       * @throws  DirectoryNotEmptyException
       *          if the file is a directory and could not otherwise be deleted
       *          because the directory is not empty <i>(optional specific
       *          exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkDelete(String)} method
       *          is invoked to check delete access to the file
       */
      public abstract void delete(Path path) throws IOException;
  
      /**
       * Deletes a file if it exists. This method works in exactly the manner
       * specified by the {@link Files#deleteIfExists} method.
       *
       * <p> The default implementation of this method simply invokes {@link
       * #delete} ignoring the {@code NoSuchFileException} when the file does not
       * exist. It may be overridden where appropriate.
       *
       * @param   path
       *          the path to the file to delete
       *
       * @return  {@code true} if the file was deleted by this method; {@code
       *          false} if the file could not be deleted because it did not
       *          exist
       *
       * @throws  DirectoryNotEmptyException
       *          if the file is a directory and could not otherwise be deleted
       *          because the directory is not empty <i>(optional specific
       *          exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkDelete(String)} method
       *          is invoked to check delete access to the file
       */
      public boolean deleteIfExists(Path path) throws IOException {
          try {
              delete(path);
              return true;
          } catch (NoSuchFileException ignore) {
              return false;
          }
      }
  
      /**
       * Reads the target of a symbolic link. This method works in exactly the
       * manner specified by the {@link Files#readSymbolicLink} method.
       *
       * <p> The default implementation of this method throws {@code
       * UnsupportedOperationException}.
       *
       * @param   link
       *          the path to the symbolic link
       *
       * @return  The target of the symbolic link
       *
       * @throws  UnsupportedOperationException
       *          if the implementation does not support symbolic links
       * @throws  NotLinkException
       *          if the target could otherwise not be read because the file
       *          is not a symbolic link <i>(optional specific exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager
       *          is installed, it checks that {@code FilePermission} has been
       *          granted with the "{@code readlink}" action to read the link.
       */
      public Path readSymbolicLink(Path link) throws IOException {
          throw new UnsupportedOperationException();
      }
  
      /**
       * Copy a file to a target file. This method works in exactly the manner
       * specified by the {@link Files#copy(Path,Path,CopyOption[])} method
       * except that both the source and target paths must be associated with
       * this provider.
       *
       * @param   source
       *          the path to the file to copy
       * @param   target
       *          the path to the target file
       * @param   options
       *          options specifying how the copy should be done
       *
       * @throws  UnsupportedOperationException
       *          if the array contains a copy option that is not supported
       * @throws  FileAlreadyExistsException
       *          if the target file exists but cannot be replaced because the
       *          {@code REPLACE_EXISTING} option is not specified <i>(optional
       *          specific exception)</i>
       * @throws  DirectoryNotEmptyException
       *          the {@code REPLACE_EXISTING} option is specified but the file
       *          cannot be replaced because it is a non-empty directory
       *          <i>(optional specific exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to the source file, the
       *          {@link SecurityManager#checkWrite(String) checkWrite} is invoked
       *          to check write access to the target file. If a symbolic link is
       *          copied the security manager is invoked to check {@link
       *          LinkPermission}{@code ("symbolic")}.
       */
      public abstract void copy(Path source, Path target, CopyOption... options)
          throws IOException;
  
      /**
       * Move or rename a file to a target file. This method works in exactly the
       * manner specified by the {@link Files#move} method except that both the
       * source and target paths must be associated with this provider.
       *
       * @param   source
       *          the path to the file to move
       * @param   target
       *          the path to the target file
       * @param   options
       *          options specifying how the move should be done
       *
       * @throws  UnsupportedOperationException
       *          if the array contains a copy option that is not supported
       * @throws  FileAlreadyExistsException
       *          if the target file exists but cannot be replaced because the
       *          {@code REPLACE_EXISTING} option is not specified <i>(optional
       *          specific exception)</i>
       * @throws  DirectoryNotEmptyException
       *          the {@code REPLACE_EXISTING} option is specified but the file
       *          cannot be replaced because it is a non-empty directory
       *          <i>(optional specific exception)</i>
       * @throws  AtomicMoveNotSupportedException
       *          if the options array contains the {@code ATOMIC_MOVE} option but
       *          the file cannot be moved as an atomic file system operation.
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkWrite(String) checkWrite}
       *          method is invoked to check write access to both the source and
       *          target file.
       */
      public abstract void move(Path source, Path target, CopyOption... options)
          throws IOException;
  
      /**
       * Tests if two paths locate the same file. This method works in exactly the
       * manner specified by the {@link Files#isSameFile} method.
       *
       * @param   path
       *          one path to the file
       * @param   path2
       *          the other path
       *
       * @return  {@code true} if, and only if, the two paths locate the same file
       *
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to both files.
       */
      public abstract boolean isSameFile(Path path, Path path2)
          throws IOException;
  
      /**
       * Tells whether or not a file is considered <em>hidden</em>. This method
       * works in exactly the manner specified by the {@link Files#isHidden}
       * method.
       *
       * <p> This method is invoked by the {@link Files#isHidden isHidden} method.
       *
       * @param   path
       *          the path to the file to test
       *
       * @return  {@code true} if the file is considered hidden
       *
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to the file.
       */
      public abstract boolean isHidden(Path path) throws IOException;
  
      /**
       * Returns the {@link FileStore} representing the file store where a file
       * is located. This method works in exactly the manner specified by the
       * {@link Files#getFileStore} method.
       *
       * @param   path
       *          the path to the file
       *
       * @return  the file store where the file is stored
       *
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to the file, and in
       *          addition it checks {@link RuntimePermission}<tt>
       *          ("getFileStoreAttributes")</tt>
       */
      public abstract FileStore getFileStore(Path path) throws IOException;
  
      /**
       * Checks the existence, and optionally the accessibility, of a file.
       *
       * <p> This method may be used by the {@link Files#isReadable isReadable},
       * {@link Files#isWritable isWritable} and {@link Files#isExecutable
       * isExecutable} methods to check the accessibility of a file.
       *
       * <p> This method checks the existence of a file and that this Java virtual
       * machine has appropriate privileges that would allow it access the file
       * according to all of access modes specified in the {@code modes} parameter
       * as follows:
       *
       * <table border=1 cellpadding=5 summary="">
       * <tr> <th>Value</th> <th>Description</th> </tr>
       * <tr>
       *   <td> {@link AccessMode#READ READ} </td>
       *   <td> Checks that the file exists and that the Java virtual machine has
       *     permission to read the file. </td>
       * </tr>
       * <tr>
       *   <td> {@link AccessMode#WRITE WRITE} </td>
       *   <td> Checks that the file exists and that the Java virtual machine has
       *     permission to write to the file, </td>
       * </tr>
       * <tr>
       *   <td> {@link AccessMode#EXECUTE EXECUTE} </td>
       *   <td> Checks that the file exists and that the Java virtual machine has
       *     permission to {@link Runtime#exec execute} the file. The semantics
       *     may differ when checking access to a directory. For example, on UNIX
       *     systems, checking for {@code EXECUTE} access checks that the Java
       *     virtual machine has permission to search the directory in order to
       *     access file or subdirectories. </td>
       * </tr>
       * </table>
       *
       * <p> If the {@code modes} parameter is of length zero, then the existence
       * of the file is checked.
       *
       * <p> This method follows symbolic links if the file referenced by this
       * object is a symbolic link. Depending on the implementation, this method
       * may require to read file permissions, access control lists, or other
       * file attributes in order to check the effective access to the file. To
       * determine the effective access to a file may require access to several
       * attributes and so in some implementations this method may not be atomic
       * with respect to other file system operations.
       *
       * @param   path
       *          the path to the file to check
       * @param   modes
       *          The access modes to check; may have zero elements
       *
       * @throws  UnsupportedOperationException
       *          an implementation is required to support checking for
       *          {@code READ}, {@code WRITE}, and {@code EXECUTE} access. This
       *          exception is specified to allow for the {@code Access} enum to
       *          be extended in future releases.
       * @throws  NoSuchFileException
       *          if a file does not exist <i>(optional specific exception)</i>
       * @throws  AccessDeniedException
       *          the requested access would be denied or the access cannot be
       *          determined because the Java virtual machine has insufficient
       *          privileges or other reasons. <i>(optional specific exception)</i>
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, the {@link SecurityManager#checkRead(String) checkRead}
       *          is invoked when checking read access to the file or only the
       *          existence of the file, the {@link SecurityManager#checkWrite(String)
       *          checkWrite} is invoked when checking write access to the file,
       *          and {@link SecurityManager#checkExec(String) checkExec} is invoked
       *          when checking execute access.
       */
      public abstract void checkAccess(Path path, AccessMode... modes)
          throws IOException;
  
      /**
       * Returns a file attribute view of a given type. This method works in
       * exactly the manner specified by the {@link Files#getFileAttributeView}
       * method.
       *
       * @param   <V>
       *          The {@code FileAttributeView} type
       * @param   path
       *          the path to the file
       * @param   type
       *          the {@code Class} object corresponding to the file attribute view
       * @param   options
       *          options indicating how symbolic links are handled
       *
       * @return  a file attribute view of the specified type, or {@code null} if
       *          the attribute view type is not available
       */
      public abstract <V extends FileAttributeView> V
          getFileAttributeView(Path path, Class<V> type, LinkOption... options);
  
      /**
       * Reads a file's attributes as a bulk operation. This method works in
       * exactly the manner specified by the {@link
       * Files#readAttributes(Path,Class,LinkOption[])} method.
       *
       * @param   <A>
       *          The {@code BasicFileAttributes} type
       * @param   path
       *          the path to the file
       * @param   type
       *          the {@code Class} of the file attributes required
       *          to read
       * @param   options
       *          options indicating how symbolic links are handled
       *
       * @return  the file attributes
       *
       * @throws  UnsupportedOperationException
       *          if an attributes of the given type are not supported
       * @throws  IOException
       *          if an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, a security manager is
       *          installed, its {@link SecurityManager#checkRead(String) checkRead}
       *          method is invoked to check read access to the file
       */
      public abstract <A extends BasicFileAttributes> A
          readAttributes(Path path, Class<A> type, LinkOption... options) throws IOException;
  
      /**
       * Reads a set of file attributes as a bulk operation. This method works in
       * exactly the manner specified by the {@link
       * Files#readAttributes(Path,String,LinkOption[])} method.
       *
       * @param   path
       *          the path to the file
       * @param   attributes
       *          the attributes to read
       * @param   options
       *          options indicating how symbolic links are handled
       *
       * @return  a map of the attributes returned; may be empty. The map's keys
       *          are the attribute names, its values are the attribute values
       *
       * @throws  UnsupportedOperationException
       *          if the attribute view is not available
       * @throws  IllegalArgumentException
       *          if no attributes are specified or an unrecognized attributes is
       *          specified
       * @throws  IOException
       *          If an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, its {@link SecurityManager#checkRead(String) checkRead}
       *          method denies read access to the file. If this method is invoked
       *          to read security sensitive attributes then the security manager
       *          may be invoke to check for additional permissions.
       */
      public abstract Map<String,Object> readAttributes(Path path, String attributes,
                                                        LinkOption... options)
          throws IOException;
  
      /**
       * Sets the value of a file attribute. This method works in exactly the
       * manner specified by the {@link Files#setAttribute} method.
       *
       * @param   path
       *          the path to the file
       * @param   attribute
       *          the attribute to set
       * @param   value
       *          the attribute value
       * @param   options
       *          options indicating how symbolic links are handled
       *
       * @throws  UnsupportedOperationException
       *          if the attribute view is not available
       * @throws  IllegalArgumentException
       *          if the attribute name is not specified, or is not recognized, or
       *          the attribute value is of the correct type but has an
       *          inappropriate value
       * @throws  ClassCastException
       *          If the attribute value is not of the expected type or is a
       *          collection containing elements that are not of the expected
       *          type
       * @throws  IOException
       *          If an I/O error occurs
       * @throws  SecurityException
       *          In the case of the default provider, and a security manager is
       *          installed, its {@link SecurityManager#checkWrite(String) checkWrite}
       *          method denies write access to the file. If this method is invoked
       *          to set security sensitive attributes then the security manager
       *          may be invoked to check for additional permissions.
       */
      public abstract void setAttribute(Path path, String attribute,
                                        Object value, LinkOption... options)
          throws IOException;
  }
  