Update README, javadoc, and tests

googleapis · Jan 27, 2016 · c7795a5 · c7795a5
1 parent 5a7e887
commit c7795a5
Show file tree

Hide file tree

Showing 7 changed files with 66 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -209,20 +209,20 @@ 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()
+Project myProject = resourceManager.get("some-project-id"); // Use an existing project's ID
+Project newProject = resourceManager.replace(myProject.toBuilder()
     .addLabel("launch-status", "in-development").build());
-System.out.println("Updated the labels of project " + newProjectInfo.projectId()
-    + " to be " + newProjectInfo.labels());
+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());

diff --git a/gcloud-java-resourcemanager/README.md b/gcloud-java-resourcemanager/README.md
@@ -83,32 +83,33 @@ 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`, which simply contains metadata about projects.
 
 #### 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()
+Project newProject = myProject.replace(myProject.toBuilder()
     .addLabel("launch-status", "in-development").build());
 ```
 
@@ -124,7 +125,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 +137,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 +153,20 @@ 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()
+    Project newProject = resourceManager.replace(myProject.toBuilder()
         .addLabel("launch-status", "in-development").build());
-    System.out.println("Updated the labels of project " + newProjectInfo.projectId()
-        + " to be " + newProjectInfo.labels());
+    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());

diff --git a/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/Project.java b/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/Project.java
@@ -28,8 +28,9 @@
  *
  * <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. `Project`, a subclass of `ProjectInfo`, adds a layer of service-related functionality
+ * over `ProjectInfo`, which simply contains metadata about projects.
  */
 public class Project extends ProjectInfo {
 
@@ -235,8 +236,7 @@ private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundE
     this.resourceManager = options.service();
   }
 
-  static Project fromPb(
-      ResourceManager resourceManager,
+  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));

diff --git a/...java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManager.java b/...java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/ResourceManager.java
@@ -179,7 +179,7 @@ public static ProjectListOption fields(ProjectField... fields) {
    * @see <a
    * href="https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/create">Cloud
    * Resource Manager create</a>
-   * @return ProjectInfo object representing the new project's metadata. The returned object will
+   * @return Project object representing the new project's metadata. The returned object will
    *     include the following read-only fields supplied by the server: project number, lifecycle
    *     state, and creation time.
    * @throws ResourceManagerException upon failure
@@ -234,7 +234,7 @@ public static ProjectListOption fields(ProjectField... fields) {
    * @see <a
    * href="https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects/list">Cloud
    * Resource Manager list</a>
-   * @return {@code Page<ProjectInfo>}, a page of projects
+   * @return {@code Page<Project>}, a page of projects
    * @throws ResourceManagerException upon failure
    */
   Page<Project> list(ProjectListOption... options);
@@ -247,7 +247,7 @@ public static ProjectListOption fields(ProjectField... fields) {
    * @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
    */
   Project replace(ProjectInfo newProject);

diff --git a/...ud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/package-info.java b/...ud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/package-info.java
@@ -21,10 +21,10 @@
  * <pre> {@code
  * ResourceManager resourceManager = ResourceManagerOptions.defaultInstance().service();
  * String myProjectId = "my-globally-unique-project-id"; // Change to a unique project ID.
- * ProjectInfo myProject = resourceManager.create(ProjectInfo.builder(myProjectId).build());
- * ProjectInfo newProjectInfo = resourceManager.replace(myProject.toBuilder()
+ * Project myProject = resourceManager.create(ProjectInfo.builder(myProjectId).build());
+ * Project newProject = resourceManager.replace(myProject.toBuilder()
  *     .addLabel("launch-status", "in-development").build());
- * 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());

diff --git a/gcloud-java-resourcemanager/src/test/java/com/google/gcloud/resourcemanager/ProjectTest.java b/gcloud-java-resourcemanager/src/test/java/com/google/gcloud/resourcemanager/ProjectTest.java
@@ -23,11 +23,11 @@
 import static org.easymock.EasyMock.verify;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
 
 import com.google.common.collect.ImmutableMap;
 
 import org.junit.After;
-import org.junit.Before;
 import org.junit.Test;
 
 import java.util.Map;
@@ -53,26 +53,26 @@ public class ProjectTest {
   private Project expectedProject;
   private Project project;
 
-  @Before
-  public void setUp() throws Exception {
-    expect(serviceMockReturnsOptions.options()).andReturn(mockOptions).anyTimes();
+  @After
+  public void tearDown() throws Exception {
+    verify(resourceManager);
+  }
+
+  private void initializeExpectedProject(int optionsCalls) {
+    expect(serviceMockReturnsOptions.options()).andReturn(mockOptions).times(optionsCalls);
     replay(serviceMockReturnsOptions);
     resourceManager = createStrictMock(ResourceManager.class);
     expectedProject =
         new Project(serviceMockReturnsOptions, new ProjectInfo.BuilderImpl(PROJECT_INFO));
   }
 
-  @After
-  public void tearDown() throws Exception {
-    verify(resourceManager);
-  }
-
   private void initializeProject() {
     project = new Project(resourceManager, new ProjectInfo.BuilderImpl(PROJECT_INFO));
   }
 
   @Test
   public void testBuilder() {
+    initializeExpectedProject(2);
     replay(resourceManager);
     Project builtProject = Project.builder(serviceMockReturnsOptions, PROJECT_ID)
         .name(NAME)
@@ -87,16 +87,19 @@ public void testBuilder() {
     assertEquals(PROJECT_NUMBER, builtProject.projectNumber());
     assertEquals(CREATE_TIME_MILLIS, builtProject.createTimeMillis());
     assertEquals(STATE, builtProject.state());
+    assertSame(serviceMockReturnsOptions, builtProject.resourceManager());
   }
 
   @Test
   public void testToBuilder() {
+    initializeExpectedProject(4);
     replay(resourceManager);
     compareProjects(expectedProject, expectedProject.toBuilder().build());
   }
 
   @Test
   public void testGet() {
+    initializeExpectedProject(1);
     expect(resourceManager.get(PROJECT_INFO.projectId())).andReturn(expectedProject);
     replay(resourceManager);
     Project loadedProject = Project.get(resourceManager, PROJECT_INFO.projectId());
@@ -105,6 +108,7 @@ public void testGet() {
 
   @Test
   public void testReload() {
+    initializeExpectedProject(2);
     ProjectInfo newInfo = PROJECT_INFO.toBuilder().addLabel("k3", "v3").build();
     Project expectedProject =
         new Project(serviceMockReturnsOptions, new ProjectInfo.BuilderImpl(newInfo));
@@ -118,13 +122,15 @@ public void testReload() {
 
   @Test
   public void testLoadNull() {
+    initializeExpectedProject(1);
     expect(resourceManager.get(PROJECT_INFO.projectId())).andReturn(null);
     replay(resourceManager);
     assertNull(Project.get(resourceManager, PROJECT_INFO.projectId()));
   }
 
   @Test
   public void testReloadNull() {
+    initializeExpectedProject(1);
     expect(resourceManager.options()).andReturn(mockOptions);
     expect(resourceManager.get(PROJECT_INFO.projectId())).andReturn(null);
     replay(resourceManager);
@@ -135,12 +141,14 @@ public void testReloadNull() {
 
   @Test
   public void testResourceManager() {
+    initializeExpectedProject(1);
     replay(resourceManager);
     assertEquals(serviceMockReturnsOptions, expectedProject.resourceManager());
   }
 
   @Test
   public void testDelete() {
+    initializeExpectedProject(1);
     expect(resourceManager.options()).andReturn(mockOptions);
     resourceManager.delete(PROJECT_INFO.projectId());
     replay(resourceManager);
@@ -150,6 +158,7 @@ public void testDelete() {
 
   @Test
   public void testUndelete() {
+    initializeExpectedProject(1);
     expect(resourceManager.options()).andReturn(mockOptions);
     resourceManager.undelete(PROJECT_INFO.projectId());
     replay(resourceManager);
@@ -159,6 +168,7 @@ public void testUndelete() {
 
   @Test
   public void testReplace() {
+    initializeExpectedProject(2);
     ProjectInfo newInfo = PROJECT_INFO.toBuilder().addLabel("k3", "v3").build();
     Project expectedProject =
         new Project(serviceMockReturnsOptions, new ProjectInfo.BuilderImpl(newInfo));