You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[`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
36
+
- 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).
37
+
-[`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
38
+
- 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).
39
+
40
+
Authentication
41
+
--------------
42
+
43
+
There are multiple ways to authenticate to use Google Cloud services.
44
+
45
+
1. When using `gcloud-java` libraries from within Compute/App Engine, no additional authentication steps are necessary.
46
+
2. When using `gcloud-java` libraries elsewhere, there are two options:
47
+
*[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.
48
+
* 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`.
43
49
44
50
Google Cloud Datastore
45
51
----------------------
46
52
47
-
Google [Cloud Datastore][cloud-datastore] is a fully managed, schemaless database for
48
-
storing non-relational data. Cloud Datastore automatically scales with
49
-
your users and supports ACID transactions, high availability of reads and
50
-
writes, strong consistency for reads and ancestor queries, and eventual
51
-
consistency for all other queries.
53
+
-[API Documentation][datastore-api]
54
+
-[Official Documentation][cloud-datastore-docs]
52
55
53
-
See the [Google Cloud Datastore docs][cloud-datastore-activation] for more details on how to activate
54
-
Cloud Datastore for your project.
56
+
*Follow the [activation instructions][cloud-datastore-activation] to use the Google Cloud Datastore API with your project.*
55
57
56
-
See the ``gcloud-java`` API [datastore documentation][datastore-api] to learn how to interact
57
-
with the Cloud Datastore using this Client Library.
58
+
#### Preview
59
+
60
+
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.
Contributions to this library are always welcome and highly encouraged.
94
+
-[API Documentation][storage-api]
95
+
-[Official Documentation][cloud-storage-docs]
93
96
94
-
See [CONTRIBUTING] for more information on how to get started.
97
+
*Follow the [activation instructions][cloud-storage-activation] to use the Google Cloud Storage API with your project.*
95
98
96
-
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.
99
+
#### Preview
100
+
101
+
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 7 or above is required for using this client.
102
136
137
+
Testing
138
+
-------
139
+
140
+
This library provides tools to help write tests for code that uses gcloud-java services.
141
+
142
+
See [TESTING] to read more about using our testing helpers.
143
+
103
144
Versioning
104
145
----------
105
146
@@ -109,6 +150,15 @@ It is currently in major version zero (``0.y.z``), which means that anything
109
150
may change at any time and the public API should not be considered
110
151
stable.
111
152
153
+
Contributing
154
+
------------
155
+
156
+
Contributions to this library are always welcome and highly encouraged.
157
+
158
+
See [CONTRIBUTING] for more information on how to get started.
159
+
160
+
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.
161
+
112
162
License
113
163
-------
114
164
@@ -118,6 +168,7 @@ Apache 2.0 - See [LICENSE] for more information.
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.
4
+
5
+
### To push a release version
6
+
7
+
1. Run `utilities/update_pom_version.sh` from the repository's base directory.
8
+
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.
9
+
10
+
2. Create a PR to update the pom.xml version.
11
+
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.
12
+
13
+
3. Create a release on Github manually.
14
+
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.
15
+
16
+
4. Run `utilities/update_pom_version.sh` again (to include "-SNAPSHOT" in the project version).
17
+
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`.
18
+
19
+
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).
20
+
21
+
### To push a snapshot version
22
+
23
+
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.
24
+
25
+
### Improvements
26
+
27
+
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.
This library provides tools to help write tests for code that uses gcloud-java services.
4
+
5
+
### Testing code that uses Datastore
6
+
7
+
#### On your machine
8
+
9
+
You can test against a temporary local datastore by following these steps:
10
+
11
+
1. Start the local datastore emulator using `LocalGcdHelper`. This can be done in two ways:
12
+
- 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.
13
+
- Call `LocalGcdHelper.start(<project ID>, <port number>)` before running your tests. Save the `LocalGcdHelper` object returned so that you can stop the emulator later.
14
+
15
+
2. In your program, create and use a datastore whose host is set host to `localhost:<port number>`. For example,
- 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.
27
+
- If you ran `LocalGcdHelper.start()` to start the emulator, call the `stop()` method on the `LocalGcdHelper` object returned by `LocalGcdHelper.start()`.
28
+
29
+
#### On a remote machine
30
+
31
+
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.
Note that the remote datastore must be running before your tests are run.
42
+
43
+
### Testing code that uses Storage
44
+
45
+
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:
46
+
47
+
1. Create a test Google Cloud project.
48
+
49
+
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].
50
+
51
+
3. Create a `RemoteGcsHelper` object using your project ID and JSON key.
52
+
Here is an example that uses the `RemoteGcsHelper` to create a bucket.
0 commit comments