make pubsub publish and pull package-private (#1544)

Author: pongad

google-cloud-pubsub/src/main/java/com/google/cloud/pubsub/spi/v1/PublisherClient.java

@@ -20,7 +20,6 @@
 
 import com.google.api.gax.grpc.ChannelAndExecutor;
 import com.google.api.gax.grpc.UnaryCallable;
-import com.google.api.gax.protobuf.PathTemplate;
 import com.google.iam.v1.GetIamPolicyRequest;
 import com.google.iam.v1.Policy;
 import com.google.iam.v1.SetIamPolicyRequest;
@@ -53,6 +52,8 @@
  * Service Description: The service that an application uses to manipulate topics, and to send
  * messages to a topic.
  *
+ * <p>To publish messages to a topic, see the Publisher class.
+ *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:
  *
@@ -127,39 +128,6 @@ public class PublisherClient implements AutoCloseable {
   private final UnaryCallable<TestIamPermissionsRequest, TestIamPermissionsResponse>
       testIamPermissionsCallable;
 
-  private static final PathTemplate PROJECT_PATH_TEMPLATE =
-      PathTemplate.createWithoutUrlEncoding("projects/{project}");
-
-  private static final PathTemplate TOPIC_PATH_TEMPLATE =
-      PathTemplate.createWithoutUrlEncoding("projects/{project}/topics/{topic}");
-
-  /** Formats a string containing the fully-qualified path to represent a project resource. */
-  public static final String formatProjectName(String project) {
-    return PROJECT_PATH_TEMPLATE.instantiate("project", project);
-  }
-
-  /** Formats a string containing the fully-qualified path to represent a topic resource. */
-  public static final String formatTopicName(String project, String topic) {
-    return TOPIC_PATH_TEMPLATE.instantiate(
-        "project", project,
-        "topic", topic);
-  }
-
-  /** Parses the project from the given fully-qualified path which represents a project resource. */
-  public static final String parseProjectFromProjectName(String projectName) {
-    return PROJECT_PATH_TEMPLATE.parse(projectName).get("project");
-  }
-
-  /** Parses the project from the given fully-qualified path which represents a topic resource. */
-  public static final String parseProjectFromTopicName(String topicName) {
-    return TOPIC_PATH_TEMPLATE.parse(topicName).get("project");
-  }
-
-  /** Parses the topic from the given fully-qualified path which represents a topic resource. */
-  public static final String parseTopicFromTopicName(String topicName) {
-    return TOPIC_PATH_TEMPLATE.parse(topicName).get("topic");
-  }
-
   /** Constructs an instance of PublisherClient with default settings. */
   public static final PublisherClient create() throws IOException {
     return create(PublisherSettings.defaultBuilder().build());
@@ -327,11 +295,13 @@ public final UnaryCallable<Topic, Topic> createTopicCallable() {
    * }
    * </code></pre>
    *
-   * @param topic The messages in the request will be published on this topic.
+   * @param topic The messages in the request will be published on this topic. Format is
+   *     `projects/{project}/topics/{topic}`.
    * @param messages The messages to publish.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
-  public final PublishResponse publish(TopicName topic, List<PubsubMessage> messages) {
+  /* package-private */ final PublishResponse publish(
+      TopicName topic, List<PubsubMessage> messages) {
 
     PublishRequest request =
         PublishRequest.newBuilder().setTopicWithTopicName(topic).addAllMessages(messages).build();
@@ -395,7 +365,7 @@ public final PublishResponse publish(PublishRequest request) {
    * }
    * </code></pre>
    */
-  public final UnaryCallable<PublishRequest, PublishResponse> publishCallable() {
+  /* package-private */ final UnaryCallable<PublishRequest, PublishResponse> publishCallable() {
     return publishCallable;
   }
 
@@ -412,7 +382,7 @@ public final UnaryCallable<PublishRequest, PublishResponse> publishCallable() {
    * }
    * </code></pre>
    *
-   * @param topic The name of the topic to get.
+   * @param topic The name of the topic to get. Format is `projects/{project}/topics/{topic}`.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final Topic getTopic(TopicName topic) {
@@ -481,7 +451,8 @@ public final UnaryCallable<GetTopicRequest, Topic> getTopicCallable() {
    * }
    * </code></pre>
    *
-   * @param project The name of the cloud project that topics belong to.
+   * @param project The name of the cloud project that topics belong to. Format is
+   *     `projects/{project}`.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final ListTopicsPagedResponse listTopics(ProjectName project) {
@@ -585,7 +556,8 @@ public final UnaryCallable<ListTopicsRequest, ListTopicsResponse> listTopicsCall
    * }
    * </code></pre>
    *
-   * @param topic The name of the topic that subscriptions are attached to.
+   * @param topic The name of the topic that subscriptions are attached to. Format is
+   *     `projects/{project}/topics/{topic}`.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final ListTopicSubscriptionsPagedResponse listTopicSubscriptions(TopicName topic) {
@@ -693,7 +665,7 @@ public final ListTopicSubscriptionsPagedResponse listTopicSubscriptions(
    * }
    * </code></pre>
    *
-   * @param topic Name of the topic to delete.
+   * @param topic Name of the topic to delete. Format is `projects/{project}/topics/{topic}`.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final void deleteTopic(TopicName topic) {
@@ -762,7 +734,7 @@ public final UnaryCallable<DeleteTopicRequest, Empty> deleteTopicCallable() {
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   Policy policy = Policy.newBuilder().build();
    *   Policy response = publisherClient.setIamPolicy(formattedResource, policy);
    * }
@@ -777,7 +749,7 @@ public final UnaryCallable<DeleteTopicRequest, Empty> deleteTopicCallable() {
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final Policy setIamPolicy(String resource, Policy policy) {
-    TOPIC_PATH_TEMPLATE.validate(resource, "setIamPolicy");
+
     SetIamPolicyRequest request =
         SetIamPolicyRequest.newBuilder().setResource(resource).setPolicy(policy).build();
     return setIamPolicy(request);
@@ -791,7 +763,7 @@ public final Policy setIamPolicy(String resource, Policy policy) {
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   Policy policy = Policy.newBuilder().build();
    *   SetIamPolicyRequest request = SetIamPolicyRequest.newBuilder()
    *     .setResource(formattedResource)
@@ -816,7 +788,7 @@ public final Policy setIamPolicy(SetIamPolicyRequest request) {
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   Policy policy = Policy.newBuilder().build();
    *   SetIamPolicyRequest request = SetIamPolicyRequest.newBuilder()
    *     .setResource(formattedResource)
@@ -841,7 +813,7 @@ public final UnaryCallable<SetIamPolicyRequest, Policy> setIamPolicyCallable() {
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   Policy response = publisherClient.getIamPolicy(formattedResource);
    * }
    * </code></pre>
@@ -852,7 +824,7 @@ public final UnaryCallable<SetIamPolicyRequest, Policy> setIamPolicyCallable() {
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final Policy getIamPolicy(String resource) {
-    TOPIC_PATH_TEMPLATE.validate(resource, "getIamPolicy");
+
     GetIamPolicyRequest request = GetIamPolicyRequest.newBuilder().setResource(resource).build();
     return getIamPolicy(request);
   }
@@ -866,7 +838,7 @@ public final Policy getIamPolicy(String resource) {
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   GetIamPolicyRequest request = GetIamPolicyRequest.newBuilder()
    *     .setResource(formattedResource)
    *     .build();
@@ -890,7 +862,7 @@ private final Policy getIamPolicy(GetIamPolicyRequest request) {
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   GetIamPolicyRequest request = GetIamPolicyRequest.newBuilder()
    *     .setResource(formattedResource)
    *     .build();
@@ -906,13 +878,14 @@ public final UnaryCallable<GetIamPolicyRequest, Policy> getIamPolicyCallable() {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD
   /**
-   * Returns permissions that a caller has on the specified resource.
+   * Returns permissions that a caller has on the specified resource. If the resource does not
+   * exist, this will return an empty set of permissions, not a NOT_FOUND error.
    *
    * <p>Sample code:
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   List&lt;String&gt; permissions = new ArrayList&lt;&gt;();
    *   TestIamPermissionsResponse response = publisherClient.testIamPermissions(formattedResource, permissions);
    * }
@@ -928,7 +901,7 @@ public final UnaryCallable<GetIamPolicyRequest, Policy> getIamPolicyCallable() {
    */
   public final TestIamPermissionsResponse testIamPermissions(
       String resource, List<String> permissions) {
-    TOPIC_PATH_TEMPLATE.validate(resource, "testIamPermissions");
+
     TestIamPermissionsRequest request =
         TestIamPermissionsRequest.newBuilder()
             .setResource(resource)
@@ -939,13 +912,14 @@ public final TestIamPermissionsResponse testIamPermissions(
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD
   /**
-   * Returns permissions that a caller has on the specified resource.
+   * Returns permissions that a caller has on the specified resource. If the resource does not
+   * exist, this will return an empty set of permissions, not a NOT_FOUND error.
    *
    * <p>Sample code:
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   List&lt;String&gt; permissions = new ArrayList&lt;&gt;();
    *   TestIamPermissionsRequest request = TestIamPermissionsRequest.newBuilder()
    *     .setResource(formattedResource)
@@ -964,13 +938,14 @@ public final TestIamPermissionsResponse testIamPermissions(TestIamPermissionsReq
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD
   /**
-   * Returns permissions that a caller has on the specified resource.
+   * Returns permissions that a caller has on the specified resource. If the resource does not
+   * exist, this will return an empty set of permissions, not a NOT_FOUND error.
    *
    * <p>Sample code:
    *
    * <pre><code>
    * try (PublisherClient publisherClient = PublisherClient.create()) {
-   *   String formattedResource = PublisherClient.formatTopicName("[PROJECT]", "[TOPIC]");
+   *   String formattedResource = TopicName.create("[PROJECT]", "[TOPIC]").toString();
    *   List&lt;String&gt; permissions = new ArrayList&lt;&gt;();
    *   TestIamPermissionsRequest request = TestIamPermissionsRequest.newBuilder()
    *     .setResource(formattedResource)