Add javadoc and tests for functional Topic class (googleapis#1021)

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

@@ -30,7 +30,13 @@
 import java.util.concurrent.Future;
 
 /**
- * PubSub Topic.
+ * 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.
+ * {@code Topic} adds a layer of service-related functionality over {@link TopicInfo}. Objects of
+ * this class are immutable. To get a {@code Topic} object with the most recent information use
+ * {@link #reload} or {@link #reloadAsync}.
+ *
+ * @see <a href="https://cloud.google.com/pubsub/overview#data_model">Pub/Sub Data Model</a>
  */
 public class Topic extends TopicInfo {
 
@@ -39,6 +45,9 @@ public class Topic extends TopicInfo {
   private final PubSubOptions options;
   private transient PubSub pubsub;
 
+  /**
+   * A builder for {@code Topic} objects.
+   */
   public static final class Builder extends TopicInfo.Builder {
 
     private final PubSub pubsub;
@@ -73,70 +82,173 @@ public Builder toBuilder() {
   }
 
   @Override
-  public int hashCode() {
+  public final int hashCode() {
     return Objects.hash(options, super.hashCode());
   }
 
   @Override
-  public boolean equals(Object obj) {
-    if (this == obj) {
+  public final boolean equals(Object obj) {
+    if (obj == this) {
       return true;
     }
-    if (obj == null || getClass() != obj.getClass()) {
+    if (obj == null || !obj.getClass().equals(Topic.class)) {
       return false;
     }
     Topic other = (Topic) obj;
-    return Objects.equals(name(), other.name()) && Objects.equals(options, other.options);
+    return baseEquals(other) && Objects.equals(options, other.options);
   }
 
+  /**
+   * Returns the topic's {@code PubSub} object used to issue requests.
+   */
   public PubSub pubSub() {
     return pubsub;
   }
 
+  /**
+   * Deletes this topic.
+   *
+   * @return {@code true} if the topic was deleted, {@code false} if it was not found
+   * @throws PubSubException upon failure
+   */
   public boolean delete() {
     return pubsub.deleteTopic(name());
   }
 
+  /**
+   * Sends a request for deleting this topic. This method returns a {@code Future} object to consume
+   * the result. {@link Future#get()} returns {@code true} if the topic was deleted, {@code false}
+   * if it was not found.
+   *
+   * @throws PubSubException upon failure
+   */
   public Future<Boolean> deleteAsync() {
     return pubsub.deleteTopicAsync(name());
   }
 
+  /**
+   * Fetches current topic's latest information. Returns {@code null} if the topic does not exist.
+   *
+   * @return a {@code Topic} object with latest information or {@code null} if not found
+   * @throws PubSubException upon failure
+   */
   public Topic reload() {
     return pubsub.getTopic(name());
   }
 
+  /**
+   * Sends a request to fetch current topic's latest information. This method returns a
+   * {@code Future} object to consume the result. {@link Future#get()} returns a {@code Topic}
+   * object with latest information or {@code null} if not found.
+   *
+   * @throws PubSubException upon failure
+   */
   public Future<Topic> reloadAsync() {
     return pubsub.getTopicAsync(name());
   }
 
+  /**
+   * Publishes a message to this topic. This method returns a service-generated id for the published
+   * message. Service-generated ids are guaranteed to be unique within the topic.
+   *
+   * @param message the message to publish
+   * @return a unique service-generated id for the message
+   * @throws PubSubException upon failure, if the topic does not exist or if the message has empty
+   *     payload and no attributes
+   */
   public String publish(Message message) {
     return pubsub.publish(name(), message);
   }
 
+  /**
+   * Sends a request for publishing a message to the this topic. This method returns a
+   * {@code Future} object to consume the result. {@link Future#get()} returns a service-generated
+   * id for the published message. Service-generated ids are guaranteed to be unique within the
+   * topic.
+   *
+   * @param message the message to publish
+   * @return a {@code Future} for the unique service-generated id for the message
+   */
   public Future<String> publishAsync(Message message) {
     return pubsub.publishAsync(name(), message);
   }
 
+  /**
+   * Publishes a number of messages to this topic. This method returns a list of service-generated
+   * ids for the published messages. Service-generated ids are guaranteed to be unique within the
+   * topic.
+   *
+   * @param message the first message to publish
+   * @param messages other messages to publish
+   * @return a list of unique, service-generated, ids. Ids are in the same order as the messages.
+   * @throws PubSubException upon failure, if the topic does not exist or if one of the messages has
+   *     empty payload and no attributes
+   */
   public List<String> publish(Message message, Message... messages) {
     return pubsub.publish(name(), message, messages);
   }
 
+  /**
+   * Sends a request to publish a number of messages to this topic. This method returns a
+   * {@code Future} object to consume the result. {@link Future#get()} returns a list of
+   * service-generated ids for the published messages. Service-generated ids are guaranteed to be
+   * unique within the topic.
+   *
+   * @param message the first message to publish
+   * @param messages other messages to publish
+   * @return a {@code Future} for the unique, service-generated ids. Ids are in the same order as
+   *     the messages.
+   */
   public Future<List<String>> publishAsync(Message message, Message... messages) {
     return pubsub.publishAsync(name(), message, messages);
   }
 
+  /**
+   * Publishes a number of messages to this topic. This method returns a list ofservice-generated
+   * ids for the published messages. Service-generated ids are guaranteed to be unique within the
+   * topic.
+   *
+   * @param messages the messages to publish
+   * @return a list of unique, service-generated, ids. Ids are in the same order as the messages.
+   * @throws PubSubException upon failure, if the topic does not exist or if one of the messages has
+   *     empty payload and no attributes
+   */
   public List<String> publish(Iterable<Message> messages) {
     return pubsub.publish(name(), messages);
   }
 
+  /**
+   * Sends a request to publish a number of messages to this topic. This method returns a
+   * {@code Future} object to consume the result. {@link Future#get()} returns a list of
+   * service-generated ids for the published messages. Service-generated ids are guaranteed to be
+   * unique within the topic.
+   *
+   * @param messages the messages to publish
+   * @return a {@code Future} for the unique, service-generated ids. Ids are in the same order as
+   *     the messages.
+   */
   public Future<List<String>> publishAsync(Iterable<Message> messages) {
     return pubsub.publishAsync(name(), messages);
   }
 
+  /**
+   * Lists the identities of the subscriptions for this topic. This method returns a {@link Page}
+   * object that can be used to consume paginated results. Use {@link ListOption} to specify the
+   * page size or the page token from which to start listing subscriptions.
+   *
+   * @throws PubSubException upon failure
+   */
   public Page<SubscriptionId> listSubscriptions(ListOption... options) {
     return pubsub.listSubscriptions(name(), options);
   }
 
+  /**
+   * Sends a request for listing the identities of subscriptions for this topic. This method returns
+   * a {@code Future} object to consume the result. {@link Future#get()} returns an
+   * {@link AsyncPage} object that can be used to asynchronously handle paginated results. Use
+   * {@link ListOption} to specify the page size or the page token from which to start listing
+   * subscriptions.
+   */
   public Future<AsyncPage<SubscriptionId>> listSubscriptionsAsync(ListOption... options) {
     return pubsub.listSubscriptionsAsync(name(), options);
   }
@@ -146,9 +258,9 @@ private void readObject(ObjectInputStream input) throws IOException, ClassNotFou
     this.pubsub = options.service();
   }
 
-  static Topic fromPb(PubSub storage, com.google.pubsub.v1.Topic topicPb) {
+  static Topic fromPb(PubSub pubsub, com.google.pubsub.v1.Topic topicPb) {
     TopicInfo topicInfo = TopicInfo.fromPb(topicPb);
-    return new Topic(storage, new BuilderImpl(topicInfo));
+    return new Topic(pubsub, new BuilderImpl(topicInfo));
   }
 
   static Function<com.google.pubsub.v1.Topic, Topic> fromPbFunction(final PubSub pubsub) {

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

@@ -98,15 +98,16 @@ public int hashCode() {
     return Objects.hash(name);
   }
 
+  final boolean baseEquals(TopicInfo topicInfo) {
+    return Objects.equals(name, topicInfo.name);
+  }
+
   @Override
   public boolean equals(Object obj) {
-    if (this == obj) {
-      return true;
-    }
-    if (obj == null || !obj.getClass().equals(this.getClass())) {
-      return false;
-    }
-    return Objects.equals(name, ((TopicInfo) obj).name);
+    return obj == this
+        || obj != null
+        && obj.getClass().equals(TopicInfo.class)
+        && baseEquals((TopicInfo) obj);
   }
 
   @Override