com.google.cloud.storage.contrib.nio.package-info Maven / Gradle / Ivy
Show all versions of google-cloud-nio Show documentation
/*
* Copyright 2016 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* 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 {@code Paths} and {@code Files}:
*
* {@code
* Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
* List 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
* {@code FileSystem} API:
*
*
{@code
* 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 lines = Files.readAllLines(path, StandardCharsets.UTF_8);
* }
*
* For the complete source code see
* GetFileSystem.java.
*
*
You can also use {@code InputStream} and {@code 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 {@link
* com.google.cloud.storage.contrib.nio.CloudStorageOptions 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 {@link
* 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.
*/
@javax.annotation.ParametersAreNonnullByDefault
package com.google.cloud.storage.contrib.nio;