feat: support conditional policies

google-cloud-core/src/main/java/com/google/cloud/Binding.java

@@ -16,64 +16,94 @@
 
 package com.google.cloud;
 
+import static com.google.common.base.Predicates.in;
+import static com.google.common.base.Predicates.not;
+
 import com.google.api.core.BetaApi;
 import com.google.auto.value.AutoValue;
 import com.google.common.base.Predicate;
-import com.google.common.base.Predicates;
 import com.google.common.collect.Collections2;
 import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
 import javax.annotation.Nullable;
 
+/**
+ * Class for Identity and Access Management (IAM) policies. IAM policies are used to specify access
+ * settings for Cloud Platform resources. A policy is a list of bindings. A binding assigns a set of
+ * identities to a role, where the identities can be user accounts, Google groups, Google domains,
+ * and service accounts. A role is a named list of permissions defined by IAM.
+ *
+ * @see <a href="https://cloud.google.com/iam/docs/reference/rest/v1/Policy">Policy</a>
+ */
 @BetaApi("This is a Beta API is not stable yet and may change in the future.")
 @AutoValue
 public abstract class Binding {
+  /** Get IAM Policy Binding Role */
   public abstract String getRole();
 
+  /** Get IAM Policy Binding Members */
   public abstract ImmutableList<String> getMembers();
 
+  /** Get IAM Policy Binding Condition */
   @Nullable
   public abstract Condition getCondition();
 
+  /** Create a Binding.Builder from an existing Binding */
   public abstract Builder toBuilder();
 
+  /** Create a new Binding.Builder */
   public static Builder newBuilder() {
-    return new AutoValue_Binding.Builder();
+    List<String> emptyMembers = ImmutableList.of();
+    return new AutoValue_Binding.Builder().setMembers(emptyMembers);
   }
 
   @AutoValue.Builder
   public abstract static class Builder {
+    /**
+     * Set IAM Role for Policy Binding
+     *
+     * @throws NullPointerException if the role is null.
+     */
     public abstract Builder setRole(String role);
 
-    public abstract Builder setMembers(List<String> members);
+    /**
+     * Set IAM Members for Policy Binding
+     *
+     * @throws NullPointerException if a member is null.
+     */
+    public abstract Builder setMembers(Iterable<String> members);
 
+    /** Set IAM Condition for Policy Binding */
     public abstract Builder setCondition(Condition condition);
 
-    public abstract String getRole();
-
-    public abstract ImmutableList<String> getMembers();
-
-    public abstract Condition getCondition();
+    /** Internal use to getMembers() in addMembers() and removeMembers() */
+    abstract ImmutableList<String> getMembers();
 
-    // Members property must be initialized before this method can be used.
-    public Builder addMembers(String... members) {
+    /**
+     * Add members to Policy Binding.
+     *
+     * @throws NullPointerException if a member is null.
+     */
+    public Builder addMembers(String member, String... moreMembers) {
       ImmutableList.Builder<String> membersBuilder = ImmutableList.builder();
       membersBuilder.addAll(getMembers());
-      for (String member : members) {
-        membersBuilder.add(member);
-      }
+      membersBuilder.addAll(Lists.asList(member, moreMembers));
       setMembers(membersBuilder.build());
       return this;
     }
 
-    // Members property must be initialized before this method can be used.
+    /**
+     * Remove members to Policy Binding.
+     *
+     * @throws NullPointerException if a member is null.
+     */
     public Builder removeMembers(String... members) {
-      Predicate<String> selectMembersNotInList =
-          Predicates.not(Predicates.in(Arrays.asList(members)));
+      Predicate<String> selectMembersNotInList = not(in(Arrays.asList(members)));
       Collection<String> filter = Collections2.filter(getMembers(), selectMembersNotInList);
-      setMembers(ImmutableList.copyOf(filter));
+      setMembers(filter);
       return this;
     }
 

google-cloud-core/src/main/java/com/google/cloud/Condition.java

@@ -18,34 +18,48 @@
 
 import com.google.api.core.BetaApi;
 import com.google.auto.value.AutoValue;
-import javax.annotation.Nullable;
 
+/**
+ * Class for Identity and Access Management (IAM) policies. IAM policies are used to specify access
+ * settings for Cloud Platform resources. A policy is a list of bindings. A binding assigns a set of
+ * identities to a role, where the identities can be user accounts, Google groups, Google domains,
+ * and service accounts. A role is a named list of permissions defined by IAM.
+ *
+ * @see <a href="https://cloud.google.com/iam/docs/reference/rest/v1/Policy">Policy</a>
+ * @see <a href="https://cloud.google.com/iam/docs/conditions-overview">IAM Conditions</a>
+ */
 @BetaApi("This is a Beta API is not stable yet and may change in the future.")
 @AutoValue
 public abstract class Condition {
-  @Nullable
+  /** Get IAM Policy Binding Condition Title */
   public abstract String getTitle();
 
-  @Nullable
+  /** Get IAM Policy Binding Condition Description */
   public abstract String getDescription();
 
-  @Nullable
+  /** Get IAM Policy Binding Condition Expression */
   public abstract String getExpression();
 
+  /** Create a new Condition.Builder from an existing Condition */
   public abstract Builder toBuilder();
 
+  /** Create a new Condition.Builder */
   public static Builder newBuilder() {
     return new AutoValue_Condition.Builder();
   }
 
   @AutoValue.Builder
   public abstract static class Builder {
+    /** Set IAM Policy Binding Condition Title */
     public abstract Builder setTitle(String title);
 
+    /** Set IAM Policy Binding Condition Description */
     public abstract Builder setDescription(String description);
 
+    /** Set IAM Policy Binding Condition Expression */
     public abstract Builder setExpression(String expression);
 
+    /** Build Builder which creates a Condition instance */
     public abstract Condition build();
   }
 }

google-cloud-core/src/main/java/com/google/cloud/Policy.java

@@ -43,12 +43,12 @@
  * identities to a role, where the identities can be user accounts, Google groups, Google domains,
  * and service accounts. A role is a named list of permissions defined by IAM.
  *
- * @see <a href="https://cloud.google.com/iam/reference/rest/v1/Policy">Policy</a>
+ * @see <a href="https://cloud.google.com/iam/docs/reference/rest/v1/Policy">Policy</a>
  */
 public final class Policy implements Serializable {
 
   private static final long serialVersionUID = -3348914530232544290L;
-  private final List<Binding> bindingsList;
+  private final ImmutableList<Binding> bindingsList;
   private final String etag;
   private final int version;
 
@@ -102,7 +102,7 @@ protected Policy fromPb(com.google.iam.v1.Policy policyPb) {
         Binding.Builder convertedBinding =
             Binding.newBuilder()
                 .setRole(bindingPb.getRole())
-                .setMembers(ImmutableList.copyOf(bindingPb.getMembersList()));
+                .setMembers(bindingPb.getMembersList());
         if (bindingPb.hasCondition()) {
           Expr expr = bindingPb.getCondition();
           convertedBinding.setCondition(
@@ -131,7 +131,7 @@ protected com.google.iam.v1.Policy toPb(Policy policy) {
       for (Binding binding : policy.getBindingsList()) {
         com.google.iam.v1.Binding.Builder bindingBuilder = com.google.iam.v1.Binding.newBuilder();
         bindingBuilder.setRole(binding.getRole());
-        bindingBuilder.addAllMembers(ImmutableList.copyOf(binding.getMembers()));
+        bindingBuilder.addAllMembers(binding.getMembers());
         if (binding.getCondition() != null) {
           Condition condition = binding.getCondition();
           bindingBuilder.setCondition(
@@ -163,9 +163,7 @@ protected Builder() {}
 
     @InternalApi("This class should only be extended within google-cloud-java")
     protected Builder(Policy policy) {
-      for (Binding binding : policy.bindingsList) {
-        bindingsList.add(binding.toBuilder().build());
-      }
+      bindingsList.addAll(policy.bindingsList);
       setEtag(policy.etag);
       setVersion(policy.version);
     }
@@ -175,7 +173,8 @@ protected Builder(Policy policy) {
      *
      * @throws NullPointerException if the given map is null or contains any null keys or values
      * @throws IllegalArgumentException if any identities in the given map are null or if policy
-     *     version is equal to 3 or has conditional bindings.
+     *     version is equal to 3 or has conditional bindings because conditional policies are not
+     *     supported
      */
     public final Builder setBindings(Map<Role, Set<Identity>> bindings) {
       checkNotNull(bindings, "The provided map of bindings cannot be null.");
@@ -207,7 +206,7 @@ public final Builder setBindings(Map<Role, Set<Identity>> bindings) {
      * Replaces the builder's List of bindings with the given List of Bindings.
      *
      * @throws NullPointerException if the given list is null, role is null, or contains any null
-     *     members in bindings.
+     *     members in bindings
      */
     public final Builder setBindings(List<Binding> bindings) {
       this.bindingsList.clear();
@@ -221,7 +220,12 @@ public final Builder setBindings(List<Binding> bindings) {
       return this;
     }
 
-    /** Removes the role (and all identities associated with that role) from the policy. */
+    /**
+     * Removes the role (and all identities associated with that role) from the policy.
+     *
+     * @throws IllegalArgumentException if policy version is equal to 3 or has conditional bindings
+     *     because conditional policies are not supported
+     */
     public final Builder removeRole(Role role) {
       checkArgument(
           !isConditional(this.version, this.bindingsList),
@@ -283,7 +287,7 @@ public final Builder addIdentity(Role role, Identity first, Identity... others)
      * Removes one or more identities from an existing binding. Does nothing if the binding
      * associated with the provided role doesn't exist.
      *
-     * @throws IllegalArgumentException if policy version is equal to 3 or has conditional bindings.
+     * @throws IllegalArgumentException if policy version is equal to 3 or has conditional bindings
      */
     public final Builder removeIdentity(Role role, Identity first, Identity... others) {
       checkArgument(
@@ -360,7 +364,7 @@ public Builder toBuilder() {
   /**
    * Returns the map of bindings that comprises the policy.
    *
-   * @throws IllegalArgumentException if policy version is equal to 3 or has conditional bindings.
+   * @throws IllegalArgumentException if policy version is equal to 3 or has conditional bindings
    */
   public Map<Role, Set<Identity>> getBindings() {
     checkArgument(
@@ -378,7 +382,7 @@ public Map<Role, Set<Identity>> getBindings() {
   }
 
   /** Returns the list of bindings that comprises the policy for version 3. */
-  public List<Binding> getBindingsList() {
+  public ImmutableList<Binding> getBindingsList() {
     return bindingsList;
   }
 
@@ -428,13 +432,10 @@ public boolean equals(Object obj) {
       return false;
     }
     Policy other = (Policy) obj;
-    if (bindingsList.size() != other.getBindingsList().size()) {
+    if (!bindingsList.equals(other.getBindingsList())) {
       return false;
     }
-    for (int i = 0; i < bindingsList.size(); i++) {
-      bindingsList.get(i).equals(other.getBindingsList().get(i));
-    }
-    return Objects.equals(etag, other.getEtag()) && Objects.equals(version, other.getVersion());
+    return Objects.equals(etag, other.getEtag()) && version == other.getVersion();
   }
 
   /** Returns a builder for {@code Policy} objects. */