.readme-partials.yaml

custom_content: |
  #### About Google Cloud Storage

  [Google Cloud Storage](https://cloud.google.com/storage/) is a durable and highly available
  object storage service. Google Cloud Storage is almost infinitely scalable
  and guarantees consistency: when a write succeeds, the latest copy of the
  object will be returned to any GET, globally.

  See the [Google Cloud Storage docs](https://cloud.google.com/storage/docs/signup?hl=en) for more details
  on how to activate Cloud Storage for your project.

  #### About Java NIO Providers

  Java NIO Providers is an extension mechanism that is part of Java and allows
  third parties to extend Java's [normal File API](https://docs.oracle.com/javase/7/docs/api/java/nio/file/Files.html) to support
  additional filesystems.

  #### Accessing files

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

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

  If you know the paths will point to Google Cloud Storage, you can also use the
  direct formulation:

  ```java
  try (CloudStorageFileSystem fs = CloudStorageFileSystem.forBucket("bucket")) {
    Path path = fs.getPath("lolcat.csv");
    List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
  }
  ```

  Once you have a `Path` you can use it as you would a normal file. For example
  you can use `InputStream` and `OutputStream` for streaming:

  ```java
  try (InputStream input = Files.openInputStream(path)) {
    // ...
  }
  ```

  You can also set various attributes using CloudStorageOptions static helpers:

  ```java
  Files.write(csvPath, csvLines, StandardCharsets.UTF_8,
      withMimeType(MediaType.CSV_UTF8),
      withoutCaching());
  ```

  #### Limitations

  This library is usable, but not yet complete. The following features are not
  yet implemented:
   * Resuming upload or download
   * Generations
   * File attributes
   * (more - list is not exhaustive)

  Some features are not on the roadmap: this library would be a poor choice to
  mirror a local filesystem onto the cloud because Google Cloud Storage has a
  different set of features from your local disk. This library, by design,
  does not mask those differences. Rather, it aims to expose the common
  subset via a familiar interface.

  **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. Paths without the trailing
  slash will result in an I/O operation to check a file is present in that "directory".
  This allows you to do path manipulation in the same manner as you would with the normal UNIX file
  system implementation. Using this feature with buckets or "directory" paths that do not exist
  is not recommended, as at the time I/O is performed the failure may not be handled gracefully.
  You can disable this feature with `CloudStorageConfiguration.usePseudoDirectories()`.

  #### Complete source code

  There are examples in [google-cloud-nio-examples](google-cloud-nio-examples/src/main/java/com/google/cloud/examples/nio/)
  for your perusal.