Add javadoc and unit tests for TopicInfo (#976)

gcloud-java-pubsub/src/main/java/com/google/cloud/pubsub/PubSubImpl.java

@@ -22,6 +22,7 @@
 import com.google.cloud.BaseService;
 import com.google.cloud.Page;
 import com.google.cloud.pubsub.spi.PubSubRpc;
+import com.google.cloud.pubsub.spi.v1.PublisherApi;
 import com.google.common.base.Function;
 import com.google.common.base.Throwables;
 import com.google.common.util.concurrent.Uninterruptibles;
@@ -59,7 +60,7 @@ public Topic create(TopicInfo topic) {
 
   @Override
   public Future<Topic> createAsync(TopicInfo topic) {
-    return lazyTransform(rpc.create(topic.toPb()), Topic.fromPbFunction(this));
+    return lazyTransform(rpc.create(topic.toPb(options().projectId())), Topic.fromPbFunction(this));
   }
 
   @Override
@@ -69,7 +70,9 @@ public Topic getTopic(String topic) {
 
   @Override
   public Future<Topic> getTopicAsync(String topic) {
-    GetTopicRequest request = GetTopicRequest.newBuilder().setTopic(topic).build();
+    GetTopicRequest request = GetTopicRequest.newBuilder()
+        .setTopic(PublisherApi.formatTopicName(options().projectId(), topic))
+        .build();
     return lazyTransform(rpc.get(request), Topic.fromPbFunction(this));
   }
 
@@ -80,7 +83,9 @@ public boolean deleteTopic(String topic) {
 
   @Override
   public Future<Boolean> deleteTopicAsync(String topic) {
-    DeleteTopicRequest request = DeleteTopicRequest.newBuilder().setTopic(topic).build();
+    DeleteTopicRequest request = DeleteTopicRequest.newBuilder()
+        .setTopic(PublisherApi.formatTopicName(options().projectId(), topic))
+        .build();
     return lazyTransform(rpc.delete(request), new Function<Empty, Boolean>() {
       @Override
       public Boolean apply(Empty input) {

gcloud-java-pubsub/src/main/java/com/google/cloud/pubsub/Topic.java

@@ -86,7 +86,7 @@ public boolean equals(Object obj) {
       return false;
     }
     Topic other = (Topic) obj;
-    return Objects.equals(toPb(), other.toPb()) && Objects.equals(options, other.options);
+    return Objects.equals(name(), other.name()) && Objects.equals(options, other.options);
   }
 
   public PubSub pubSub() {

gcloud-java-pubsub/src/main/java/com/google/cloud/pubsub/TopicInfo.java

@@ -18,13 +18,17 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+import com.google.cloud.pubsub.spi.v1.PublisherApi;
 import com.google.common.base.MoreObjects;
 
 import java.io.Serializable;
 import java.util.Objects;
 
 /**
- * Pub/Sub Topic information.
+ * A Google Cloud Pub/Sub topic. A topic is a named resource to which messages are sent by
+ * publishers. Subscribers can receive messages sent to a topic by creating subscriptions.
+ *
+ * @see <a href="https://cloud.google.com/pubsub/overview#data_model">Pub/Sub Data Model</a>
  */
 public class TopicInfo implements Serializable {
 
@@ -33,12 +37,21 @@ public class TopicInfo implements Serializable {
   private final String name;
 
   /**
-   * Builder for TopicInfo.
+   * Builder for {@code TopicInfo} objects.
    */
   public abstract static class Builder {
 
+    /**
+     * Sets the name of the topic. The name must start with a letter, and contain only letters
+     * ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores ({@code _}),
+     * periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs ({@code %}). It
+     * must be between 3 and 255 characters in length and cannot begin with the string {@code goog}.
+     */
     public abstract Builder name(String name);
 
+    /**
+     * Creates a topic object.
+     */
     public abstract TopicInfo build();
   }
 
@@ -70,6 +83,12 @@ public TopicInfo build() {
     name = builder.name;
   }
 
+  /**
+   * Returns the name of the topic. The name must start with a letter, and contain only letters
+   * ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores ({@code _}),
+   * periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs ({@code %}). It
+   * must be between 3 and 255 characters in length and cannot begin with the string {@code goog}.
+   */
   public String name() {
     return name;
   }
@@ -84,10 +103,10 @@ public boolean equals(Object obj) {
     if (this == obj) {
       return true;
     }
-    if (obj == null || getClass() != obj.getClass()) {
+    if (obj == null || !obj.getClass().equals(this.getClass())) {
       return false;
     }
-    return Objects.equals(toPb(), ((TopicInfo) obj).toPb());
+    return Objects.equals(name, ((TopicInfo) obj).name);
   }
 
   @Override
@@ -97,22 +116,42 @@ public String toString() {
         .toString();
   }
 
-  com.google.pubsub.v1.Topic toPb() {
-    return com.google.pubsub.v1.Topic.newBuilder().setName(name).build();
+  com.google.pubsub.v1.Topic toPb(String projectId) {
+    return com.google.pubsub.v1.Topic.newBuilder()
+        .setName(PublisherApi.formatTopicName(projectId, name))
+        .build();
   }
 
   static TopicInfo fromPb(com.google.pubsub.v1.Topic topicPb) {
-    return builder(topicPb.getName()).build();
+    return builder(PublisherApi.parseTopicFromTopicName(topicPb.getName())).build();
   }
 
   public Builder toBuilder() {
     return new BuilderImpl(this);
   }
 
+  /**
+   * Creates a {@code TopicInfo} object given the name of the topic.
+   *
+   * @param name the name of the topic. The name must start with a letter, and contain only letters
+   *     ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores ({@code _}),
+   *     periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs ({@code %}).
+   *     It must be between 3 and 255 characters in length and cannot begin with the string
+   *     {@code goog}.
+   */
   public static TopicInfo of(String name) {
     return builder(name).build();
   }
 
+  /**
+   * Creates a builder for {@code TopicInfo} objects given the name of the topic.
+   *
+   * @param name the name of the topic. The name must start with a letter, and contain only letters
+   *     ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores ({@code _}),
+   *     periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs ({@code %}).
+   *     It must be between 3 and 255 characters in length and cannot begin with the string
+   *     {@code goog}.
+   */
   public static Builder builder(String name) {
     return new BuilderImpl(name);
   }

gcloud-java-pubsub/src/test/java/com/google/cloud/pubsub/TopicInfoTest.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.pubsub;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+
+public class TopicInfoTest {
+
+  private static final String NAME = "topic";
+  private static final TopicInfo TOPIC_INFO = TopicInfo.builder("topic").build();
+
+  @Test
+  public void testToBuilder() {
+    compareTopicInfo(TOPIC_INFO, TOPIC_INFO.toBuilder().build());
+    TopicInfo topicInfo = TOPIC_INFO.toBuilder()
+        .name("newTopic")
+        .build();
+    assertEquals("newTopic", topicInfo.name());
+    topicInfo = topicInfo.toBuilder().name(NAME).build();
+    compareTopicInfo(TOPIC_INFO, topicInfo);
+  }
+
+  @Test
+  public void testBuilder() {
+    assertEquals(NAME, TOPIC_INFO.name());
+    TopicInfo topicInfo = TopicInfo.builder("wrongName").name(NAME).build();
+    compareTopicInfo(TOPIC_INFO, topicInfo);
+  }
+
+  @Test
+  public void testOf() {
+    compareTopicInfo(TOPIC_INFO, TopicInfo.of(NAME));
+  }
+
+  @Test
+  public void testToAndFromPb() {
+    compareTopicInfo(TOPIC_INFO, TopicInfo.fromPb(TOPIC_INFO.toPb("project")));
+    assertEquals("projects/project/topics/topic", TOPIC_INFO.toPb("project").getName());
+  }
+
+  private void compareTopicInfo(TopicInfo expected, TopicInfo value) {
+    assertEquals(expected, value);
+    assertEquals(expected.name(), value.name());
+    assertEquals(expected.hashCode(), value.hashCode());
+  }
+}