Make role and permission strings to allow for service-specific values

Author: Ajay Kannan

gcloud-java-examples/src/main/java/com/google/gcloud/examples/resourcemanager/snippets/ModifyPolicy.java

@@ -24,7 +24,7 @@
 
 import com.google.gcloud.Identity;
 import com.google.gcloud.resourcemanager.Policy;
-import com.google.gcloud.resourcemanager.Policy.Role;
+import com.google.gcloud.resourcemanager.Policy.ProjectRole;
 import com.google.gcloud.resourcemanager.Project;
 import com.google.gcloud.resourcemanager.ResourceManager;
 import com.google.gcloud.resourcemanager.ResourceManagerOptions;
@@ -49,7 +49,7 @@ public static void main(String... args) {
     // Add a viewer
     Policy.Builder modifiedPolicy = policy.toBuilder();
     Identity newViewer = Identity.user("<insert user's email address here>");
-    modifiedPolicy.addIdentity(Role.viewer(), newViewer);
+    modifiedPolicy.addIdentity(ProjectRole.VIEWER.value(), newViewer);
 
     // Write policy
     Policy updatedPolicy = project.replacePolicy(modifiedPolicy.build());

gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/Policy.java

@@ -23,13 +23,11 @@
 import com.google.gcloud.IamPolicy;
 import com.google.gcloud.Identity;
 
-import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Set;
 
 /**
@@ -42,120 +40,63 @@
  *
  * @see <a href="https://cloud.google.com/iam/reference/rest/v1/Policy">Policy</a>
  */
-public class Policy extends IamPolicy<Policy.Role> {
+public class Policy extends IamPolicy<String> {
 
   private static final long serialVersionUID = -5573557282693961850L;
 
   /**
-   * Represents legacy roles in an IAM Policy.
+   * The project-level roles in an IAM policy. This enum is not an exhaustive list of all roles
+   * you can use in an IAM policy. You can also use service-specific roles (e.g.
+   * <i>roles/pubsub.editor</i>).  See the <i>Supported Cloud Platform Services</i> page for links
+   * to service-specific roles.
+   *
+   * @see <a href="https://cloud.google.com/iam/#supported_cloud_platform_services">Supported Cloud
+   * Platform Services</a>
    */
-  public static class Role implements Serializable {
+  public enum ProjectRole {
 
     /**
-     * The recognized roles in a Project's IAM policy.
+     * Permissions for read-only actions that preserve state.
      */
-    public enum Type {
-
-      /**
-       * Permissions for read-only actions that preserve state.
-       */
-      VIEWER,
-
-      /**
-       * All viewer permissions and permissions for actions that modify state.
-       */
-      EDITOR,
-
-      /**
-       * All editor permissions and permissions for the following actions:
-       * <ul>
-       * <li>Manage access control for a resource.
-       * <li>Set up billing (for a project).
-       * </ul>
-       */
-      OWNER
-    }
-
-    private static final long serialVersionUID = 2421978909244287488L;
-
-    private final String value;
-    private final Type type;
-
-    private Role(String value, Type type) {
-      this.value = value;
-      this.type = type;
-    }
-
-    String value() {
-      return value;
-    }
+    VIEWER("roles/viewer"),
 
     /**
-     * Returns the type of role (editor, owner, or viewer).  Returns {@code null} if the role type
-     * is unrecognized.
+     * All viewer permissions and permissions for actions that modify state.
      */
-    public Type type() {
-      return type;
-    }
+    EDITOR("roles/editor"),
 
     /**
-     * Returns a {@code Role} of type {@link Type#VIEWER VIEWER}.
+     * All editor permissions and permissions for the following actions:
+     * <ul>
+     * <li>Manage access control for a resource.
+     * <li>Set up billing (for a project).
+     * </ul>
      */
-    public static Role viewer() {
-      return new Role("roles/viewer", Type.VIEWER);
-    }
+    OWNER("roles/owner");
 
-    /**
-     * Returns a {@code Role} of type {@link Type#EDITOR EDITOR}.
-     */
-    public static Role editor() {
-      return new Role("roles/editor", Type.EDITOR);
+    String value;
+
+    private ProjectRole(String value) {
+      this.value = value;
     }
 
     /**
-     * Returns a {@code Role} of type {@link Type#OWNER OWNER}.
+     * Returns the string value associated with the role.
      */
-    public static Role owner() {
-      return new Role("roles/owner", Type.OWNER);
-    }
-
-    static Role rawRole(String roleStr) {
-      return new Role(roleStr, null);
-    }
-
-    static Role fromStr(String roleStr) {
-      try {
-        Type type = Type.valueOf(roleStr.split("/")[1].toUpperCase());
-        return new Role(roleStr, type);
-      } catch (Exception ex) {
-        return new Role(roleStr, null);
-      }
-    }
-
-    @Override
-    public final int hashCode() {
-      return Objects.hash(value, type);
-    }
-
-    @Override
-    public final boolean equals(Object obj) {
-      if (!(obj instanceof Role)) {
-        return false;
-      }
-      Role other = (Role) obj;
-      return Objects.equals(value, other.value()) && Objects.equals(type, other.type());
+    public String value() {
+      return value;
     }
   }
 
   /**
    * Builder for an IAM Policy.
    */
-  public static class Builder extends IamPolicy.Builder<Role, Builder> {
+  public static class Builder extends IamPolicy.Builder<String, Builder> {
 
     private Builder() {}
 
     @VisibleForTesting
-    Builder(Map<Role, Set<Identity>> bindings, String etag, Integer version) {
+    Builder(Map<String, Set<Identity>> bindings, String etag, Integer version) {
       bindings(bindings).etag(etag).version(version);
     }
 
@@ -188,10 +129,10 @@ com.google.api.services.cloudresourcemanager.model.Policy toPb() {
         new com.google.api.services.cloudresourcemanager.model.Policy();
     List<com.google.api.services.cloudresourcemanager.model.Binding> bindingPbList =
         new LinkedList<>();
-    for (Map.Entry<Role, Set<Identity>> binding : bindings().entrySet()) {
+    for (Map.Entry<String, Set<Identity>> binding : bindings().entrySet()) {
       com.google.api.services.cloudresourcemanager.model.Binding bindingPb =
           new com.google.api.services.cloudresourcemanager.model.Binding();
-      bindingPb.setRole(binding.getKey().value());
+      bindingPb.setRole(binding.getKey());
       bindingPb.setMembers(
           Lists.transform(
               new ArrayList<>(binding.getValue()),
@@ -211,11 +152,11 @@ public String apply(Identity identity) {
 
   static Policy fromPb(
       com.google.api.services.cloudresourcemanager.model.Policy policyPb) {
-    Map<Role, Set<Identity>> bindings = new HashMap<>();
+    Map<String, Set<Identity>> bindings = new HashMap<>();
     for (com.google.api.services.cloudresourcemanager.model.Binding bindingPb :
         policyPb.getBindings()) {
       bindings.put(
-          Role.fromStr(bindingPb.getRole()),
+          bindingPb.getRole(),
           ImmutableSet.copyOf(
               Lists.transform(
                   bindingPb.getMembers(),

gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/Project.java

@@ -18,8 +18,6 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
-import com.google.gcloud.resourcemanager.ResourceManager.Permission;
-
 import java.io.IOException;
 import java.io.ObjectInputStream;
 import java.util.List;
@@ -235,16 +233,21 @@ public Policy replacePolicy(Policy newPolicy) {
    * if you're using Google Cloud Platform directly to manage permissions. This method is intended
    * for integration with your proprietary software, such as a customized graphical user interface.
    * For example, the Cloud Platform Console tests IAM permissions internally to determine which UI
-   * should be available to the logged-in user.
+   * should be available to the logged-in user.  Each service that supports IAM lists the possible
+   * permissions; see the <i>Supported Cloud Platform services</i> page below for links to these
+   * lists.
    *
    * @return a list of booleans representing whether the caller has the permissions specified (in
    *     the order of the given permissions)
    * @throws ResourceManagerException upon failure
    * @see <a href=
    *     "https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/testIamPermissions">
    *     Resource Manager testIamPermissions</a>
+   * @see <a href=
+   *     "https://cloud.google.com/iam/#supported_cloud_platform_services">Supported Cloud Platform
+   *     Services</a>
    */
-  List<Boolean> testPermissions(List<Permission> permissions) {
+  List<Boolean> testPermissions(List<String> permissions) {
     return resourceManager.testPermissions(projectId(), permissions);
   }
 
@@ -253,17 +256,22 @@ List<Boolean> testPermissions(List<Permission> permissions) {
    * if you're using Google Cloud Platform directly to manage permissions. This method is intended
    * for integration with your proprietary software, such as a customized graphical user interface.
    * For example, the Cloud Platform Console tests IAM permissions internally to determine which UI
-   * should be available to the logged-in user.
+   * should be available to the logged-in user. Each service that supports IAM lists the possible
+   * permissions; see the <i>Supported Cloud Platform services</i> page below for links to these
+   * lists.
    *
    * @return a list of booleans representing whether the caller has the permissions specified (in
    *     the order of the given permissions)
    * @throws ResourceManagerException upon failure
    * @see <a href=
    *     "https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/testIamPermissions">
    *     Resource Manager testIamPermissions</a>
+   * @see <a href=
+   *     "https://cloud.google.com/iam/#supported_cloud_platform_services">Supported Cloud Platform
+   *     Services</a>
    */
-  List<Boolean> testPermissions(Permission first, Permission... others) {
-    return resourceManager.testPermissions(projectId(), first, others);
+  List<Boolean> testPermissions(String firstPermission, String... otherPermissions) {
+    return resourceManager.testPermissions(projectId(), firstPermission, otherPermissions);
   }
 
   @Override

gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManager.java

@@ -169,38 +169,6 @@ public static ProjectListOption fields(ProjectField... fields) {
     }
   }
 
-  /**
-   * The permissions associated with a Google Cloud project. These values can be used when calling
-   * {@link #testPermissions}.
-   *
-   * @see <a href=
-   *     "https://cloud.google.com/resource-manager/docs/access-control-proj#project-level_roles">
-   *     Project-level roles</a>
-   */
-  enum Permission {
-    DELETE("delete"),
-    GET("get"),
-    GET_POLICY("getIamPolicy"),
-    REPLACE("update"),
-    REPLACE_POLICY("setIamPolicy"),
-    UNDELETE("undelete");
-
-    private static final String PREFIX = "resourcemanager.projects.";
-
-    private final String value;
-
-    Permission(String suffix) {
-      this.value = PREFIX + suffix;
-    }
-
-    /**
-     * Returns the string representation of the permission.
-     */
-    public String value() {
-      return value;
-    }
-  }
-
   /**
    * Creates a new project.
    *
@@ -358,30 +326,41 @@ public String value() {
    * this method if you're using Google Cloud Platform directly to manage permissions. This method
    * is intended for integration with your proprietary software, such as a customized graphical user
    * interface. For example, the Cloud Platform Console tests IAM permissions internally to
-   * determine which UI should be available to the logged-in user.
+   * determine which UI should be available to the logged-in user. Each service that supports IAM
+   * lists the possible permissions; see the <i>Supported Cloud Platform services</i> page below for
+   * links to these lists.
    *
    * @return A list of booleans representing whether the caller has the permissions specified (in
    *     the order of the given permissions)
    * @throws ResourceManagerException upon failure
    * @see <a href=
    *     "https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/testIamPermissions">
    *     Resource Manager testIamPermissions</a>
+   * @see <a href=
+   *     "https://cloud.google.com/iam/#supported_cloud_platform_services">Supported Cloud Platform
+   *     Services</a>
    */
-  List<Boolean> testPermissions(String projectId, List<Permission> permissions);
+  List<Boolean> testPermissions(String projectId, List<String> permissions);
 
   /**
    * Returns the permissions that a caller has on the specified project. You typically don't call
    * this method if you're using Google Cloud Platform directly to manage permissions. This method
    * is intended for integration with your proprietary software, such as a customized graphical user
    * interface. For example, the Cloud Platform Console tests IAM permissions internally to
-   * determine which UI should be available to the logged-in user.
+   * determine which UI should be available to the logged-in user. Each service that supports IAM
+   * lists the possible permissions; see the <i>Supported Cloud Platform services</i> page below for
+   * links to these lists.
    *
    * @return A list of booleans representing whether the caller has the permissions specified (in
    *     the order of the given permissions)
    * @throws ResourceManagerException upon failure
    * @see <a href=
    *     "https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/testIamPermissions">
    *     Resource Manager testIamPermissions</a>
+   * @see <a href=
+   *     "https://cloud.google.com/iam/#supported_cloud_platform_services">Supported Cloud Platform
+   *     Services</a>
    */
-  List<Boolean> testPermissions(String projectId, Permission first, Permission... others);
+  List<Boolean> testPermissions(
+      String projectId, String firstPermission, String... otherPermissions);
 }

gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManagerImpl.java

@@ -216,19 +216,13 @@ public com.google.api.services.cloudresourcemanager.model.Policy call() {
   }
 
   @Override
-  public List<Boolean> testPermissions(final String projectId, final List<Permission> permissions) {
+  public List<Boolean> testPermissions(final String projectId, final List<String> permissions) {
     try {
       return runWithRetries(
           new Callable<List<Boolean>>() {
             @Override
             public List<Boolean> call() {
-              return resourceManagerRpc.testPermissions(projectId,
-                  Lists.transform(permissions, new Function<Permission, String>() {
-                      @Override
-                      public String apply(Permission permission) {
-                        return permission.value();
-                      }
-                  }));
+              return resourceManagerRpc.testPermissions(projectId, permissions);
             }
           }, options().retryParams(), EXCEPTION_HANDLER);
     } catch (RetryHelperException ex) {
@@ -237,8 +231,9 @@ public String apply(Permission permission) {
   }
 
   @Override
-  public List<Boolean> testPermissions(String projectId, Permission first, Permission... others) {
-    return testPermissions(projectId, Lists.asList(first, others));
+  public List<Boolean> testPermissions(
+      String projectId, String firstPermission, String... otherPermissions) {
+    return testPermissions(projectId, Lists.asList(firstPermission, otherPermissions));
   }
 
   private Map<ResourceManagerRpc.Option, ?> optionMap(Option... options) {