Add PubSub examples, update READMEs and package-info javadoc (googleapis#1075)

Author: mziccard

README.md

@@ -18,6 +18,7 @@ This client supports the following Google Cloud Platform services:
 -  [Google Cloud Compute] (#google-cloud-compute-alpha) (Alpha)
 -  [Google Cloud Datastore] (#google-cloud-datastore)
 -  [Google Cloud DNS] (#google-cloud-dns-alpha) (Alpha)
+-  [Google Cloud Pub/Sub] (#google-cloud-pubsub) (Alpha - Not working on App Engine Standard)
 -  [Google Cloud Resource Manager] (#google-cloud-resource-manager-alpha) (Alpha)
 -  [Google Cloud Storage] (#google-cloud-storage)
 
@@ -62,6 +63,8 @@ Example Applications
 - [`Flexible Environment/Datastore example`](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/managed_vms/datastore) - A simple app that uses Cloud Datastore to list the last 10 IP addresses that visited your site.
   - Read about how to run the application [here](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/master/managed_vms/README.md).
 - [`Flexible Environment/Storage example`](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/managed_vms/cloudstorage) - An app that uploads files to a public Cloud Storage bucket on the App Engine Flexible Environment runtime.
+- [`PubSubExample`](./gcloud-java-examples/src/main/java/com/google/cloud/examples/pubsub/PubSubExample.java) - A simple command line interface providing some of Cloud Pub/Sub's functionality
+  - Read more about using this application on the [`PubSubExample` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/cloud/examples/pubsub/PubSubExample.html).
 - [`ResourceManagerExample`](./gcloud-java-examples/src/main/java/com/google/cloud/examples/resourcemanager/ResourceManagerExample.java) - A simple command line interface providing some of Cloud Resource Manager's functionality
   - Read more about using this application on the [`ResourceManagerExample` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/cloud/examples/resourcemanager/ResourceManagerExample.html).
 - [`SparkDemo`](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/master/managed_vms/sparkjava) - An example of using `gcloud-java-datastore` from within the SparkJava and App Engine Flexible Environment frameworks.
@@ -368,6 +371,44 @@ ChangeRequestInfo changeRequest = changeBuilder.build();
 zone.applyChangeRequest(changeRequest);
 ```
 
+Google Cloud Pub/Sub (Alpha)
+----------------------
+
+- [API Documentation][pubsub-api]
+- [Official Documentation][cloud-pubsub-docs]
+
+#### Preview
+
+Here is a code snippet showing a simple usage example from within Compute Engine/App Engine
+Flexible. Note that you must [supply credentials](#authentication) and a project ID if running this
+snippet elsewhere. Complete source code can be found at
+[CreateSubscriptionAndPullMessages.java](./gcloud-java-examples/src/main/java/com/google/cloud/examples/pubsub/snippets/CreateSubscriptionAndPullMessages.java).
+
+```java
+import com.google.cloud.pubsub.Message;
+import com.google.cloud.pubsub.PubSub;
+import com.google.cloud.pubsub.PubSub.MessageConsumer;
+import com.google.cloud.pubsub.PubSub.MessageProcessor;
+import com.google.cloud.pubsub.PubSubOptions;
+import com.google.cloud.pubsub.Subscription;
+import com.google.cloud.pubsub.SubscriptionInfo;
+
+try (PubSub pubsub = PubSubOptions.defaultInstance().service()) {
+  Subscription subscription =
+      pubsub.create(SubscriptionInfo.of("test-topic", "test-subscription"));
+  MessageProcessor callback = new MessageProcessor() {
+    @Override
+    public void process(Message message) throws Exception {
+      System.out.printf("Received message \"%s\"%n", message.payloadAsString());
+    }
+  };
+  // Create a message consumer and pull messages (for 60 seconds)
+  try (MessageConsumer consumer = subscription.pullAsync(callback)) {
+    Thread.sleep(60_000);
+  }
+}
+```
+
 Google Cloud Resource Manager (Alpha)
 ----------------------
 
@@ -513,6 +554,7 @@ Apache 2.0 - See [LICENSE] for more information.
 [cloud-dns-docs]: https://cloud.google.com/dns/docs
 [cloud-dns-activation]: https://console.cloud.google.com/start/api?id=dns
 
+[pubsub-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/pubsub/package-summary.html
 [cloud-pubsub]: https://cloud.google.com/pubsub/
 [cloud-pubsub-docs]: https://cloud.google.com/pubsub/docs
 

TESTING.md

@@ -174,5 +174,46 @@ Here is an example that clears the dataset created in Step 3.
   RemoteBigQueryHelper.forceDelete(bigquery, dataset);
   ```
 
+### Testing code that uses Pub/Sub
+
+#### On your machine
+
+You can test against a temporary local Pub/Sub by following these steps:
+
+1. Start the local Pub/Sub emulator before running your tests using `LocalPubSubHelper`'s `create`
+and `start` methods. This will bind a port for communication with the local Pub/Sub emulator.
+  ```java
+  LocalPubSubHelper helper = LocalPubSubHelper.create();
+
+  helper.start(); // Starts the local Pub/Sub emulator in a separate process
+  ```
+
+2. Create and use a `PubSub` object with the options given by the `LocalPubSubHelper` instance. For
+example:
+  ```java
+  PubSub localPubsub = helper.options().service();
+  ```
+
+3. Run your tests.
+
+4. Stop the local Pub/Sub emulator by calling the `stop()` method, like so:
+  ```java
+  helper.stop();
+  ```
+
+#### On a remote machine
+
+You can test against a remote Pub/Sub emulator as well. To do this, set the `PubSubOptions` project
+endpoint to the hostname of the remote machine, like the example below.
+
+  ```java
+  PubSubOptions options = PubSubOptions.builder()
+      .projectId("my-project-id") // must match project ID specified on remote machine
+      .host("<hostname of machine>:<port>")
+      .authCredentials(AuthCredentials.noAuth())
+      .build();
+  PubSub localPubsub= options.service();
+  ```
+
 [cloud-platform-storage-authentication]:https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts
 [create-service-account]:https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount

gcloud-java-examples/README.md

@@ -100,6 +100,16 @@ To run examples from your command line:
     mvn exec:java -Dexec.mainClass="com.google.cloud.examples.dns.DnsExample" -Dexec.args="delete some-sample-zone"
     ```
 
+  * Here's an example run of `PubSubExample`.
+
+    Before running the example, go to the [Google Developers Console][developers-console] to ensure that "Google Cloud Pub/Sub" is enabled.
+    ```
+    mvn exec:java -Dexec.mainClass="com.google.cloud.examples.pubsub.PubSubExample" -Dexec.args="create topic test-topic"
+    mvn exec:java -Dexec.mainClass="com.google.cloud.examples.pubsub.PubSubExample" -Dexec.args="create subscription test-topic test-subscription"
+    mvn exec:java -Dexec.mainClass="com.google.cloud.examples.pubsub.PubSubExample" -Dexec.args="publish test-topic message1 message2"
+    mvn exec:java -Dexec.mainClass="com.google.cloud.examples.pubsub.PubSubExample" -Dexec.args="pull sync test-subscription 2"
+    ```
+
   * Here's an example run of `ResourceManagerExample`.
 
     Be sure to change the placeholder project ID "your-project-id" with your own globally unique project ID.

gcloud-java-examples/pom.xml

@@ -29,6 +29,7 @@
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>exec-maven-plugin</artifactId>
         <configuration>
+          <cleanupDaemonThreads>false</cleanupDaemonThreads>
           <skip>false</skip>
         </configuration>
       </plugin>