Merge pull request #572 from ajkannan/project-extends-projectinfo

Make Project a subclass of ProjectInfo

Author: ajkannan

README.md

@@ -210,20 +210,22 @@ Google Cloud Resource Manager (Alpha)
 Here is a code snippet showing a simple usage example. Note that you must supply Google SDK credentials for this service, not other forms of authentication listed in the [Authentication section](#authentication).
 
 ```java
-import com.google.gcloud.resourcemanager.ProjectInfo;
+import com.google.gcloud.resourcemanager.Project;
 import com.google.gcloud.resourcemanager.ResourceManager;
 import com.google.gcloud.resourcemanager.ResourceManagerOptions;
 
 import java.util.Iterator;
 
 ResourceManager resourceManager = ResourceManagerOptions.defaultInstance().service();
-ProjectInfo myProject = resourceManager.get("some-project-id"); // Use an existing project's ID
-ProjectInfo newProjectInfo = resourceManager.replace(myProject.toBuilder()
-    .addLabel("launch-status", "in-development").build());
-System.out.println("Updated the labels of project " + newProjectInfo.projectId()
-    + " to be " + newProjectInfo.labels());
+Project myProject = resourceManager.get("some-project-id"); // Use an existing project's ID
+Project newProject = myProject.toBuilder()
+    .addLabel("launch-status", "in-development")
+    .build()
+    .replace();
+System.out.println("Updated the labels of project " + newProject.projectId()
+    + " to be " + newProject.labels());
 // List all the projects you have permission to view.
-Iterator<ProjectInfo> projectIterator = resourceManager.list().iterateAll();
+Iterator<Project> projectIterator = resourceManager.list().iterateAll();
 System.out.println("Projects I can view:");
 while (projectIterator.hasNext()) {
   System.out.println(projectIterator.next().projectId());

gcloud-java-examples/src/main/java/com/google/gcloud/examples/ResourceManagerExample.java

@@ -17,6 +17,7 @@
 package com.google.gcloud.examples;
 
 import com.google.common.base.Joiner;
+import com.google.gcloud.resourcemanager.Project;
 import com.google.gcloud.resourcemanager.ProjectInfo;
 import com.google.gcloud.resourcemanager.ResourceManager;
 import com.google.gcloud.resourcemanager.ResourceManagerOptions;
@@ -64,7 +65,7 @@ public void run(ResourceManager resourceManager, String... args) {
           labels.put(args[i], "");
         }
       }
-      ProjectInfo project =
+      Project project =
           resourceManager.create(ProjectInfo.builder(projectId).labels(labels).build());
       System.out.printf(
           "Successfully created project '%s': %s.%n", projectId, projectDetails(project));

gcloud-java-resourcemanager/README.md

@@ -83,33 +83,36 @@ ResourceManager resourceManager = ResourceManagerOptions.defaultInstance().servi
 All you need to create a project is a globally unique project ID.  You can also optionally attach a non-unique name and labels to your project. Read more about naming guidelines for project IDs, names, and labels [here](https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects). To create a project, add the following import at the top of your file:
 
 ```java
+import com.google.gcloud.resourcemanager.Project;
 import com.google.gcloud.resourcemanager.ProjectInfo;
 ```
 
 Then add the following code to create a project (be sure to change `myProjectId` to your own unique project ID).
 
 ```java
 String myProjectId = "my-globally-unique-project-id"; // Change to a unique project ID.
-ProjectInfo myProject = resourceManager.create(ProjectInfo.builder(myProjectId).build());
+Project myProject = resourceManager.create(ProjectInfo.builder(myProjectId).build());
 ```
 
-Note that the return value from `create` is a `ProjectInfo` that includes additional read-only information, like creation time, project number, and lifecycle state. Read more about these fields on the [Projects page](https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects).
+Note that the return value from `create` is a `Project` that includes additional read-only information, like creation time, project number, and lifecycle state. Read more about these fields on the [Projects page](https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects). `Project`, a subclass of `ProjectInfo`, adds a layer of service-related functionality over `ProjectInfo`.
 
 #### Getting a specific project
 You can load a project if you know it's project ID and have read permissions to the project. For example, to get the project we just created we can do the following:
 
 ```java
-ProjectInfo projectFromServer = resourceManager.get(myProjectId);
+Project projectFromServer = resourceManager.get(myProjectId);
 ```
 
 #### Editing a project
-To edit a project, create a new `ProjectInfo` object and pass it in to the `ResourceManager.replace` method.
+To edit a project, create a new `ProjectInfo` object and pass it in to the `Project.replace` method.
 
 For example, to add a label for the newly created project to denote that it's launch status is "in development", add the following code:
 
 ```java
-ProjectInfo newProjectInfo = resourceManager.replace(projectFromServer.toBuilder()
-    .addLabel("launch-status", "in-development").build());
+Project newProject = myProject.toBuilder()
+    .addLabel("launch-status", "in-development")
+    .build()
+    .replace();
 ```
 
 Note that the values of the project you pass in to `replace` overwrite the server's values for non-read-only fields, namely `projectName` and `labels`. For example, if you create a project with `projectName` "some-project-name" and subsequently call replace using a `ProjectInfo` object that didn't set the `projectName`, then the server will unset the project's name. The server ignores any attempted changes to the read-only fields `projectNumber`, `lifecycleState`, and `createTime`. The `projectId` cannot change.
@@ -124,7 +127,7 @@ import java.util.Iterator;
 Then add the following code to print a list of projects you can view:
 
 ```java
-Iterator<ProjectInfo> projectIterator = resourceManager.list().iterateAll();
+Iterator<Project> projectIterator = resourceManager.list().iterateAll();
 System.out.println("Projects I can view:");
 while (projectIterator.hasNext()) {
   System.out.println(projectIterator.next().projectId());
@@ -136,6 +139,7 @@ while (projectIterator.hasNext()) {
 Here we put together all the code shown above into one program.  This program assumes that you are running from your own desktop and used the Google Cloud SDK to authenticate yourself.
 
 ```java
+import com.google.gcloud.resourcemanager.Project;
 import com.google.gcloud.resourcemanager.ProjectInfo;
 import com.google.gcloud.resourcemanager.ResourceManager;
 import com.google.gcloud.resourcemanager.ResourceManagerOptions;
@@ -151,20 +155,22 @@ public class GcloudJavaResourceManagerExample {
 
     // Create a project.
     String myProjectId = "my-globally-unique-project-id"; // Change to a unique project ID.
-    ProjectInfo myProject = resourceManager.create(ProjectInfo.builder(myProjectId).build());
+    Project myProject = resourceManager.create(ProjectInfo.builder(myProjectId).build());
 
     // Get a project from the server.
-    ProjectInfo projectFromServer = resourceManager.get(myProjectId);
+    Project projectFromServer = resourceManager.get(myProjectId);
     System.out.println("Got project " + projectFromServer.projectId() + " from the server.");
 
     // Update a project
-    ProjectInfo newProjectInfo = resourceManager.replace(myProject.toBuilder()
-        .addLabel("launch-status", "in-development").build());
-    System.out.println("Updated the labels of project " + newProjectInfo.projectId()
-        + " to be " + newProjectInfo.labels());
+    Project newProject = myProject.toBuilder()
+        .addLabel("launch-status", "in-development")
+        .build()
+        .replace();
+    System.out.println("Updated the labels of project " + newProject.projectId()
+        + " to be " + newProject.labels());
 
     // List all the projects you have permission to view.
-    Iterator<ProjectInfo> projectIterator = resourceManager.list().iterateAll();
+    Iterator<Project> projectIterator = resourceManager.list().iterateAll();
     System.out.println("Projects I can view:");
     while (projectIterator.hasNext()) {
       System.out.println(projectIterator.next().projectId());

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

@@ -18,25 +18,110 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+import java.io.IOException;
+import java.io.ObjectInputStream;
+import java.util.Map;
+import java.util.Objects;
+
 /**
  * A Google Cloud Resource Manager project object.
  *
  * <p>A Project is a high-level Google Cloud Platform entity. It is a container for ACLs, APIs,
  * AppEngine Apps, VMs, and other Google Cloud Platform resources. This class' member variables are
- * immutable.  Methods that change or update the underlying Project information return a new Project
- * instance.
+ * immutable. Methods that change or update the underlying Project information return a new Project
+ * instance. {@code Project} adds a layer of service-related functionality over {@link ProjectInfo}.
  */
-public class Project {
+public class Project extends ProjectInfo {
 
-  private final ResourceManager resourceManager;
-  private final ProjectInfo info;
+  private static final long serialVersionUID = 6767630161335155133L;
 
-  /**
-   * Constructs a Project object that contains the ProjectInfo given.
-   */
-  public Project(ResourceManager resourceManager, ProjectInfo projectInfo) {
+  private final ResourceManagerOptions options;
+  private transient ResourceManager resourceManager;
+
+  public static class Builder extends ProjectInfo.Builder {
+    private final ResourceManager resourceManager;
+    private ProjectInfo.BuilderImpl infoBuilder;
+
+    Builder(ResourceManager resourceManager) {
+      this.resourceManager = resourceManager;
+      this.infoBuilder = new ProjectInfo.BuilderImpl();
+    }
+
+    Builder(Project project) {
+      this.resourceManager = project.resourceManager;
+      this.infoBuilder = new ProjectInfo.BuilderImpl(project);
+    }
+
+    @Override
+    public Builder name(String name) {
+      infoBuilder.name(name);
+      return this;
+    }
+
+    @Override
+    public Builder projectId(String projectId) {
+      infoBuilder.projectId(projectId);
+      return this;
+    }
+
+    @Override
+    public Builder addLabel(String key, String value) {
+      infoBuilder.addLabel(key, value);
+      return this;
+    }
+
+    @Override
+    public Builder removeLabel(String key) {
+      infoBuilder.removeLabel(key);
+      return this;
+    }
+
+    @Override
+    public Builder clearLabels() {
+      infoBuilder.clearLabels();
+      return this;
+    }
+
+    @Override
+    public Builder labels(Map<String, String> labels) {
+      infoBuilder.labels(labels);
+      return this;
+    }
+
+    @Override
+    Builder projectNumber(Long projectNumber) {
+      infoBuilder.projectNumber(projectNumber);
+      return this;
+    }
+
+    @Override
+    Builder state(State state) {
+      infoBuilder.state(state);
+      return this;
+    }
+
+    @Override
+    Builder createTimeMillis(Long createTimeMillis) {
+      infoBuilder.createTimeMillis(createTimeMillis);
+      return this;
+    }
+
+    @Override
+    Builder parent(ResourceId parent) {
+      infoBuilder.parent(parent);
+      return this;
+    }
+
+    @Override
+    public Project build() {
+      return new Project(resourceManager, infoBuilder);
+    }
+  }
+
+  Project(ResourceManager resourceManager, ProjectInfo.BuilderImpl infoBuilder) {
+    super(infoBuilder);
     this.resourceManager = checkNotNull(resourceManager);
-    this.info = checkNotNull(projectInfo);
+    this.options = resourceManager.options();
   }
 
   /**
@@ -46,15 +131,7 @@ public Project(ResourceManager resourceManager, ProjectInfo projectInfo) {
    * @throws ResourceManagerException upon failure
    */
   public static Project get(ResourceManager resourceManager, String projectId) {
-    ProjectInfo projectInfo = resourceManager.get(projectId);
-    return projectInfo != null ? new Project(resourceManager, projectInfo) : null;
-  }
-
-  /**
-   * Returns the {@link ProjectInfo} object associated with this Project.
-   */
-  public ProjectInfo info() {
-    return info;
+    return resourceManager.get(projectId);
   }
 
   /**
@@ -72,7 +149,7 @@ public ResourceManager resourceManager() {
    * @throws ResourceManagerException upon failure
    */
   public Project reload() {
-    return Project.get(resourceManager, info.projectId());
+    return Project.get(resourceManager, projectId());
   }
 
   /**
@@ -98,7 +175,7 @@ public Project reload() {
    * @throws ResourceManagerException upon failure
    */
   public void delete() {
-    resourceManager.delete(info.projectId());
+    resourceManager.delete(projectId());
   }
 
   /**
@@ -115,21 +192,52 @@ public void delete() {
    * @throws ResourceManagerException upon failure (including when the project can't be restored)
    */
   public void undelete() {
-    resourceManager.undelete(info.projectId());
+    resourceManager.undelete(projectId());
   }
 
   /**
-   * Replaces the attributes of the project.
+   * Replaces the attributes of the project with the attributes of this project.
    *
    * <p>The caller must have modify permissions for this project.
    *
    * @see <a
    * href="https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/update">Cloud
    * Resource Manager update</a>
-   * @return the ProjectInfo representing the new project metadata
+   * @return the Project representing the new project metadata
    * @throws ResourceManagerException upon failure
    */
-  public Project replace(ProjectInfo projectInfo) {
-    return new Project(resourceManager, resourceManager.replace(checkNotNull(projectInfo)));
+  public Project replace() {
+    return resourceManager.replace(this);
+  }
+
+  static Builder builder(ResourceManager resourceManager, String projectId) {
+    return new Builder(resourceManager).projectId(projectId);
+  }
+
+  @Override
+  public Builder toBuilder() {
+    return new Builder(this);
+  }
+
+  @Override
+  public boolean equals(Object obj) {
+    return obj instanceof Project && Objects.equals(toPb(), ((Project) obj).toPb())
+        && Objects.equals(options, ((Project) obj).options);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(super.hashCode(), options);
+  }
+
+  private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
+    in.defaultReadObject();
+    this.resourceManager = options.service();
+  }
+
+  static Project fromPb(ResourceManager resourceManager,
+      com.google.api.services.cloudresourcemanager.model.Project answer) {
+    ProjectInfo info = ProjectInfo.fromPb(answer);
+    return new Project(resourceManager, new ProjectInfo.BuilderImpl(info));
   }
 }