ACL examples (#1399)

jerjou · garrettjonesgoogle · commit 7729401e875c · 2016-11-27T08:54:39.000-08:00
* Add GCS sample for getting a user's ACL
* Example for getting ACL of blob for specific user
diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/storage/snippets/StorageSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/storage/snippets/StorageSnippets.java
@@ -717,6 +717,19 @@ public Acl getBucketAcl(String bucketName) {
     return acl;
   }
 
+  /**
+   * Example of getting the ACL entry for a specific user on a bucket.
+   */
+  // [TARGET getAcl(String, Entity)]
+  // [VARIABLE "my_unique_bucket"]
+  // [VARIABLE "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com"]
+  public Acl getBucketAcl(String bucketName, String userEmail) {
+    // [START storagePrintBucketAclForUser]
+    Acl acl = storage.getAcl(bucketName, new User(userEmail));
+    // [END storagePrintBucketAclForUser]
+    return acl;
+  }
+
   /**
    * Example of deleting the ACL entry for an entity on a bucket.
    */
@@ -858,6 +871,21 @@ public Acl getBlobAcl(String bucketName, String blobName, long blobGeneration) {
     return acl;
   }
 
+  /**
+   * Example of getting the ACL entry for a specific user on a blob.
+   */
+  // [TARGET getAcl(BlobId, Entity)]
+  // [VARIABLE "my_unique_bucket"]
+  // [VARIABLE "my_blob_name"]
+  // [VARIABLE "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com"]
+  public Acl getBlobAcl(String bucketName, String blobName, String userEmail) {
+    // [START storagePrintFileAclForUser]
+    BlobId blobId = BlobId.of(bucketName, blobName);
+    Acl acl = storage.getAcl(blobId, new User(userEmail));
+    // [END storagePrintFileAclForUser]
+    return acl;
+  }
+
   /**
    * Example of deleting the ACL entry for an entity on a blob.
    */
diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/storage/snippets/ITStorageSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/storage/snippets/ITStorageSnippets.java
@@ -27,6 +27,7 @@
 
 import com.google.cloud.Page;
 import com.google.cloud.storage.Acl;
+import com.google.cloud.storage.Acl.Role;
 import com.google.cloud.storage.Acl.User;
 import com.google.cloud.storage.Blob;
 import com.google.cloud.storage.BlobId;
@@ -63,6 +64,8 @@ public class ITStorageSnippets {
 
   private static final Logger log = Logger.getLogger(ITStorageSnippets.class.getName());
   private static final String BUCKET = RemoteStorageHelper.generateBucketName();
+  private static final String USER_EMAIL = "google-cloud-java-tests@"
+      + "java-docs-samples-tests.iam.gserviceaccount.com";
 
   private static Storage storage;
   private static StorageSnippets storageSnippets;
@@ -290,6 +293,14 @@ public void testBucketAcl() {
     assertEquals(Acl.Role.OWNER, updatedAcl.getRole());
     Set<Acl> acls = Sets.newHashSet(storageSnippets.listBucketAcls(BUCKET));
     assertTrue(acls.contains(updatedAcl));
+
+    assertNotNull(storageSnippets.getBucketAcl(BUCKET));
+    assertNull(storageSnippets.getBucketAcl(BUCKET, USER_EMAIL));
+    storage.createAcl(BUCKET, Acl.of(new User(USER_EMAIL), Role.READER));
+    Acl userAcl = storageSnippets.getBucketAcl(BUCKET, USER_EMAIL);
+    assertNotNull(userAcl);
+    assertEquals(USER_EMAIL, ((User)userAcl.getEntity()).getEmail());
+
     assertTrue(storageSnippets.deleteBucketAcl(BUCKET));
     assertNull(storageSnippets.getBucketAcl(BUCKET));
   }
@@ -321,13 +332,20 @@ public void testBlobAcl() {
         storageSnippets.listBlobAcls(BUCKET, blobName, createdBlob.getGeneration()));
     assertTrue(acls.contains(updatedAcl));
 
+    assertNull(storageSnippets.getBlobAcl(BUCKET, blobName, USER_EMAIL));
+    storage.createAcl(BlobId.of(BUCKET, blobName), Acl.of(new User(USER_EMAIL), Role.READER));
+    Acl userAcl = storageSnippets.getBlobAcl(BUCKET, blobName, USER_EMAIL);
+    assertNotNull(userAcl);
+    assertEquals(USER_EMAIL, ((User)userAcl.getEntity()).getEmail());
+
     updatedAcl = storageSnippets.blobToPublicRead(BUCKET, blobName, createdBlob.getGeneration());
     assertEquals(Acl.Role.READER, updatedAcl.getRole());
     assertEquals(User.ofAllUsers(), updatedAcl.getEntity());
     acls = Sets.newHashSet(
         storageSnippets.listBlobAcls(BUCKET, blobName, createdBlob.getGeneration()));
     assertTrue(acls.contains(updatedAcl));
 
+    assertNotNull(storageSnippets.getBlobAcl(BUCKET, blobName, createdBlob.getGeneration()));
     assertTrue(storageSnippets.deleteBlobAcl(BUCKET, blobName, createdBlob.getGeneration()));
     assertNull(storageSnippets.getBlobAcl(BUCKET, blobName, createdBlob.getGeneration()));
     // test non-existing blob
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java
@@ -2248,6 +2248,13 @@ public static Builder newBuilder() {
    * Acl acl = storage.getAcl(bucketName, User.ofAllAuthenticatedUsers());
    * }</pre>
    *
+   * <p>Example of getting the ACL entry for a specific user on a bucket.
+   * <pre> {@code
+   * String bucketName = "my_unique_bucket";
+   * String userEmail = "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com";
+   * Acl acl = storage.getAcl(bucketName, new User(userEmail));
+   * }</pre>
+   *
    * @throws StorageException upon failure
    */
   Acl getAcl(String bucket, Entity entity);
@@ -2418,6 +2425,15 @@ public static Builder newBuilder() {
    * Acl acl = storage.getAcl(blobId, User.ofAllAuthenticatedUsers());
    * }</pre>
    *
+   * <p>Example of getting the ACL entry for a specific user on a blob.
+   * <pre> {@code
+   * String bucketName = "my_unique_bucket";
+   * String blobName = "my_blob_name";
+   * String userEmail = "google-cloud-java-tests@java-docs-samples-tests.iam.gserviceaccount.com";
+   * BlobId blobId = BlobId.of(bucketName, blobName);
+   * Acl acl = storage.getAcl(blobId, new User(userEmail));
+   * }</pre>
+   *
    * @throws StorageException upon failure
    */
   Acl getAcl(BlobId blob, Entity entity);
