Class FileService

Object
FileSystemProvider
FileService
public class FileService extends FileSystemProvider
A provider of file system services as wrappers around Amazon Simple Storage Service (AWS S3). This provider accepts URIs of the following forms:
  • S3://bucket/file
  • S3://host:port/bucket/file
  • S3://access­Key@bucket/file (password not allowed)
  • S3://access­Key@host:port/bucket/key (password not allowed)
"Files" are S3 keys interpreted as paths with components separated by the '/' separator. The password and the region can be specified at file system initialization time. The endpoint (e.g. "s3​.eu-central-1.amazonaws​.com") shall not be specified in the URI. In particular the region ("eu-central-1" in the above example) can depend on the server location instead of the data to access, and can be a global configuration for the server.
Since:
1.2

  • Field Details

    • AWS_SECRET_ACCESS_KEY

      public static final String AWS_SECRET_ACCESS_KEY
      The property for the secret access key (password). Values shall be instances of String. If not specified, the AWS SDK default mechanism searches for the first of the following:
      • AWS_SECRET_ACCESS_KEY environment variable.
      • ~/.aws/credentials and ~/.aws/config files.
      See Also:

    • AWS_REGION

      public static final String AWS_REGION
      The property for the region. Values shall should be instances of Region or strings convertible to region. If not specified, the AWS SDK default mechanism searches for the first of the following:
      • AWS_REGION environment variable.
      • ~/.aws/credentials and ~/.aws/config files.
      See Also:

    • HOST_URL

      public static final String HOST_URL
      The property for the host (mandatory if not using AWS S3). Values shall be instances of String.
      Since:
      1.7
      See Also:

    • PORT

      public static final String PORT
      The property for the port (mandatory if not using AWS S3). Values shall be instances of Integer.
      Since:
      1.7
      See Also:

    • IS_HTTPS

      public static final String IS_HTTPS
      The property for the protocol (optional). Values shall be instances of Boolean. The default value is true (HTTPS).
      Since:
      1.7
      See Also:

    • SEPARATOR

      public static final String SEPARATOR
      The property for the name-separator characters. The default value is "/" for simulating Unix paths. The separator must contain at least one character. They usually have only one character, but longer separators are accepted. The separator can contain any characters which are valid in a S3 object name.
      See Also:

  • Constructor Details

    • FileService

      public FileService()
      Creates a new provider of file systems for Amazon S3.

  • Method Details

    • getScheme

      public String getScheme()
      Returns the URI scheme that identifies this provider, which is "S3".
      Specified by:
      get­Scheme in class File­System­Provider
      Returns:
      the "S3" URI scheme.

    • newFileSystem

      public FileSystem newFileSystem(URI uri, Map<String,?> properties) throws IOException
      Initializes and returns a new file system identified by a URI. The given URI shall have the following pattern: 
      S3://accessKey@bucket/file
      In current version all path components after access­Key are ignored. A future version may allow finer grain control.

      Authentication

      The access key is a kind of login (not a password). The password (also called "secret access key") shall not be specified in the URI; syntax like access­Key:password will not be parsed by this package. Instead the password can be specified in the given map as a String value associated with the "aws.secretAccessKey" key.

      Recognized properties

      The following properties are accepted:

      The URI can be of the form "s3://access­Key@bucket/file" (AWS S3) or "s3://access­Key@host:port/bucket/file" (self-hosted S3). In the latter case, the host and the port are mandatory.

      Specified by:
      new­File­System in class File­System­Provider
      Parameters:
      uri - an URI of the form "s3://access­Key@[host:port/]bucket/file".
      properties - properties to configure the file system, or null if none.
      Returns:
      the new file system.
      Throws:
      Illegal­Argument­Exception - if the URI or the map contains invalid values.
      IOException - if an I/O error occurs while creating the file system.
      File­System­Already­Exists­Exception - if a file system has already been created for the given URI and has not yet been closed.

    • getFileSystem

      public FileSystem getFileSystem(URI uri)
      Returns a reference to a file system that was created by the new­File­System(URI, Map) method. If the file system has not been created or has been closed, then this method throws File­System­Not­Found­Exception.

      The URI scheme should be the value returned by get­Scheme(), which is usually "S3". The AWS S3 service may be implemented on top of HTTP or HTTPS protocol. This method detects automatically which protocol was specified in the call to new­File­System(URI, Map). If the two protocols have been used for the same host, then this method uses the port number for disambiguation: port 80 is mapped to HTTP and port 443 is mapped to HTTPS.

      Specified by:
      get­File­System in class File­System­Provider
      Parameters:
      uri - an URI of the form "s3://access­Key@bucket/file" or "s3://access­Key@host:port/bucket/key".
      Returns:
      the file system previously created by new­File­System(URI, Map).
      Throws:
      Illegal­Argument­Exception - if the URI is not supported by this provider.
      File­System­Not­Found­Exception - if the file system does not exist or has been closed.

    • getPath

      public Path getPath(URI uri)
      Return a Path object by converting the given URI. The resulting Path is associated with a File­System that already exists or is constructed automatically.

      The URI can be of the form "s3://access­Key@bucket/file" (AWS S3) or "s3://access­Key@host:port/bucket/file" (self-hosted S3). In the latter case, the host and the port are mandatory.

      Specified by:
      get­Path in class File­System­Provider
      Parameters:
      uri - an URI of the form "s3://access­Key@[host:port/]bucket/file".
      Returns:
      the resulting Path.
      Throws:
      Illegal­Argument­Exception - if the URI is not supported by this provider.
      File­System­Not­Found­Exception - if the file system does not exist and cannot be created automatically.

    • isSameFile

      public boolean isSameFile(Path path1, Path path2) throws IOException
      Tests if two paths locate the same file.
      Specified by:
      is­Same­File in class File­System­Provider
      Parameters:
      path1 - one path to the file.
      path2 - the other path.
      Returns:
      true if the two paths locate the same file.
      Throws:
      IOException - if an I/O error occurs.

    • isHidden

      public boolean isHidden(Path path) throws IOException
      Tells whether a file is considered hidden. Current implementation always return false.
      Specified by:
      is­Hidden in class File­System­Provider
      Parameters:
      path - the path to the file to test.
      Returns:
      true if the file is considered hidden.
      Throws:
      IOException - if an I/O error occurs.

    • getFileStore

      public FileStore getFileStore(Path path) throws IOException
      Returns the store where a file is located.
      Specified by:
      get­File­Store in class File­System­Provider
      Parameters:
      path - the path to the file.
      Returns:
      the store where the file is stored.
      Throws:
      IOException - if an I/O error occurs.

    • newDirectoryStream

      public DirectoryStream<Path> newDirectoryStream(Path directory, DirectoryStream.Filter<? super Path> filter) throws IOException
      Opens a directory and returns a Directory­Stream to iterate over its entries. S3 does not formally has directories. Instead directories are simulated by handling the '/' character in a special way.
      Specified by:
      new­Directory­Stream in class File­System­Provider
      Parameters:
      directory - the path to the directory.
      filter - the directory stream filter.
      Returns:
      a new and open stream on directory entries.
      Throws:
      Not­Directory­Exception - if the file is not a directory.
      IOException - if an I/O error occurs.

    • createDirectory

      public void createDirectory(Path directory, FileAttribute<?>... attributes) throws IOException
      Creates a new pseudo-directory. S3 does not formally has directories, so the current operation does nothing. Instead a pseudo-directory will appear after the first file or sub-directory is added in the directory.
      Specified by:
      create­Directory in class File­System­Provider
      Parameters:
      directory - the directory to create.
      attributes - an optional list of file attributes to set when creating the directory.
      Throws:
      IOException - if an I/O error occurs or the parent directory does not exist.

    • copy

      public void copy(Path source, Path target, CopyOption... options) throws IOException
      Copies a file. This method is not yet supported.
      Specified by:
      copy in class File­System­Provider
      Parameters:
      source - the path to the file to copy.
      target - the path to the target file.
      options - options specifying how the copy should be done
      Throws:
      IOException - if an I/O error occurs.

    • move

      public void move(Path source, Path target, CopyOption... options) throws IOException
      Copies a file. This method is not yet supported.
      Specified by:
      move in class File­System­Provider
      Parameters:
      source - the path to the file to move.
      target - the path to the target file.
      options - options specifying how the move should be done
      Throws:
      IOException - if an I/O error occurs.

    • delete

      public void delete(Path path) throws IOException
      Deletes a file. This method is not yet supported.
      Specified by:
      delete in class File­System­Provider
      Parameters:
      path - the path to the file to delete.
      Throws:
      IOException - if an I/O error occurs.

    • newInputStream

      public InputStream newInputStream(Path path, OpenOption... options) throws IOException
      Opens an input stream to read from the path. It is important to close the input stream after usage for avoiding exhaustion of connection pool.
      Overrides:
      new­Input­Stream in class File­System­Provider
      Parameters:
      path - the path to the file to open.
      options - options specifying how the file is opened.
      Returns:
      a new input stream for the specified path.
      Throws:
      Unsupported­Operation­Exception - if an unsupported option is specified.
      IOException - if an I/O error occurs.

    • newByteChannel

      public SeekableByteChannel newByteChannel(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attributes) throws IOException
      Returns a seekable byte channel to access a file.
      Specified by:
      new­Byte­Channel in class File­System­Provider
      Parameters:
      path - the path to the file to open.
      options - options specifying how the file is opened.
      attributes - an optional list of file attributes to set when creating the file.
      Returns:
      a new seekable byte channel for the specified path.
      Throws:
      Unsupported­Operation­Exception - if an unsupported open option is specified.
      IOException - if an I/O error occurs.

    • checkAccess

      public void checkAccess(Path path, AccessMode... modes) throws IOException
      Checks the existence, and optionally the accessibility, of a file.
      Specified by:
      check­Access in class File­System­Provider
      Parameters:
      path - the path to the file to check.
      modes - the access modes to check; may have zero elements.
      Throws:
      No­Such­File­Exception - if a file does not exist (optional specific exception).
      Access­Denied­Exception - the requested access would be denied.
      IOException - if an I/O error occurs

    • getFileAttributeView

      public <V extends FileAttributeView> V getFileAttributeView(Path path, Class<V> type, LinkOption... options)
      Returns a read-only or updatable view of a set of file attributes.
      Specified by:
      get­File­Attribute­View in class File­System­Provider
      Type Parameters:
      V - the view type.
      Parameters:
      path - the path to the file.
      type - the class of the file attribute view.
      options - options indicating how symbolic links are handled.
      Returns:
      a file attribute view of the specified type, or null if not available.

    • readAttributes

      public <A extends BasicFileAttributes> A readAttributes(Path path, Class<A> type, LinkOption... options) throws IOException
      Reads a file's attributes as a bulk operation.
      Specified by:
      read­Attributes in class File­System­Provider
      Type Parameters:
      A - the Basic­File­Attributes type.
      Parameters:
      path - the path to the file.
      type - the class of the file attributes to read.
      options - options indicating how symbolic links are handled.
      Returns:
      the file attributes.
      Throws:
      Unsupported­Operation­Exception - if attributes of the given type are not supported.
      IOException - if an I/O error occurs.

    • readAttributes

      public Map<String,Object> readAttributes(Path path, String attributes, LinkOption... options) throws IOException
      Reads a set of file attributes as a bulk operation. See NIO javadoc for details about the attributes argument.
      Specified by:
      read­Attributes in class File­System­Provider
      Parameters:
      path - the path to the file.
      attributes - the attributes to read.
      options - options indicating how symbolic links are handled
      Returns:
      a map of the attributes returned; may be empty. The map's keys are the attribute names, its values are the attribute values.
      Throws:
      IOException - if an I/O error occurs.
      See Also:

    • setAttribute

      public void setAttribute(Path path, String attribute, Object value, LinkOption... options) throws IOException
      Specified by:
      set­Attribute in class File­System­Provider
      Throws:
      IOException