feat: add interfaces for cloud pubsub publishers and subscribers (#134)

google-cloud-pubsub/src/main/java/com/google/cloud/pubsub/v1/Publisher.java

@@ -85,7 +85,7 @@
  * <p>{@link Publisher} will use the credentials set on the channel, which uses application default
  * credentials through {@link GoogleCredentials#getApplicationDefault} by default.
  */
-public class Publisher {
+public class Publisher implements PublisherInterface {
   private static final Logger logger = Logger.getLogger(Publisher.class.getName());
 
   private final String topicName;
@@ -226,6 +226,7 @@ public String getTopicNameString() {
    * @param message the message to publish.
    * @return the message ID wrapped in a future.
    */
+  @Override
   public ApiFuture<String> publish(PubsubMessage message) {
     Preconditions.checkState(!shutdown.get(), "Cannot publish on a shut-down publisher.");
 

google-cloud-pubsub/src/main/java/com/google/cloud/pubsub/v1/PublisherInterface.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2020 Google LLC
+ *
+ * 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.v1;
+
+import com.google.api.core.ApiFuture;
+import com.google.pubsub.v1.PubsubMessage;
+
+/**
+ * An interface for a Cloud Pub/Sub <a
+ * href="https://cloud.google.com/pubsub/docs/publisher">publisher</a>.
+ */
+public interface PublisherInterface {
+  /**
+   * Schedules the publishing of a message. The future will be returned with the message ID on
+   * success or an exception on failure.
+   *
+   * <p>Example of publishing a message.
+   *
+   * <pre>{@code
+   * String message = "my_message";
+   * ByteString data = ByteString.copyFromUtf8(message);
+   * PubsubMessage pubsubMessage = PubsubMessage.newBuilder().setData(data).build();
+   * ApiFuture<String> messageIdFuture = publisher.publish(pubsubMessage);
+   * ApiFutures.addCallback(messageIdFuture, new ApiFutureCallback<String>() {
+   *   public void onSuccess(String messageId) {
+   *     System.out.println("published with message id: " + messageId);
+   *   }
+   *
+   *   public void onFailure(Throwable t) {
+   *     System.out.println("failed to publish: " + t);
+   *   }
+   * }, MoreExecutors.directExecutor());
+   * }</pre>
+   *
+   * @param message the message to publish.
+   * @return the message ID wrapped in a future.
+   */
+  ApiFuture<String> publish(PubsubMessage message);
+}

google-cloud-pubsub/src/main/java/com/google/cloud/pubsub/v1/Subscriber.java

@@ -90,7 +90,7 @@
  * href="https://github.com/google/guava/wiki/ServiceExplained">Guava documentation</a> for more
  * details.
  */
-public class Subscriber extends AbstractApiService {
+public class Subscriber extends AbstractApiService implements SubscriberInterface {
   private static final int THREADS_PER_CHANNEL = 5;
   private static final int MAX_INBOUND_MESSAGE_SIZE =
       20 * 1024 * 1024; // 20MB API maximum message size.

google-cloud-pubsub/src/main/java/com/google/cloud/pubsub/v1/SubscriberInterface.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2020 Google LLC
+ *
+ * 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.v1;
+
+import com.google.api.core.ApiService;
+
+/**
+ * The core interface for a Cloud Pub/Sub <a
+ * href="https://cloud.google.com/pubsub/docs/subscriber">subscriber</a>, consisting only of
+ * ApiService methods.
+ */
+public interface SubscriberInterface extends ApiService {}