Package com.google.cloud.storage.contrib.nio (0.125.0)

Java 7 nio FileSystem client library for Google Cloud Storage.

This client library allows you to easily interact with Google Cloud Storage, using Java's standard file system API, introduced in Java 7.

How It Works

The simplest way to get started is with Paths and Files:


 Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
 List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);

For the complete source code see ReadAllLines.java.

If you want to configure the bucket per-environment, it might make more sense to use the FileSystem API:


 FileSystem fs = FileSystems.getFileSystem(URI.create("gs://bucket"));
 byte[] data = "hello world".getBytes(StandardCharsets.UTF_8);
 Path path = fs.getPath("/object");
 Files.write(path, data);
 List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);

For the complete source code see GetFileSystem.java.

You can also use InputStream and OutputStream for streaming:

Path path = Paths.get(URI.create("gs://bucket/lolcat.csv")); try (InputStream input = Files.newInputStream(path)) { // use input stream }

For the complete source code see CreateInputStream.java.

You can set various attributes using CloudStorageOptions static helpers:

Path path = Paths.get(URI.create("gs://bucket/lolcat.csv")); Files.write(path, csvLines, StandardCharsets.UTF_8, withMimeType("text/csv; charset=UTF-8"), withoutCaching());

For the complete source code see WriteFileWithAttributes.java.

NOTE: Cloud Storage uses a flat namespace and therefore doesn't support real directories. So this library supports what's known as "pseudo-directories". Any path that includes a trailing slash, will be considered a directory. It will always be assumed to exist, without performing any I/O. This allows you to do path manipulation in the same manner as you would with the normal UNIX file system implementation. You can disable this feature with com.google.cloud.storage.contrib.nio.CloudStorageConfiguration#usePseudoDirectories().

Non-SPI Interface

If you don't want to rely on Java SPI, which requires a META-INF file in your jar generated by Google Auto, you can instantiate this file system directly as follows:

CloudStorageFileSystem fs = CloudStorageFileSystem.forBucket("bucket"); byte[] data = "hello world".getBytes(StandardCharsets.UTF_8); Path path = fs.getPath("/object"); Files.write(path, data); data = Files.readAllBytes(path);

For the complete source code see CreateCloudStorageFileSystem.java.

Classes

CloudStorageConfiguration

Configuration for CloudStorageFileSystem instances.

CloudStorageConfiguration.Builder

Builder for CloudStorageConfiguration.

CloudStorageFileAttributeView

Metadata view for a Google Cloud Storage object.

CloudStorageFileSystem

Google Cloud Storage FileSystem implementation. See Also: Concepts and Terminology, Bucket and Object Naming Guidelines

CloudStorageFileSystemProvider

Google Cloud Storage FileSystemProvider implementation.

Note: This class should never be used directly. This class is instantiated by the service loader and called through a standardized API, e.g. java.nio.file.Files. However the javadocs in this class serve as useful documentation for the behavior of the Google Cloud Storage NIO library.

CloudStorageOptions

Helper class for specifying options when opening and copying Cloud Storage files.

CloudStoragePath

A Google Cloud Storage specific implementation of the java.nio.file.Path interface. An instance of this class locates an object or a "pseudo-directory" in GCS. This implementation allows one to use Java's standard file system API to deal with remote objects as if they are local files.

Example of using java.nio.file.Files to read all lines from a remote object:


 Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
 List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);

CloudStorageRetryHandler

Simple counter class to keep track of retry and reopen attempts when StorageExceptions are encountered. Handles sleeping between retry/reopen attempts, as well as throwing an exception when all retries/reopens are exhausted.

SeekableByteChannelPrefetcher

SeekableByteChannelPrefetcher wraps an existing SeekableByteChannel to add prefetching. The prefetching is done on a different thread, so you can write simple code that repeatedly calls read() to get data, processes it, and then calls read again -- and yet this simple code overlaps computation and communication for you. (Of course this is only worthwhile if the underlying SeekableByteChannel doesn't already implement prefetching).

SeekableByteChannelPrefetcher.Statistics

Exceptions

CloudStorageObjectImmutableException

Exception reminding user that Cloud Storage objects can't be mutated.

CloudStoragePseudoDirectoryException

Exception thrown when erroneously trying to operate on a path with a trailing slash.