Minor wording and link changes to testing readme.

googleapis · Oct 8, 2015 · 59722fa · 59722fa
1 parent 25bde60
commit 59722fa
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -14,6 +14,7 @@ Java idiomatic client for [Google Cloud Platform][cloud-platform] services.
 This client supports the following Google Cloud Platform services:
 
 -  [Google Cloud Datastore] (#google-cloud-datastore)
+-  [Google Cloud Storage] (#google-cloud-storage)
 
 <!---
 -  [Google Cloud Storage] (https://cloud.google.com/storage/)
@@ -44,7 +45,7 @@ Example Applications
 Google Cloud Datastore
 ----------------------
 
-Google [Cloud Datastore][cloud-datastore] is a fully managed, schemaless database for
+[Google Cloud Datastore][cloud-datastore] is a fully managed, schemaless database for
 storing non-relational data. Cloud Datastore automatically scales with
 your users and supports ACID transactions, high availability of reads and
 writes, strong consistency for reads and ancestor queries, and eventual
@@ -86,6 +87,53 @@ if (entity == null) {
 }
 ```
 
+Google Cloud Storage
+----------------------
+
+[Google Cloud Storage][cloud-storage] is a durable and highly available
+object storage service. Google Cloud Storage is almost infinitely scalable
+and guarantees consistency: when a write succeeds, the latest copy of the
+object will be returned to any GET, globally.
+
+See the [Google Cloud Storage docs][cloud-storage-activation] for more details on how to activate
+Cloud Storage for your project.
+
+See the ``gcloud-java`` API [storage documentation][storage-api] to learn how to interact
+with the Cloud Storage using this Client Library.
+
+```java
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import com.google.gcloud.storage.Blob;
+import com.google.gcloud.storage.Storage;
+import com.google.gcloud.storage.StorageFactory;
+import com.google.gcloud.storage.StorageOptions;
+
+import java.nio.ByteBuffer;
+import java.nio.channels.WritableByteChannel;
+
+StorageOptions options = StorageOptions.builder().projectId(PROJECT_ID).build();
+Storage storage = StorageFactory.instance().get(options);
+Blob blob = new Blob(storage, "bucket", "blob_name");
+if (!blob.exists()) {
+  storage2.create(blob.info(), "Hello, Cloud Storage!".getBytes(UTF_8));
+} else {
+  System.out.println("Updating content for " + blob.info().name());
+  byte[] prevContent = blob.content();
+  System.out.println(new String(prevContent, UTF_8));
+  WritableByteChannel channel = blob.writer();
+  channel.write(ByteBuffer.wrap("Updated content".getBytes(UTF_8)));
+  channel.close();
+}
+```
+
+Testing
+-------
+
+This library provides tools to help write tests for code that use gcloud-java services.
+
+See [TESTING] to read more about using our testing helpers.
+
 Contributing
 ------------
 
@@ -118,6 +166,7 @@ Apache 2.0 - See [LICENSE] for more information.
 [CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md
 [code-of-conduct]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CODE_OF_CONDUCT.md
 [LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE
+[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md
 [cloud-platform]: https://cloud.google.com/
 [cloud-datastore]: https://cloud.google.com/datastore/docs
 [cloud-datastore-docs]: https://cloud.google.com/datastore/docs
@@ -130,3 +179,5 @@ Apache 2.0 - See [LICENSE] for more information.
 [cloud-storage]: https://cloud.google.com/storage/
 [cloud-storage-docs]: https://cloud.google.com/storage/docs/overview
 [cloud-storage-create-bucket]: https://cloud.google.com/storage/docs/cloud-console#_creatingbuckets
+[cloud-storage-activation]: https://cloud.google.com/storage/docs/signup
+[storage-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/storage/package-summary.html
diff --git a/TESTING.md b/TESTING.md
@@ -1,8 +1,8 @@
 ## gcloud-java tools for testing
 
-gcloud-java provides tools to make testing your application easier.
+This library provides tools to help write tests for code that uses gcloud-java services.
 
-### Testing interactions with Datastore
+### Testing code that uses Datastore
 
 #### On your machine
 
@@ -16,7 +16,7 @@ You can test against a temporary local datastore by following these steps:
   ```java
   DatastoreOptions options = DatastoreOptions.builder()
       .projectId(PROJECT_ID)
-      .host("localhost:8080")
+      .host("http://localhost:8080")
       .build();
   Datastore localDatastore = DatastoreFactory.instance().get(options);
   ```
@@ -33,37 +33,31 @@ You can test against a remote datastore emulator as well.  To do this, set the `
   ```java
   DatastoreOptions options = DatastoreOptions.builder()
       .projectId(PROJECT_ID)
-      .host("http://<hostname of machine>")
+      .host("http://<hostname of machine>:<port>")
       .build();
   Datastore localDatastore = DatastoreFactory.instance().get(options);
   ```
 
-Note that the remote datastore must be running before your tests are run.  Also note that the `host` argument must start with "http://" or "https://" if you are testing with a remote machine.
+Note that the remote datastore must be running before your tests are run.
 
 
-### Testing interactions with Storage
+### Testing code that uses Storage
 
-There currently isn't an emulator for Google Cloud Storage, so an alternative is to create a test project.  `RemoteGcsHelper` contains convenience methods to make setting up and cleaning up the test project easier.  To use this class, follow the steps below:
+Currently, there isn't an emulator for Google Cloud Storage, so an alternative is to create a test project.  `RemoteGcsHelper` contains convenience methods to make setting up and cleaning up the test project easier.  To use this class, follow the steps below:
 
 1. Create a test Google Cloud project.
 
-2. Create and download a JSON service account credentials file from the Google Developer's Console.  See more about this on the [Google Cloud Platform Storage Authentication page][cloud-platform-storage-authentication]. 
+2. Download a JSON service account credentials file from the Google Developer's Console.  See more about this on the [Google Cloud Platform Storage Authentication page][cloud-platform-storage-authentication]. 
 
-3. Set environment variables `GCLOUD_TESTS_PROJECT_ID` and `GCLOUD_TESTS_KEY` according to your test project's ID and the location of the newly-downloaded JSON key file.  On linux and mac, for example,
-  ```
-  export GCLOUD_TESTS_PROJECT_ID=<project id>
-  export GCLOUD_TESTS_KEY=/path/to/JSON/key.json
-  ```
-
-4. Create and and use a `RemoteGcsHelper` object.
+3. Create and use a `RemoteGcsHelper` object using your project ID and JSON key.
 Here is an example that uses the `RemoteGcsHelper` to create a bucket and clear the bucket at the end of the test.
-```java
-RemoteGcsHelper gcsHelper = RemoteGcsHelper.create();
-Storage storage = StorageFactory.instance().get(gcsHelper.options());
-String bucket = RemoteGcsHelper.generateBucketName();
-storage.create(BucketInfo.of(bucket));
-// Do tests using Storage
-RemoteGcsHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
-```
+  ```java
+  RemoteGcsHelper gcsHelper = RemoteGcsHelper.create(PROJECT_ID, "/path/to/my/JSON/key.json");
+  Storage storage = StorageFactory.instance().get(gcsHelper.options());
+  String bucket = RemoteGcsHelper.generateBucketName();
+  storage.create(BucketInfo.of(bucket));
+  // Do tests using Storage
+  RemoteGcsHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
+  ```
 
 [cloud-platform-storage-authentication]:https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts
diff --git a/gcloud-java-datastore/README.md b/gcloud-java-datastore/README.md
@@ -72,9 +72,9 @@ if (entity == null) {
 Testing
 -------
 
-This library makes testing interactions with Cloud Datastore easier by using a local datastore emulator.
+This library has tools to help write tests for code that uses the Datastore.
 
-See [TESTING] to read more about testing locally.
+See [TESTING] to read more about testing.
 
 Contributing
 ------------
@@ -105,7 +105,7 @@ Apache 2.0 - See [LICENSE] for more information.
 
 [CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md
 [LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE
-[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md
+[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md#testing-code-that-uses-datastore
 [cloud-platform]: https://cloud.google.com/
 [cloud-datastore]: https://cloud.google.com/datastore/docs
 [cloud-datastore-docs]: https://cloud.google.com/datastore/docs

diff --git a/gcloud-java-storage/README.md b/gcloud-java-storage/README.md
@@ -29,7 +29,7 @@ Add this to your pom.xml file
 Testing
 -------
 
-This library makes testing interactions with Cloud Storage more convenient.
+This library has tools to help make tests for code using Cloud Storage.
 
 See [TESTING] to read more about testing.
 
@@ -62,7 +62,7 @@ Apache 2.0 - See [LICENSE] for more information.
 
 [CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md
 [LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE
-[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md
+[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md#testing-code-that-uses-storage
 [cloud-platform]: https://cloud.google.com/
 
 [cloud-storage]: https://cloud.google.com/storage/