Module org.apache.sis.cloud.aws
Package org.apache.sis.cloud.aws.s3

# 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/key`
- `S3://accessKey@bucket/key` (password not allowed)

Keys can be 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 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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `AWS_REGION`
  The property for the secret access key (password).
  `static final String`
  `AWS_SECRET_ACCESS_KEY`
  The property for the secret access key (password).
  `static final String`
  `SEPARATOR`
  The property for the name-separator characters.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FileService()`
  Creates a new provider of file systems for Amazon S3.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `checkAccess(Path path, AccessMode... modes)`
  Checks the existence, and optionally the accessibility, of a file.
  `void`
  `copy(Path source, Path target, CopyOption... options)`
  Copies a file.
  `void`
  `createDirectory(Path directory, FileAttribute<?>... attributes)`
  Creates a new pseudo-directory.
  `void`
  `delete(Path path)`
  Deletes a file.
  `<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.
  `FileStore`
  `getFileStore(Path path)`
  Returns the store where a file is located.
  `FileSystem`
  `getFileSystem(URI uri)`
  Returns a reference to a file system that was created by the `newFileSystem(URI, Map)` method.
  `Path`
  `getPath(URI uri)`
  Return a `Path` object by converting the given `URI`.
  `String`
  `getScheme()`
  Returns the URI scheme that identifies this provider, which is `"S3"`.
  `boolean`
  `isHidden(Path path)`
  Tells whether a file is considered hidden.
  `boolean`
  `isSameFile(Path path1, Path path2)`
  Tests if two paths locate the same file.
  `void`
  `move(Path source, Path target, CopyOption... options)`
  Copies a file.
  `SeekableByteChannel`
  `newByteChannel(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attributes)`
  Returns a seekable byte channel to access a file.
  `DirectoryStream<Path>`
  `newDirectoryStream(Path directory, DirectoryStream​.Filter<? super Path> filter)`
  Opens a directory and returns a `DirectoryStream` to iterate over its entries.
  `FileSystem`
  `newFileSystem(URI uri, Map<String,?> properties)`
  Initializes and returns a new file system identified by a URI.
  `InputStream`
  `newInputStream(Path path, OpenOption... options)`
  Opens an input stream to read from the path.
  `<A extends BasicFileAttributes>
  A`
  `readAttributes(Path path, Class<A> type, LinkOption... options)`
  Reads a file's attributes as a bulk operation.
  `Map<String,Object>`
  `readAttributes(Path path, String attributes, LinkOption... options)`
  Reads a set of file attributes as a bulk operation.
  `void`
  `setAttribute(Path path, String attribute, Object value, LinkOption... options)`

  ### Methods inherited from class FileSystemProvider

  `createLink, createSymbolicLink, deleteIfExists, exists, installedProviders, newAsynchronousFileChannel, newFileChannel, newFileSystem, newOutputStream, readAttributesIfExists, readSymbolicLink`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## 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/conﬁg` files.
    See Also:
      - `newFileSystem(URI, Map)`
      - Constant Field Values

  - ### AWS_REGION

    public static final String AWS_REGION
    The property for the secret access key (password). Values shall be instances of `Region`. If not specified, the AWS SDK default mechanism searches for the first of the following:
    - `AWS_REGION` environment variable.
    - `~/.aws/credentials` and `~/.aws/conﬁg` files.
    See Also:
      - `newFileSystem(URI, Map)`
      - Constant Field Values

  - ### 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:
      - Constant Field Values

- ## 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:
      `getScheme` in class `FileSystemProvider`
    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/key

    In current version all path components after `accessKey` 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 `accessKey:password` will not be parsed by this package. Instead the password can be specified in the given map as a `String` value associated to the "aws.secretAccessKey" key.

    #### Recognized properties

    The following properties are accepted:
    - "aws.secretAccessKey" with `String` value.
    - "aws.region" with `Region` value.
    Specified by:
      `newFileSystem` in class `FileSystemProvider`
    Parameters:
      `uri` - a URI of the form `"s3://accessKey@bucket/key"`.
      `properties` - properties to configure the file system, or `null` if none.
    Returns:
      the new file system.
    Throws:
      `IllegalArgumentException` - if the URI or the map contains invalid values.
      `IOException` - if an I/O error occurs while creating the file system.
      `FileSystemAlreadyExistsException` - 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 `newFileSystem(URI, Map)` method. If the file system has not been created or has been closed, then this method throws `FileSystemNotFoundException`.
    Specified by:
      `getFileSystem` in class `FileSystemProvider`
    Parameters:
      `uri` - a URI of the form `"s3://accessKey@bucket/key"`.
    Returns:
      the file system previously created by `newFileSystem(URI, Map)`.
    Throws:
      `IllegalArgumentException` - if the URI is not supported by this provider.
      `FileSystemNotFoundException` - 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 `FileSystem` that already exists or is constructed automatically.
    Specified by:
      `getPath` in class `FileSystemProvider`
    Parameters:
      `uri` - a URI of the form `"s3://accessKey@bucket/key"`.
    Returns:
      the resulting `Path`.
    Throws:
      `IllegalArgumentException` - if the URI is not supported by this provider.
      `FileSystemNotFoundException` - 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:
      `isSameFile` in class `FileSystemProvider`
    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:
      `isHidden` in class `FileSystemProvider`
    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:
      `getFileStore` in class `FileSystemProvider`
    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 `DirectoryStream` 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:
      `newDirectoryStream` in class `FileSystemProvider`
    Parameters:
      `directory` - the path to the directory.
      `filter` - the directory stream filter.
    Returns:
      a new and open stream on directory entries.
    Throws:
      `NotDirectoryException` - 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:
      `createDirectory` in class `FileSystemProvider`
    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 `FileSystemProvider`
    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 `FileSystemProvider`
    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 `FileSystemProvider`
    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:
      `newInputStream` in class `FileSystemProvider`
    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:
      `UnsupportedOperationException` - 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:
      `newByteChannel` in class `FileSystemProvider`
    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:
      `UnsupportedOperationException` - 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:
      `checkAccess` in class `FileSystemProvider`
    Parameters:
      `path` - the path to the file to check.
      `modes` - the access modes to check; may have zero elements.
    Throws:
      `NoSuchFileException` - if a file does not exist (optional specific exception).
      `AccessDeniedException` - 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:
      `getFileAttributeView` in class `FileSystemProvider`
    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:
      `readAttributes` in class `FileSystemProvider`
    Type Parameters:
      `A` - the `BasicFileAttributes` 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:
      `UnsupportedOperationException` - 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:
      `readAttributes` in class `FileSystemProvider`
    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:
      - `Files​.readAttributes(Path, String, LinkOption...)`

  - ### setAttribute

    public void setAttribute(Path path, String attribute, Object value, LinkOption... options) throws IOException
    Specified by:
      `setAttribute` in class `FileSystemProvider`
    Throws:
      `IOException`