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://access­Key@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
File­Service()	Creates a new provider of file systems for Amazon S3.

Method Summary

Modifier and Type	Method	Description
void	check­Access(Path path, Access­Mode... modes)	Checks the existence, and optionally the accessibility, of a file.
void	copy(Path source, Path target, Copy­Option... options)	Copies a file.
void	create­Directory(Path directory, File­Attribute<?>... attributes)	Creates a new pseudo-directory.
void	delete(Path path)	Deletes a file.
<V extends File­Attribute­View> V	get­File­Attribute­View(Path path, Class<V> type, Link­Option... options)	Returns a read-only or updatable view of a set of file attributes.
File­Store	get­File­Store(Path path)	Returns the store where a file is located.
File­System	get­File­System(URI uri)	Returns a reference to a file system that was created by the new­File­System(URI, Map) method.
Path	get­Path(URI uri)	Return a Path object by converting the given URI.
String	get­Scheme()	Returns the URI scheme that identifies this provider, which is "S3".
boolean	is­Hidden(Path path)	Tells whether a file is considered hidden.
boolean	is­Same­File(Path path1, Path path2)	Tests if two paths locate the same file.
void	move(Path source, Path target, Copy­Option... options)	Copies a file.
Seekable­Byte­Channel	new­Byte­Channel(Path path, Set<? extends Open­Option> options, File­Attribute<?>... attributes)	Returns a seekable byte channel to access a file.
Directory­Stream<Path>	new­Directory­Stream(Path directory, Directory­Stream.Filter<? super Path> filter)	Opens a directory and returns a Directory­Stream to iterate over its entries.
File­System	new­File­System(URI uri, Map<String,?> properties)	Initializes and returns a new file system identified by a URI.
Input­Stream	new­Input­Stream(Path path, Open­Option... options)	Opens an input stream to read from the path.
<A extends Basic­File­Attributes> A	read­Attributes(Path path, Class<A> type, Link­Option... options)	Reads a file's attributes as a bulk operation.
Map<String,Object>	read­Attributes(Path path, String attributes, Link­Option... options)	Reads a set of file attributes as a bulk operation.
void	set­Attribute(Path path, String attribute, Object value, Link­Option... options)

Methods inherited from class FileSystemProvider

create­Link, create­Symbolic­Link, delete­If­Exists, exists, installed­Providers, new­Asynchronous­File­Channel, new­File­Channel, new­File­System, new­Output­Stream, read­Attributes­If­Exists, read­Symbolic­Link

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, 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/config files.

See Also:

• new­File­System(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/config files.

See Also:

• new­File­System(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:

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/key

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 to the "aws.secretAccessKey" key.

Recognized properties

The following properties are accepted:

• "aws.secretAccessKey" with String value.
• "aws.region" with Region value.

Specified by:

new­File­System in class File­System­Provider

Parameters:

uri - a URI of the form "s3://access­Key@bucket/key".

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.

Specified by:

get­File­System in class File­System­Provider

Parameters:

uri - a URI of the form "s3://access­Key@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.

Specified by:

get­Path in class File­System­Provider

Parameters:

uri - a URI of the form "s3://access­Key@bucket/key".

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:

• Files.read­Attributes(Path, String, Link­Option...)

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