@ParametersAreNonnullByDefault

Package com.google.cloud.storage.contrib.nio

Java 7 nio FileSystem client library for Google Cloud Storage.

See: Description

Interface Summary

Interface	Description
CloudStorageFileAttributes	Interface for attributes on a Cloud Storage file or pseudo-directory.
CloudStorageOption	Master interface for file operation option classes related to Google Cloud Storage.
CloudStorageOption.Copy	Interface for Google Cloud Storage options that can be specified when copying files.
CloudStorageOption.Open	Interface for Google Cloud Storage options that can be specified when opening files.
CloudStorageOption.OpenCopy	Interface for Google Cloud Storage options that can be specified when opening or copying files.

Class Summary

Class	Description
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.
CloudStorageFileSystemProvider	Google Cloud Storage FileSystemProvider implementation.
CloudStorageOptions	Helper class for specifying options when opening and copying Cloud Storage files.
CloudStoragePath	Google Cloud Storage Path.
CloudStorageRetryHandler	Simple counter class to keep track of retry and reopen attempts when StorageExceptions are encountered.
SeekableByteChannelPrefetcher	SeekableByteChannelPrefetcher wraps an existing SeekableByteChannel to add prefetching.
SeekableByteChannelPrefetcher.Statistics

Exception Summary

Exception	Description
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.

Package com.google.cloud.storage.contrib.nio Description

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 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.