Better explain how to use explicit credentials (#4694)

* Better explain how to use explicit credentials

This pull request updates the documentation and adds an example.

* Run auto-formatter

mvn com.coveo:fmt-maven-plugin:format

* Updating Copyright year on UseExplicitCredentials

google-cloud-clients/google-cloud-contrib/google-cloud-nio-examples/README.md

@@ -6,7 +6,8 @@ application that uses Java NIO without the need to recompile.
 
 Note that whenever possible, you instead want to recompile the app and use the normal
 dependency mechanism to add a dependency to google-cloud-nio. You can see examples of
-this in the [google-cloud-examples](../../../google-cloud-examples) project.
+this in the [google-cloud-examples](../../../google-cloud-examples) project,
+[under nio](../../../google-cloud-examples/src/main/java/com/google/cloud/examples/nio).
 
 To run this example:
 

google-cloud-clients/google-cloud-contrib/google-cloud-nio/README.md

@@ -57,7 +57,8 @@ Authentication
 --------------
 
 See the [Authentication](https://github.com/googleapis/google-cloud-java#authentication)
-section in the base directory's README.
+section in the base directory's README. This shows how to construct the `StorageOptions` object,
+which you can then pass to `CloudStorageFileSystem.forBucket`.
 
 About Google Cloud Storage
 --------------------------

google-cloud-clients/google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java

@@ -140,7 +140,12 @@ protected Path computeNext() {
     }
   }
 
-  /** Sets options that are only used by the constructor. */
+  /**
+   * Sets options that are only used by the constructor.
+   *
+   * <p>Instead of calling this, when possible use CloudStorageFileSystem.forBucket and pass
+   * StorageOptions as an argument.
+   */
   @VisibleForTesting
   public static void setStorageOptions(@Nullable StorageOptions newStorageOptions) {
     futureStorageOptions = newStorageOptions;

google-cloud-examples/src/main/java/com/google/cloud/examples/nio/snippets/UseExplicitCredentials.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2019 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.
+ */
+
+package com.google.cloud.examples.nio.snippets;
+
+import com.google.auth.oauth2.ServiceAccountCredentials;
+import com.google.cloud.storage.StorageOptions;
+import com.google.cloud.storage.contrib.nio.CloudStorageConfiguration;
+import com.google.cloud.storage.contrib.nio.CloudStorageFileSystem;
+import java.io.FileInputStream;
+import java.io.IOException;
+
+/**
+ * A snippet for Google Cloud Storage NIO that shows how to create a {@link CloudStorageFileSystem}
+ * using explicitly-provided credentials instead of the default ones.
+ */
+public class UseExplicitCredentials {
+
+  public static void main(String... args) throws IOException {
+    // Create a file system for the bucket using the service account credentials
+    // saved in the file below.
+    String myCredentials = "/path/to/my/key.json";
+    CloudStorageFileSystem fs =
+        CloudStorageFileSystem.forBucket(
+            "mybucket",
+            CloudStorageConfiguration.DEFAULT,
+            StorageOptions.newBuilder()
+                .setCredentials(
+                    ServiceAccountCredentials.fromStream(new FileInputStream(myCredentials)))
+                .build());
+    // Can now read and write to the bucket using fs
+    // (see e.g. ReadAllLines for an example).
+  }
+}