Pull updates from master branch

.travis.yml

@@ -8,7 +8,8 @@ before_install:
 - git clone -b travis `git config --get remote.origin.url` target/travis
 - cp target/travis/settings.xml ~/.m2/settings.xml
 install: mvn install -DskipTests=true -Dgpg.skip=true
-script: mvn verify
+script: 
+- utilities/verify.sh
 branches:
   only:
   - master
@@ -20,3 +21,5 @@ env:
   - secure: "CUM2l73KFm7U4eDsUKkh1WyEUzF3v94Ltvs7MnKU9olE1dNp3YmRBL9Lqhx3hSDqm/xv0ETQsPy29Fs2+VFkhQQxSley6iS/4trr2fioTB680txfXo/zDdmGSP1q1/U40fv1S+jvuBRAhDV5W+8dhWOGtzMH0tJp/TszeDGlmCY="
   - secure: "YBbdzseg5yDFpQIiMoc3P2BTmqef4o+KAvrLMEbobXjIkiglUQ7UHCoRWClX74fTKAwuC7JvK7o5xJGLnaY43jJADXrGtE8/d44HNJaieE67mNosDYtOiA0iI2uIRFCAnXJCZ8f/iHx2xVMHMNWlwyoil4IUcjj+D7FRcsT5alE="
   - secure: "Od7BwllgFXVfzFe8ooTNm05TR+Xd5QjHW0oqhU8vclaQs2oX4e0eNIsebXQfLi3xDgd1pz5uUQC/Z4S0NqACwyUuUvPdGYYmRPTR7Dh8HgGJ4ojSdN3RwaHsxUqG7Ajts9rIHOtRpY28xOChVRNX0Z7eAPlvxYU4Ed2ZEo356r0="
+  - secure: "ROxa8HHuba+Dfixljq6poW1+Uwv8EaZUtTTTB7KEtAHJRN8rwoNS4TC0U0PEHcYAL+ivxP3zIfWOCoWreJGoa+V8y9BtLSuamUj/SSsuoHRdJjq5BmcHI/77P11HAzCH6Ul/GxsRB52/IRHwJyfKkh8XUMVSsCl7AG4CKUgt63Y="
+  - secure: "MKZ3y6IYp3Z67T+BO4Brw+my8sRMSMdWWgvUcyBpwQZ64w7ccHJCce4W8WHCPNko/eczHHCJELPG28VNyPTWIV/Jt2ZJ6L9qLCjsQpDPOdJdDaAKc9Df4sm8fB0FBiPVDwMYPQF1/Sy2gK7FZf0YR3LOeoyzswRgmj5bQMdVEeU="

README.md

@@ -9,15 +9,11 @@ Java idiomatic client for [Google Cloud Platform][cloud-platform] services.
 
 -  [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
 -  [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs)
--  [Examples] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/examples/package-summary.html)
 
 This client supports the following Google Cloud Platform services:
 
 -  [Google Cloud Datastore] (#google-cloud-datastore)
-
-<!---
--  [Google Cloud Storage] (https://cloud.google.com/storage/)
---->
+-  [Google Cloud Storage] (#google-cloud-storage)
 
 > Note: This client is a work-in-progress, and may occasionally
 > make backwards-incompatible changes.
@@ -29,32 +25,39 @@ Add this to your pom.xml file
 <dependency>
   <groupId>com.google.gcloud</groupId>
   <artifactId>gcloud-java</artifactId>
-  <version>0.0.7</version>
+  <version>0.0.10</version>
 </dependency>
 ```
 
-<!---
 Example Applications
 --------------------
 
--  `java-datastore-sample`_ - A sample using Cloud Datastore
-.. _java-datastore-sample: https://github.com/GoogleCloudPlatform/java-datastore-sample
---->
+- [`DatastoreExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/DatastoreExample.java) - A simple command line interface for the Cloud Datastore
+  - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/DatastoreExample.html).
+- [`StorageExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/StorageExample.java) - A simple command line interface providing some of Cloud Storage's functionality
+  - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/StorageExample.html).
+
+Authentication
+--------------
+
+There are multiple ways to authenticate to use Google Cloud services.
+
+1. When using `gcloud-java` libraries from within Compute/App Engine, no additional authentication steps are necessary.
+2. When using `gcloud-java` libraries elsewhere, there are two options:
+  * [Generate a JSON service account key](https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts).  Supply a path to the downloaded JSON credentials file when building the options supplied to datastore/storage constructor.
+  * If running locally for development/testing, you can use use [Google Cloud SDK](https://cloud.google.com/sdk/?hl=en).  To use the SDK authentication, [download the SDK](https://cloud.google.com/sdk/?hl=en) if you haven't already.  Then login using the SDK (`gcloud auth login` in command line), and set your current project using `gcloud config set project PROJECT_ID`.
 
 Google Cloud Datastore
 ----------------------
 
-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
-consistency for all other queries.
+- [API Documentation][datastore-api]
+- [Official Documentation][cloud-datastore-docs]
 
-See the [Google Cloud Datastore docs][cloud-datastore-activation] for more details on how to activate
-Cloud Datastore for your project.
+*Follow the [activation instructions][cloud-datastore-activation] to use the Google Cloud Datastore API with your project.*
 
-See the ``gcloud-java`` API [datastore documentation][datastore-api] to learn how to interact
-with the Cloud Datastore using this Client Library.
+#### Preview
+
+Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
 
 ```java
 import com.google.gcloud.datastore.Datastore;
@@ -65,8 +68,7 @@ import com.google.gcloud.datastore.Entity;
 import com.google.gcloud.datastore.Key;
 import com.google.gcloud.datastore.KeyFactory;
 
-DatastoreOptions options = DatastoreOptions.builder().projectId(PROJECT_ID).build();
-Datastore datastore = DatastoreFactory.instance().get(options);
+Datastore datastore = DatastoreFactory.instance().get(DatastoreOptions.getDefaultInstance());
 KeyFactory keyFactory = datastore.newKeyFactory().kind(KIND);
 Key key = keyFactory.newKey(keyName);
 Entity entity = datastore.get(key);
@@ -86,20 +88,59 @@ if (entity == null) {
 }
 ```
 
-Contributing
-------------
+Google Cloud Storage
+----------------------
 
-Contributions to this library are always welcome and highly encouraged.
+- [API Documentation][storage-api]
+- [Official Documentation][cloud-storage-docs]
 
-See [CONTRIBUTING] for more information on how to get started.
+*Follow the [activation instructions][cloud-storage-activation] to use the Google Cloud Storage API with your project.*
 
-Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information.
+#### Preview
+
+Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
+
+```java
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import com.google.gcloud.storage.Blob;
+import com.google.gcloud.storage.BlobId;
+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").build();
+Storage storage = StorageFactory.instance().get(options);
+BlobId blobId = BlobId.of("bucket", "blob_name");
+Blob blob = Blob.load(storage, blobId);
+if (blob == null) {
+  BlobInfo blobInfo = BlobInfo.builder(blobId).contentType("text/plain").build();
+  storage.create(blobInfo, "Hello, Cloud Storage!".getBytes(UTF_8));
+} else {
+  System.out.println("Updating content for " + blobId.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();
+}
+```
 
 Java Versions
 -------------
 
 Java 7 or above is required for using this client.
 
+Testing
+-------
+
+This library provides tools to help write tests for code that uses gcloud-java services.
+
+See [TESTING] to read more about using our testing helpers.
+
 Versioning
 ----------
 
@@ -109,6 +150,15 @@ It is currently in major version zero (``0.y.z``), which means that anything
 may change at any time and the public API should not be considered
 stable.
 
+Contributing
+------------
+
+Contributions to this library are always welcome and highly encouraged.
+
+See [CONTRIBUTING] for more information on how to get started.
+
+Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information.
+
 License
 -------
 
@@ -118,6 +168,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 +181,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

RELEASING.md

@@ -0,0 +1,27 @@
+### Overview
+
+Most of the release process is handled by the `after_success.sh` script, triggered after Travis CI successfully completes a non-PR build.  A new artifact will be released to Maven Central Repository via Travis CI when "-SNAPSHOT" is not included in the version (as listed in the base directory's `pom.xml`).  The website and README files will also be updated automatically in this case.  When "-SNAPSHOT" is included in the version, Travis only updates the artifact in the snapshot repository.
+
+### To push a release version
+
+1. Run `utilities/update_pom_version.sh` from the repository's base directory.
+This script takes an optional argument denoting the new version.  By default, if the current version is X.Y.Z-SNAPSHOT, the script will update the version in all the pom.xml files to X.Y.Z.  If desired, another version can be supplied via command line argument instead.
+
+2. Create a PR to update the pom.xml version.
+The PR should look something like [#225](https://github.com/GoogleCloudPlatform/gcloud-java/pull/225).  After this PR is merged into GoogleCloudPlatform/gcloud-java, Travis CI will push a new website to GoogleCloudPlatform/gh-pages, push a new artifact to the Maven Central Repository, and update versions in the README files.
+
+3. Create a release on Github manually.
+Go to the [releases page](https://github.com/GoogleCloudPlatform/gcloud-java/releases) and click "Draft a new release."  Use `vX.Y.Z` as the "Tag Version" and `X.Y.Z` as the "Release Title", where `X.Y.Z` is the release version as listed in the `pom.xml` files.
+
+4. Run `utilities/update_pom_version.sh` again (to include "-SNAPSHOT" in the project version).
+As mentioned before, there is an optional version argument.  By default, the script will update the version from "X.Y.Z" to "X.Y.Z+1-SNAPSHOT".  Suppose a different version is desired, for example X+1.0.0-SNAPSHOT.  Then the appropriate command to run would be `utilities/update_pom_version.sh X+1.0.0-SNAPSHOT`.
+
+5. Create and merge in another PR to reflect the updated project version.  For an example of what this PR should look like, see [#227](https://github.com/GoogleCloudPlatform/gcloud-java/pull/227).
+
+### To push a snapshot version
+
+Pushing a snapshot is completely automated.  If "-SNAPSHOT" is included in the version denoted by the base directory's pom.xml, then an updated artifact will be pushed to the snapshot repository when Travis CI successfully completes a non-PR build.
+
+### Improvements
+
+Automatic tagging is not currently implemented, though it was discussed in [#119](https://github.com/GoogleCloudPlatform/gcloud-java/pull/119).  If the version updates continue to be manual, a one-line git tag command can be added to `after_success.sh` to correctly tag releases.  However, automatically creating useful annotations for this tag will be difficult.  Also, if the release process becomes fully automated, tagging becomes a harder problem, as mentioned in that issue.

TESTING.md

@@ -0,0 +1,69 @@
+## gcloud-java tools for testing
+
+This library provides tools to help write tests for code that uses gcloud-java services.
+
+### Testing code that uses Datastore
+
+#### On your machine
+
+You can test against a temporary local datastore by following these steps:
+
+1. Start the local datastore emulator using `LocalGcdHelper`.  This can be done in two ways:
+  - Run `LocalGcdHelper.java`'s `main` method with arguments `START` and (optionally) `--port=<port number>`.  This will create a temporary folder on your computer and bind `localhost:<port number>` for communication with the local datastore.  The port number is an optional argument.  If no port number is specified, port 8080 will be used.
+  - Call `LocalGcdHelper.start(<project ID>, <port number>)` before running your tests.  Save the `LocalGcdHelper` object returned so that you can stop the emulator later.
+
+2. In your program, create and use a datastore whose host is set host to `localhost:<port number>`.  For example, 
+  ```java
+  DatastoreOptions options = DatastoreOptions.builder()
+      .projectId(PROJECT_ID)
+      .host("http://localhost:8080")
+      .build();
+  Datastore localDatastore = DatastoreFactory.instance().get(options);
+  ```
+3. Run your tests.
+
+4. Stop the local datastore emulator.
+  - If you ran `LocalGcdHelper.java`'s `main` function to start the emulator, run `LocalGcdHelper.java`'s `main` method with arguments `STOP` and (optionally) `--port=<port number>`.  If the port is not supplied, the program will attempt to close the last port started.
+  - If you ran `LocalGcdHelper.start()` to start the emulator, call the `stop()` method on the `LocalGcdHelper` object returned by `LocalGcdHelper.start()`.
+
+#### On a remote machine
+
+You can test against a remote datastore emulator as well.  To do this, set the `DatastoreOptions` project endpoint to the hostname of the remote machine, like the example below.
+
+  ```java
+  DatastoreOptions options = DatastoreOptions.builder()
+      .projectId(PROJECT_ID)
+      .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.
+
+### Testing code that uses Storage
+
+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. 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. Create a `RemoteGcsHelper` object using your project ID and JSON key.
+Here is an example that uses the `RemoteGcsHelper` to create a bucket.
+  ```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));
+  ```
+
+4. Run your tests.
+
+5. Clean up the test project by using `forceDelete` to clear any buckets used.
+Here is an example that clears the bucket created in Step 3 with a timeout of 5 seconds.
+  ```java
+  RemoteGcsHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
+  ```
+
+
+[cloud-platform-storage-authentication]:https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts

gcloud-java-core/README.md

@@ -1,16 +1,14 @@
-Google Cloud Java Client
-==========================
+Google Cloud Java Client -- Core
+=========================================
 
-Java idiomatic client for [Google Cloud Platform][cloud-platform] services.
+This module provides common functionality required by service-specific modules of this library.
 
 [![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
 [![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
+[![Maven](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-core.svg)](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-core.svg)
 
 -  [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
--  [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs)
--  [Examples] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/examples/package-summary.html)
-
-This module provides common functionality and is required by the other service specific modules.
+-  [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/package-summary.html)
 
 Quickstart
 ----------
@@ -19,22 +17,22 @@ Add this to your pom.xml file
 <dependency>
   <groupId>com.google.gcloud</groupId>
   <artifactId>gcloud-java-core</artifactId>
-  <version>0.0.7</version>
+  <version>0.0.10</version>
 </dependency>
 ```
 
+Java Versions
+-------------
+
+Java 7 or above is required for using this client.
+
 Contributing
 ------------
 
 Contributions to this library are always welcome and highly encouraged.
 
 See [CONTRIBUTING] for more information on how to get started.
 
-Java Versions
--------------
-
-Java 7 or above is required for using this client.
-
 Versioning
 ----------
 

gcloud-java-core/pom.xml

@@ -11,7 +11,7 @@
   <parent>
     <groupId>com.google.gcloud</groupId>
     <artifactId>gcloud-java-pom</artifactId>
-    <version>0.0.8-SNAPSHOT</version>
+    <version>0.0.11-SNAPSHOT</version>
   </parent>
   <dependencies>
     <dependency>
@@ -74,7 +74,7 @@
     <dependency>
       <groupId>joda-time</groupId>
       <artifactId>joda-time</artifactId>
-      <version>RELEASE</version>
+      <version>2.8.2</version>
       <scope>compile</scope>
     </dependency>
     <dependency>