diff --git a/.gitignore b/.gitignore index 3ca4b1fa5..2d6752757 100644 --- a/.gitignore +++ b/.gitignore @@ -25,8 +25,6 @@ nosetests.xml .DS_Store .classpath -# Built documentation -docs/ # Python utilities *.pyc diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 000000000..0c830d027 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,2 @@ +theme: jekyll-theme-dinky +title: Google HTTP Client for Java diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml new file mode 100644 index 000000000..4a92b7885 --- /dev/null +++ b/docs/_data/navigation.yml @@ -0,0 +1,23 @@ +toc: + - page: Overview + url: index.html + - page: Setup Instructions + url: setup.html + - page: Component Modules + url: component-modules.html + - page: Android + url: android.html + - page: Google App Engine + url: google-app-engine.html + - page: Batching + url: batching.html + - page: Media Download + url: media-download.html + - page: Media Upload + url: media-upload.html + - page: OAuth 2.0 + url: oauth-2.0.html + - page: Timeouts and Errors + url: errors.html + - page: Support + url: support.html \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 000000000..b3e7d30e6 --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,54 @@ + + + + + + +{% seo %} + + + + + + +
+
+

{{ site.title | default: site.github.repository_name }}

+ + {% for entry in site.data.navigation.toc %} + {{ entry.page }}
+ {% endfor %} +
+ + +
+ +
+ {{ content }} +
+ + +
+ + {% if site.google_analytics %} + + {% endif %} + + \ No newline at end of file diff --git a/docs/android.md b/docs/android.md new file mode 100644 index 000000000..f3b5ab5b6 --- /dev/null +++ b/docs/android.md @@ -0,0 +1,69 @@ +--- +title: Android +--- + +# Running on [Android (@Beta)](#@Beta) + +If you are developing for Android and the Google API you want to use is included +in the [Google Play Services library][play-services], use that library for the +best performance and experience. + +To access other Google APIs, use the Google Client Library for Java's +Android-specific helper classes, which are well-integrated with +[Android AccountManager][account-manager]. + +For example: + +```java +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + // Google Accounts + credential = + GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS)); + SharedPreferences settings = getPreferences(Context.MODE_PRIVATE); + credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null)); + // Tasks client + service = + new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential) + .setApplicationName("Google-TasksAndroidSample/1.0").build(); +} +``` + +## Getting started + +Begin by reading the [Android development instructions][http-client-android] for +the Google HTTP Client Library for Java. + +## Authentication + +As described in the [Android development instructions][http-client-android], the +best practice on Android is to use the [`AccountManager`][account-manager] class +(`@Beta`) for centralized identity management and credential token storage. + +For information about the OAuth 2.0 flow, see the +[OAuth 2.0 instructions for Android][oauth2-android]. + +## Partial response and update + +Google APIs support a partial-response protocol that allows you to specify which +fields are returned to you in the HTTP response. This can significantly reduce +the size of the response, thereby reducing network usage, parsing response time, +and memory usage. It works with both JSON and XML. + +The following snippet of code drawn from the Google+ Sample demonstrates how to +use the partial-response protocol: + + +```java +Plus.Activities.List listActivities = plus.activities().list("me", "public"); +listActivities.setMaxResults(5L); +// Pro tip: Use partial responses to improve response time considerably +listActivities.setFields("nextPageToken,items(id,URL,object/content)"); +ActivityFeed feed = listActivities.execute(); +``` + +[play-services]: https://developer.android.com/google/play-services/index.html +[account-manager]: http://developer.android.com/reference/android/accounts/AccountManager.html +[http-client-android]: https://github.com/googleapis/google-http-java-client/wiki/Android +[oauth2-android]: https://github.com/googleapis/google-api-java-client#oauth2-android diff --git a/docs/batching.md b/docs/batching.md new file mode 100644 index 000000000..52f943e8c --- /dev/null +++ b/docs/batching.md @@ -0,0 +1,43 @@ +--- +title: Batching +--- + +# Batching + +Each HTTP connection that your client makes results in overhead. To reduce +overhead, you can batch multiple API calls together into a single HTTP request. + +The main classes of interest are [BatchRequest][batch-request] and +[JsonBatchCallback][json-batch-callback]. The following example shows how to use +these classes with service-specific generated libraries: + +```java +JsonBatchCallback callback = new JsonBatchCallback() { + + public void onSuccess(Calendar calendar, HttpHeaders responseHeaders) { + printCalendar(calendar); + addedCalendarsUsingBatch.add(calendar); + } + + public void onFailure(GoogleJsonError e, HttpHeaders responseHeaders) { + System.out.println("Error Message: " + e.getMessage()); + } +}; + +... + +Calendar client = Calendar.builder(transport, jsonFactory, credential) + .setApplicationName("BatchExample/1.0").build(); +BatchRequest batch = client.batch(); + +Calendar entry1 = new Calendar().setSummary("Calendar for Testing 1"); +client.calendars().insert(entry1).queue(batch, callback); + +Calendar entry2 = new Calendar().setSummary("Calendar for Testing 2"); +client.calendars().insert(entry2).queue(batch, callback); + +batch.execute(); +``` + +[batch-request]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/batch/BatchRequest.html +[json-batch-callback]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/batch/json/JsonBatchCallback.html \ No newline at end of file diff --git a/docs/component-modules.md b/docs/component-modules.md new file mode 100644 index 000000000..264788217 --- /dev/null +++ b/docs/component-modules.md @@ -0,0 +1,64 @@ +--- +title: Component Modules +--- + +# Component Modules + +This libraries is composed of several modules: + +## google-api-client + +The Google API Client Library for Java (`google-api-client`) is designed to be +compatible with all supported Java platforms, including Android. + +## google-api-client-android + +Extensions to the Google API Client Library for Java +(`google-api-client-android`) support Java Google Android (only for SDK >= 2.1) +applications. This module depends on `google-api-client` and +`google-http-client-android`. + +## google-api-client-servlet + +Servlet and JDO extensions to the Google API Client Library for Java +(`google-api-client-servlet`) support Java servlet web applications. This module +depends on `google-api-client` and `google-oauth-client-servlet`. + +## google-api-client-appengine + +Google App Engine extensions to the Google API Client Library for Java +(`google-api-client-appengine`) support Java Google App Engine applications. +This module depends on `google-api-client`, `google-api-client-servlet`, +`google-oauth-client-appengine`, and `google-http-client-appengine`. + +## google-api-client-gson + +GSON extensions to the Google API Client Library for Java +(`google-api-client-gson`). This module depends on `google-api-client` and +`google-http-client-gson`. + +## google-api-client-jackson2 + +Jackson2 extensions to the Google API Client Library for Java +(`google-api-client-jackson2`). This module depends on `google-api-client` and +`google-http-client-jackson2`. + +## google-api-client-java6 + +Java 6 (and higher) extensions to the Google API Client Library for Java +(`google-api-client-java6`). This module depends on `google-api-client` and +`google-oauth-client-java6`. + +## google-api-client-protobuf + +[Protocol buffer][protobuf] extensions to the Google API Client Library for Java +(`google-api-client-protobuf`). This module depends on +`google-http-client-protobuf` and `google-api-client`. + +## google-api-client-xml + +XML extensions to the Google API Client Library for Java +(`google-api-client-xml`). This module depends on `google-api-client` and +`google-http-client-xml`. + +[protobuf]: https://developers.google.com/protocol-buffers/docs/overview diff --git a/docs/errors.md b/docs/errors.md new file mode 100644 index 000000000..3b43e83ab --- /dev/null +++ b/docs/errors.md @@ -0,0 +1,52 @@ +--- +title: Timeout and Errors +--- + +# Timeout and Errors + +## Setting timeouts + +In the following example, which uses the +[Google Analytics API][google-analytics-api], the `setConnectTimeout` and +`setReadTimeout` methods are used to set the connect and read timeouts to three +minutes (in milliseconds) for all requests: + +```java +private HttpRequestInitializer setHttpTimeout(final HttpRequestInitializer requestInitializer) { + return new HttpRequestInitializer() { + @Override + public void initialize(HttpRequest httpRequest) throws IOException { + requestInitializer.initialize(httpRequest); + httpRequest.setConnectTimeout(3 * 60000); // 3 minutes connect timeout + httpRequest.setReadTimeout(3 * 60000); // 3 minutes read timeout + } +}; + +GoogleCredential credential = .... + +final Analytics analytics = Analytics.builder(new NetHttpTransport(), jsonFactory, setHttpTimeout(credential)).build(); +``` + +## Handling HTTP error responses from Google APIs + +When an error status code is detected in an HTTP response to a Google API that +uses the JSON format, the generated libraries throw a +[`GoogleJsonResponseException`][google-json-response-exception]. + +The errors use the format specified in [Error responses][error-responses]. + +The following example shows one way that you can handle these exceptions: + +```java +Plus.Activities.List listActivities = plus.activities().list("me", "public"); +try { + ActivityFeed feed = listActivities.execute(); + ... +} catch (GoogleJsonResponseException e) { + System.err.println(e.getDetails()); +} +``` + +[google-analytics-api]: https://developers.google.com/analytics/ +[google-json-response-exception]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/json/GoogleJsonResponseException.html +[error-responses]: https://developers.google.com/url-shortener/v1/getting_started?csw=1#errors diff --git a/docs/google-app-engine.md b/docs/google-app-engine.md new file mode 100644 index 000000000..52a0a360d --- /dev/null +++ b/docs/google-app-engine.md @@ -0,0 +1,59 @@ +--- +title: Running on Google App Engine +--- + +# Running on Google App Engine + +App Engine-specific helpers make quick work of authenticated calls to APIs, and +you do not need to worry about exchanging code for tokens. + +For example: + +```java +@Override +protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { + AppIdentityCredential credential = + new AppIdentityCredential(Arrays.asList(UrlshortenerScopes.URLSHORTENER)); + Urlshortener shortener = + new Urlshortener.Builder(new UrlFetchTransport(), new JacksonFactory(), credential) + .build(); + UrlHistory history = shortener.URL().list().execute(); + ... +} +``` + +## Auth helpers + +If you are building a web app that interacts with a user's data via an OAuth +2.0-enabled API, we've created some helpers to assist you with the process. The +helpers aim to: + +* Simplify the process of obtaining access tokens + ([`AuthorizationCodeFlow`][authorization-code-flow]). +* Manage tokens, after they are obtained, by marking them as + [`PersistenceCapable`][persistence-capable]. +* Simplify the process of making authenticated calls using the access token's + [credential][credential]. +* Insulate you from the details of authentication when writing servlets. + +## Getting started + +1. Install the Google API Client Library for Java: + * Follow the [download instructions][setup] and put the library jar files + into your war/WEB-INF/lib directory. + * Alternatively, you can use [Maven][setup]. +1. Learn about using [OAuth 2.0 with the authorization code flow for Google App Engine applications][oauth2]. +1. Learn about using [OAuth 2.0 with the Google App Engine Identity API][oauth2-gae]. +1. Take a look at the [Calendar App Engine sample][calendar-sample]. This sample + combines our Java library and auth helpers to show you how to access end-user + data from within a Google App Engine web app. The sample also uses [GWT][gwt] + for the user interface. + +[authorization-code-flow]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html +[persistence-capable]: https://cloud.google.com/appengine/docs/java/datastore/ +[credential]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/Credential.html +[setup]: https://github.com/googleapis/google-api-java-client/wiki/Setup +[oauth2]: https://github.com/googleapis/google-api-java-client/wiki/OAuth2 +[oauth2-gae]: https://github.com/googleapis/google-api-java-client/wiki/OAuth2#gae +[calendar-sample]: https://github.com/google/google-api-java-client-samples/tree/master/calendar-appengine-sample +[gwt]: http://www.gwtproject.org/gle-http-java-client/http-transport.html \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..106bc5e4f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,77 @@ +--- +title: Overview +--- + +# Overview + +## Description + +The Google APIs Client Library for Java is a flexible, efficient, and powerful +Java client library for accessing any HTTP-based API on the web, not just Google +APIs. + +The library has the following features: + +- A powerful [OAuth 2.0][oauth2] library with a consistent interface. +- Lightweight, efficient XML and JSON data models that support any data schema. +- Support for [protocol buffers][protobuf]. +- A set of [generated libraries for Google APIs][service-clients]. + +The library supports the following Java environments: + +- Java 7 (or higher) +- Android 1.6 (or higher) +- [Google App Engine][app-engine] + +This library is built on top of two common libraries, also built by Google, and +also designed to work with any HTTP service on the web: + +- [Google HTTP Client Library for Java][http-client] +- [Google OAuth Client Library for Java][oauth-client] + +This is an open-source library, and [contributions][contributions] are welcome. + +## Accessing Google APIs + +To use Google's Java client libraries to call any Google API, you need two +libraries: + +- The core Google APIs Client Library for Java (`google-api-java-client`), which + is the generic runtime library described here. This library provides + functionality common to all APIs, for example HTTP transport, error handling, + authentication, JSON parsing, media download/upload, and batching. +- An auto-generated Java library for the API you are accessing, for example the + [generated Java library for the BigQuery API][bigquery]. These generated + libraries include API-specific information such as the root URL, and classes + that represent entities in the context of the API. These classes are useful + for making conversions between JSON objects and Java objects. + +To find the generated library for a Google API, visit +[Google APIs Client Library for Java][service-list]. +The API-specific Java packages include both the core google-api-java-client and +the client-specific libraries. + +## Beta Features + +Features marked with the `@Beta` annotation at the class or method level are +subject to change. They might be modified in any way, or even removed, in any +major release. You should not use beta features if your code is a library itself +(that is, if your code is used on the `CLASSPATH` of users outside your own +control). + +## Deprecated Features + +Deprecated non-beta features will be removed eighteen months after the release +in which they are first deprecated. You must fix your usages before this time. +If you don't, any type of breakage might result, and you are not guaranteed a +compilation error. + +[oauth2]: https://googleapis.github.io/google-api-java-client/oauth-2.0.html +[protobuf]: https://github.com/google/protobuf/ +[service-clients]: https://github.com/googleapis/google-api-java-client-services/ +[app-engine]: https://googleapis.github.io/google-api-java-client/google-app-engine.html +[http-client]: https://github.com/googleapis/google-http-java-client +[oauth-client]: https://github.com/googleapis/google-oauth-java-client +[contributions]: https://github.com/googleapis/google-api-java-client/wiki/CONTRIBUTING.md +[bigquery]: https://github.com/google/google-api-java-client-samples/tree/master/bigquery-appengine-sample/src/main/java/com/google/api/client/sample/bigquery/appengine/dashboard +[service-list]: https://github.com/googleapis/google-api-java-client-services#supported-google-apis diff --git a/docs/media-download.md b/docs/media-download.md new file mode 100644 index 000000000..088786828 --- /dev/null +++ b/docs/media-download.md @@ -0,0 +1,88 @@ +--- +title: Media Download +--- + +# Media Download + +## Resumable media downloads + +When you download a large media file from a server, use resumable media download +to download the file chunk by chunk. The Google API generated libraries contain +convenience methods for interacting with resumable media download, which was +introduced in the 1.9.0-beta version of the Google API Client Library for Java. + +The resumable media download protocol is similar to the resumable media upload +protocol, which is described in the +[Google Drive API documentation][google-drive-documentation]. + +### Implementation details + +The main classes of interest are [`MediaHttpDownloader`][media-http-downloader] +and [`MediaHttpDownloaderProgressListener`][media-http-downloader-progress-listener]. +Media content is downloaded in chunks, and chunk size is configurable. If a +server error is encountered in a request, then the request is retried. + +If methods in the service-specific generated libraries support download in the +Discovery document, then a convenient download method is created for these +methods that takes in an [`OutputStream`][output-stream]. (For more about using +media download with the Google APIs Discovery Service, see +[Media download][media-download].) + +For example: + +```java +class CustomProgressListener implements MediaHttpDownloaderProgressListener { + public void progressChanged(MediaHttpDownloader downloader) { + switch (downloader.getDownloadState()) { + case MEDIA_IN_PROGRESS: + System.out.println(downloader.getProgress()); + break; + case MEDIA_COMPLETE: + System.out.println("Download is complete!"); + } + } +} + +OutputStream out = new FileOutputStream("/tmp/driveFile.jpg"); + +DriveFiles.Get request = drive.files().get(fileId); +request.getMediaHttpDownloader().setProgressListener(new CustomProgressListener()); +request.executeMediaAndDownloadTo(out); +``` + +You can also use this feature without service-specific generated libraries. +Here is an example: + +```java +OutputStream out = new FileOutputStream("/tmp/Test.jpg"); + +MediaHttpDownloader downloader = new MediaHttpDownloader(transport, httpRequestInitializer); +downloader.setProgressListener(new CustomProgressListener()); +downloader.download(requestUrl, out); +``` + +## Direct media download + +Resumable media download is enabled by default, but you can disable it and use +direct media download instead, for example if you are downloading a small file. +Direct media download was introduced in the 1.9.0-beta version of the Google API +Client Library for Java. + +Direct media download downloads the whole media content in one HTTP request, as +opposed to the resumable media download protocol, which can download in multiple +requests. Doing a direct download reduces the number of HTTP requests but +increases the chance of failures (such as connection failures) that can happen +with large downloads. + +The usage is the same as what is described above, plus the following call that +tells [`MediaHttpDownloader`][media-http-downloader] to do direct downloads: + +```java +mediaHttpDownloader.setDirectDownloadEnabled(true); +``` + +[google-drive-documentation]: https://developers.google.com/drive/web/manage-uploads#resumable +[media-http-downloader]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpDownloader.html +[media-http-downloader-progress-listener]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpDownloaderProgressListener.html +[output-stream]: https://docs.oracle.com/javase/7/docs/api/java/io/OutputStream.html +[media-download]: https://developers.google.com/discovery/v1/using#discovery-doc-methods-mediadownload \ No newline at end of file diff --git a/docs/media-upload.md b/docs/media-upload.md new file mode 100644 index 000000000..8418ca160 --- /dev/null +++ b/docs/media-upload.md @@ -0,0 +1,112 @@ +--- +title: Media Upload +--- + +# Media Upload + +## Resumable media upload + +When you upload a large media file to a server, use resumable media upload to +send the file chunk by chunk. The Google API generated libraries contain +convenience methods for interacting with resumable media upload, which was +introduced in the 1.7.0-beta version of the Google API Client Library for Java. + +The resumable media upload protocol is similar to the resumable media upload +protocol described in the +[Google Drive API documentation][google-drive-documentation]. + +### Protocol design + +The following sequence diagram shows how the resumable media upload protocol +works: ![Resumable Media Upload Protocol Diagram][resumable-media-upload-protocol-diagram] + +### Implementation details + +The main classes of interest are [MediaHttpUploader][media-http-uploader] and +[MediaHttpProgressListener][media-http-progress-listener]. + +If methods in the service-specific generated libraries contain the `mediaUpload` +parameter in the Discovery document, then a convenience method is created for +these methods that takes an [InputStreamContent][input-stream-content] as a +parameter. (For more about using media upload with the Google APIs Discovery +Service, see [Media upload][media-upload].) + +For example, the `insert` method of the Drive API supports `mediaUpload`, and +you can use the following code to upload a file: + +```java +class CustomProgressListener implements MediaHttpUploaderProgressListener { + public void progressChanged(MediaHttpUploader uploader) throws IOException { + switch (uploader.getUploadState()) { + case INITIATION_STARTED: + System.out.println("Initiation has started!"); + break; + case INITIATION_COMPLETE: + System.out.println("Initiation is complete!"); + break; + case MEDIA_IN_PROGRESS: + System.out.println(uploader.getProgress()); + break; + case MEDIA_COMPLETE: + System.out.println("Upload is complete!"); + } + } +} + +File mediaFile = new File("/tmp/driveFile.jpg"); +InputStreamContent mediaContent = + new InputStreamContent("image/jpeg", + new BufferedInputStream(new FileInputStream(mediaFile))); +mediaContent.setLength(mediaFile.length()); + +Drive.Files.Insert request = drive.files().insert(fileMetadata, mediaContent); +request.getMediaHttpUploader().setProgressListener(new CustomProgressListener()); +request.execute(); +``` + +You can also use the resumable media upload feature without the service-specific +generated libraries. Here is an example: + +```java +File mediaFile = new File("/tmp/Test.jpg"); +InputStreamContent mediaContent = + new InputStreamContent("image/jpeg", + new BufferedInputStream(new FileInputStream(mediaFile))); +mediaContent.setLength(mediaFile.length()); + + +MediaHttpUploader uploader = new MediaHttpUploader(mediaContent, transport, httpRequestInitializer); +uploader.setProgressListener(new CustomProgressListener()); +HttpResponse response = uploader.upload(requestUrl); +if (!response.isSuccessStatusCode()) { + throw GoogleJsonResponseException(jsonFactory, response); +} +``` + +## Direct media upload + +Resumable media upload is enabled by default, but you can disable it and use +direct media upload instead, for example if you are uploading a small file. +Direct media upload was introduced in the 1.9.0-beta version of the Google API +Client Library for Java. + +Direct media upload uploads the whole file in one HTTP request, as opposed to +the resumable media upload protocol, which uploads the file in multiple +requests. Doing a direct upload reduces the number of HTTP requests but +increases the chance of failures (such as connection failures) that can happen +with large uploads. + +The usage for direct media upload is the same as what is described above for +resumable media upload, plus the following call that tells +[MediaHttpUploader][media-http-uploader] to only do direct uploads: + +```java +mediaHttpUploader.setDirectUploadEnabled(true); +``` + +[google-drive-documentation]: https://developers.google.com/drive/web/manage-uploads#resumable +[media-http-uploader]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpUploader.html +[media-http-progress-listener]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpUploaderProgressListener.html +[input-stream-content]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/http/InputStreamContent.html +[media-upload]: https://developers.google.com/discovery/v1/using#discovery-doc-methods-mediaupload +[resumable-media-upload-protocol-diagram]: https://github.com/googleapis/google-api-java-client/raw/master/Resumable-Media-Upload-Sequence-Diagram.png diff --git a/docs/oauth-2.0.md b/docs/oauth-2.0.md new file mode 100644 index 000000000..df8a044ee --- /dev/null +++ b/docs/oauth-2.0.md @@ -0,0 +1,582 @@ +--- +title: OAuth 2.0 +--- + +# Using OAuth 2.0 with the Google API Client Library for Java + +This document explains how to use the [`GoogleCredential`][google-credential] +utility class to do OAuth 2.0 authorization with Google services. For +information about the generic [OAuth 2.0 functions that we provide, see OAuth +2.0 and the Google OAuth Client Library for Java][google-oauth-client-instructions]. + +To access protected data stored on Google services, use [OAuth 2.0][oauth2] for +authorization. Google APIs support OAuth 2.0 flows for different types of client +applications. In all of these flows, the client application requests an access +token that is associated with only your client application and the owner of the +protected data being accessed. The access token is also associated with a +limited scope that defines the kind of data your client application has access +to (for example "Manage your tasks"). An important goal for OAuth 2.0 is to +provide secure and convenient access to the protected data, while minimizing the +potential impact if an access token is stolen. + +The OAuth 2.0 packages in the Google API Client Library for Java are built on +the general-purpose +[Google OAuth 2.0 Client Library for Java][google-oauth-client-instructions]. + +For details, see the Javadoc documentation for the following packages: + +* [`com.google.api.client.googleapis.auth.oauth2`][javadoc-oauth2] (from `google-api-client`) +* [`com.google.api.client.googleapis.extensions.appengine.auth.oauth2`][javadoc-appengine-oauth2] (from google-api-client-appengine) + +## Google API Console + +Before you can access Google APIs, you need to set up a project on the +[Google API Console][console] for auth and billing purposes, whether your client +is an installed application, a mobile application, a web server, or a client +that runs in browser. + +For instructions on setting up your credentials properly, see the +[API Console Help][console-help]. + +## Credential + +### GoogleCredential + +[`GoogleCredential`][google-credential] is a thread-safe helper class for OAuth +2.0 for accessing protected resources using an access token. For example, if you +already have an access token, you can make a request in the following way: + +```java +GoogleCredential credential = new GoogleCredential().setAccessToken(accessToken); +Plus plus = new Plus.builder(new NetHttpTransport(), + JacksonFactory.getDefaultInstance(), + credential) + .setApplicationName("Google-PlusSample/1.0") + .build(); +``` + +### Google App Engine identity + +This alternative credential is based on the +[Google App Engine App Identity Java API][identity-api]. Unlike the credential +in which a client application requests access to an end-user's data, the App +Identity API provides access to the client application's own data. + +Use [`AppIdentityCredential`][app-identity-credential] (from +`google-api-client-appengine`). This credential is much simpler because Google +App Engine takes care of all of the details. You only specify the OAuth 2.0 +scope you need. + +Example code taken from [urlshortener-robots-appengine-sample][urlshortener-sample]: + +```java +static Urlshortener newUrlshortener() { + AppIdentityCredential credential = + new AppIdentityCredential( + Collections.singletonList(UrlshortenerScopes.URLSHORTENER)); + return new Urlshortener.Builder(new UrlFetchTransport(), + JacksonFactory.getDefaultInstance(), + credential) + .build(); +} +``` + +## Data store + +An access token typically has an expiration date of 1 hour, after which you will +get an error if you try to use it. [GoogleCredential][google-credential] takes +care of automatically "refreshing" the token, which simply means getting a new +access token. This is done by means of a long-lived refresh token, which is +typically received along with the access token if you use the +`access_type=offline` parameter during the authorization code flow (see +[`GoogleAuthorizationCodeFlow.Builder.setAccessType(String)`][auth-code-flow-set-access-type]. + +Most applications will need to persist the credential's access token and/or +refresh token. To persist the credential's access and/or refresh tokens, you can +provide your own implementation of [`DataStoreFactory`][data-store-factory]) +with [`StoredCredential`][stored-credential]; or you can use one of the +following implementations provided by the library: + +* [`AppEngineDataStoreFactory`][appengine-data-store-factory]: persists the + credential using the Google App Engine Data Store API. +* [`MemoryDataStoreFactory`][memory-data-store-factory]: "persists" the + credential in memory, which is only useful as a short-term storage for the + lifetime of the process. +* [`FileDataStoreFactory`][file-data-store-factory]: persists the credential in + a file. + +### Google App Engine users + + +[`AppEngineCredentialStore`][appengine-credential-store] is deprecated and is being removed. + +We recommend that you use +[`AppEngineDataStoreFactory`][appengine-data-store-factory] with +[`StoredCredential`][stored-credential]. If you have credentials stored in the +old way, you can use the added helper methods +[`migrateTo(AppEngineDataStoreFactory)`][appengine-migrate] or +[`migrateTo(DataStore)`][datastore-migrate] to migrate. + +Use [`DataStoreCredentialRefreshListener`][datastore-credential-listener] and +set it for the credential using +[`GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener)`][add-refresh-listener]. + +## Authorization code flow + +Use the authorization code flow to allow the end user to grant your application +access to their protected data. The protocol for this flow is specified in the +[Authorization Code Grant specification][authorization-code-grant]. + +This flow is implemented using [`AuthorizationCodeFlow`][authorization-code-flow]. +The steps are: + +* An end user logs in to your application. You need to associate that user with + a user ID that is unique for your application. +* Call [`AuthorizationCodeFlow.loadCredential(String)`][auth-code-flow-load], + based on the user ID, to check if the user's credentials are already known. + If so, you're done. +* If not, call [`AuthorizationCodeFlow.newAuthorizationUrl()`][auth-code-flow-new] + and direct the end user's browser to an authorization page where they can grant + your application access to their protected data. +* The web browser then redirects to the redirect URL with a "code" query + parameter that can then be used to request an access token using + [`AuthorizationCodeFlow.newTokenRequest(String)`][token-request]. +* Use + [`AuthorizationCodeFlow.createAndStoreCredential(TokenResponse, String)`][create-and-store] + to store and obtain a credential for accessing protected resources. + +Alternatively, if you are not using +[`AuthorizationCodeFlow`][authorization-code-flow], you may use the lower-level +classes: + +* Use [`DataStore.get(String)`][datastore-get] to load the credential from the + store, based on the user ID. +* Use [`AuthorizationCodeRequestUrl`][auth-code-request-url] to direct the + browser to the authorization page. +* Use [`AuthorizationCodeResponseUrl`][auth-code-response-url] to process the + authorization response and parse the authorization code. +* Use [`AuthorizationCodeTokenRequest`][auth-code-token-request] to request an + access token and possibly a refresh token. +* Create a new [`Credential`][credential] and store it using + [`DataStore.set(String, V)`][datastore-set]. +* Access protected resources using the [`Credential`][credential]. Expired access + tokens are automatically refreshed using the refresh token, if applicable. + Make sure to use + [`DataStoreCredentialRefreshListener`][datastore-credential-listener] and set + it for the credential using + [`Credential.Builder.addRefreshListener(CredentialRefreshListener)`][add-refresh-listener]. + +### Web server applications + +The protocol for this flow is explained in +[Using OAuth 2.0 for Web Server Applications][oauth-web-server]. + +This library provides servlet helper classes to significantly simplify the +authorization code flow for basic use cases. You just provide concrete subclasses +of [`AbstractAuthorizationCodeServlet`][abstract-code-servlet] +and [`AbstractAuthorizationCodeCallbackServlet`][abstract-code-callback-servlet] +(from `google-oauth-client-servlet`) and add them to your `web.xml` file. Note +that you still need to take care of user login for your web application and +extract a user ID. + +```java +public class CalendarServletSample extends AbstractAuthorizationCodeServlet { + + @Override + protected void doGet(HttpServletRequest request, HttpServletResponse response) + throws IOException { + // do stuff + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + GenericUrl url = new GenericUrl(req.getRequestURL().toString()); + url.setRawPath("/oauth2callback"); + return url.build(); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return new GoogleAuthorizationCodeFlow.Builder( + new NetHttpTransport(), JacksonFactory.getDefaultInstance(), + "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]", + Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( + DATA_STORE_FACTORY).setAccessType("offline").build(); + } + + @Override + protected String getUserId(HttpServletRequest req) throws ServletException, IOException { + // return user ID + } +} + +public class CalendarServletCallbackSample extends AbstractAuthorizationCodeCallbackServlet { + + @Override + protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential) + throws ServletException, IOException { + resp.sendRedirect("/"); + } + + @Override + protected void onError( + HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse) + throws ServletException, IOException { + // handle error + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + GenericUrl url = new GenericUrl(req.getRequestURL().toString()); + url.setRawPath("/oauth2callback"); + return url.build(); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return new GoogleAuthorizationCodeFlow.Builder( + new NetHttpTransport(), JacksonFactory.getDefaultInstance() + "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]", + Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( + DATA_STORE_FACTORY).setAccessType("offline").build(); + } + + @Override + protected String getUserId(HttpServletRequest req) throws ServletException, IOException { + // return user ID + } +} +``` + +### Google App Engine applications + +The authorization code flow on App Engine is almost identical to the servlet +authorization code flow, except that we can leverage Google App Engine's +[Users Java API][users-api]. The user needs to be logged in for the Users Java +API to be enabled; for information about redirecting users to a login page if +they are not already logged in, see +[Security and Authentication][security-authentication] (in `web.xml`). + +The primary difference from the servlet case is that you provide concrete +subclasses of [`AbstractAppEngineAuthorizationCodeServlet`][abstract-gae-code-servlet] +and [`AbstractAppEngineAuthorizationCodeCallbackServlet`][abstract-gae-code-callback-servlet] +(from `google-oauth-client-appengine`). They extend the abstract servlet classes +and implement the `getUserId` method for you using the Users Java API. +[`AppEngineDataStoreFactory`][appengine-data-store-factory] (from +[Google HTTP Client Library for Java][google-http-client]) is a good option for +persisting the credential using the Google App Engine Data Store API. + +Example taken (slightly modified) from [calendar-appengine-sample][calendar-sample]: + +```java +public class CalendarAppEngineSample extends AbstractAppEngineAuthorizationCodeServlet { + + @Override + protected void doGet(HttpServletRequest request, HttpServletResponse response) + throws IOException { + // do stuff + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + return Utils.getRedirectUri(req); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return Utils.newFlow(); + } +} + +class Utils { + static String getRedirectUri(HttpServletRequest req) { + GenericUrl url = new GenericUrl(req.getRequestURL().toString()); + url.setRawPath("/oauth2callback"); + return url.build(); + } + + static GoogleAuthorizationCodeFlow newFlow() throws IOException { + return new GoogleAuthorizationCodeFlow.Builder(HTTP_TRANSPORT, JSON_FACTORY, + getClientCredential(), Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( + DATA_STORE_FACTORY).setAccessType("offline").build(); + } +} + +public class OAuth2Callback extends AbstractAppEngineAuthorizationCodeCallbackServlet { + + private static final long serialVersionUID = 1L; + + @Override + protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential) + throws ServletException, IOException { + resp.sendRedirect("/"); + } + + @Override + protected void onError( + HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse) + throws ServletException, IOException { + String nickname = UserServiceFactory.getUserService().getCurrentUser().getNickname(); + resp.getWriter().print("

" + nickname + ", why don't you want to play with me?

"); + resp.setStatus(200); + resp.addHeader("Content-Type", "text/html"); + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + return Utils.getRedirectUri(req); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return Utils.newFlow(); + } +} +``` + +For an additional sample, see +[storage-serviceaccount-appengine-sample][storage-sample]. + +### Service accounts + +[GoogleCredential][google-credential] also supports [service accounts][service-accounts]. +Unlike the credential in which a client application requests access to an +end-user's data, Service Accounts provide access to the client application's +own data. Your client application signs the request for an access token using +a private key downloaded from the [Google API Console][console]. + +Example code taken from [plus-serviceaccount-cmdline-sample][plus-sample]: + +```java +HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport(); +JsonFactory jsonFactory = JacksonFactory.getDefaultInstance(); +... +// Build service account credential. + +GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json")) + .createScoped(Collections.singleton(PlusScopes.PLUS_ME)); +// Set up global Plus instance. +plus = new Plus.Builder(httpTransport, jsonFactory, credential) + .setApplicationName(APPLICATION_NAME).build(); +... +``` + +For an additional sample, see [storage-serviceaccount-cmdline-sample][storage-sample]. + +**Note:** Although you can use service accounts in applications that run from a +Google Apps domain, service accounts are not members of your Google Apps account +and aren't subject to domain policies set by Google Apps administrators. For +example, a policy set in the Google Apps admin console to restrict the ability +of Apps end users to share documents outside of the domain would not apply to +service accounts. + +#### Impersonation + +You can also use the service account flow to impersonate a user in a domain that +you own. This is very similar to the service account flow above, but you +additionally call [`GoogleCredential.Builder.setServiceAccountUser(String)`][set-service-account-user]. + +### Installed applications + +This is the command-line authorization code flow described in [Using OAuth 2.0 for Installed Applications][oauth2-installed-app]. + +Example snippet from [plus-cmdline-sample][plus-sample]: + +```java +public static void main(String[] args) { + try { + httpTransport = GoogleNetHttpTransport.newTrustedTransport(); + dataStoreFactory = new FileDataStoreFactory(DATA_STORE_DIR); + // authorization + Credential credential = authorize(); + // set up global Plus instance + plus = new Plus.Builder(httpTransport, JSON_FACTORY, credential).setApplicationName( + APPLICATION_NAME).build(); + // ... +} + +private static Credential authorize() throws Exception { + // load client secrets + GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY, + new InputStreamReader(PlusSample.class.getResourceAsStream("/client_secrets.json"))); + // set up authorization code flow + GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder( + httpTransport, JSON_FACTORY, clientSecrets, + Collections.singleton(PlusScopes.PLUS_ME)).setDataStoreFactory( + dataStoreFactory).build(); + // authorize + return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user"); +} +``` + +### Client-side applications + +To use the browser-based client flow described in +[Using OAuth 2.0 for Client-side Applications][oauth2-user-agent], you would +typically follow these steps: + +1. Redirect the end user in the browser to the authorization page using + [`GoogleBrowserClientRequestUrl`][browser-client-request] to grant your + browser application access to the end user's protected data. +1. Use the [Google API Client Library for JavaScript][javascript-client] to + process the access token found in the URL fragment at the redirect URI + registered at the [Google API Console][console]. + +Sample usage for a web application: + +```java +public void doGet(HttpServletRequest request, HttpServletResponse response)throws IOException { + String url = new GoogleBrowserClientRequestUrl("812741506391.apps.googleusercontent.com", + "https://oauth2.example.com/oauthcallback", Arrays.asList( + "https://www.googleapis.com/auth/userinfo.email", + "https://www.googleapis.com/auth/userinfo.profile")).setState("/profile").build(); + response.sendRedirect(url); +} +``` + +### Android (@Beta) + +**Which library to use with Android:** + +If you are developing for Android and the Google API you want to use is included +in the [Google Play Services library][play-services], use that library for the +best performance and experience. If the Google API you want to use with Android +is not part of the Google Play Services library, you can use the Google API +Client Library for Java, which supports Android 4.0 (Ice Cream Sandwich) +(or higher), and which is described here. The support for Android in the Google +API Client Library for Java is `@Beta`. + +**Background:** + +Starting with Eclair (SDK 2.1), user accounts are managed on an Android device +using the Account Manager. All Android application authorization is centrally +managed by the SDK using [AccountManager][account-manager]. You specify the +OAuth 2.0 scope your application needs, and it returns an access token to use. + +The OAuth 2.0 scope is specified via the `authTokenType` parameter as `oauth2:` +plus the scope. For example: + +``` +oauth2:https://www.googleapis.com/auth/tasks +``` + +This specifies read/write access to the Google Tasks API. If you need multiple +OAuth 2.0 scopes, use a space-separated list. + +Some APIs have special `authTokenType` parameters that also work. For example, +"Manage your tasks" is an alias for the `authtokenType` example shown above. + +You must also specify the API key from the [Google API Console][console]. +Otherwise, the token that the AccountManager gives you only provides you with +anonymous quota, which is usually very low. By contrast, by specifying an API +key you receive a higher free quota, and can optionally set up billing for usage +above that. + +Example code snippet taken from [tasks-android-sample][tasks-sample]: + +```java +com.google.api.services.tasks.Tasks service; + +@Override +public void onCreate(Bundle savedInstanceState) { + credential = + GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS)); + SharedPreferences settings = getPreferences(Context.MODE_PRIVATE); + credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null)); + service = + new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential) + .setApplicationName("Google-TasksAndroidSample/1.0").build(); +} + +private void chooseAccount() { + startActivityForResult(credential.newChooseAccountIntent(), REQUEST_ACCOUNT_PICKER); +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + super.onActivityResult(requestCode, resultCode, data); + switch (requestCode) { + case REQUEST_GOOGLE_PLAY_SERVICES: + if (resultCode == Activity.RESULT_OK) { + haveGooglePlayServices(); + } else { + checkGooglePlayServicesAvailable(); + } + break; + case REQUEST_AUTHORIZATION: + if (resultCode == Activity.RESULT_OK) { + AsyncLoadTasks.run(this); + } else { + chooseAccount(); + } + break; + case REQUEST_ACCOUNT_PICKER: + if (resultCode == Activity.RESULT_OK && data != null && data.getExtras() != null) { + String accountName = data.getExtras().getString(AccountManager.KEY_ACCOUNT_NAME); + if (accountName != null) { + credential.setSelectedAccountName(accountName); + SharedPreferences settings = getPreferences(Context.MODE_PRIVATE); + SharedPreferences.Editor editor = settings.edit(); + editor.putString(PREF_ACCOUNT_NAME, accountName); + editor.commit(); + AsyncLoadTasks.run(this); + } + } + break; + } +} +``` + +[google-credential]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html +[google-oauth-client-instructions]: https://developers.google.com/api-client-library/java/google-oauth-java-client/oauth2 +[oauth2]: https://developers.google.com/accounts/docs/OAuth2 +[javadoc-oauth2]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/package-frame.html +[javadoc-appengine-oauth2]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/extensions/appengine/auth/oauth2/package-frame.html +[console]: https://console.developers.google.com/ +[console-help]: https://developer.google.com/console/help/console/ +[identity-api]: https://cloud.google.com/appengine/docs/java/appidentity/?csw=1#Asserting_Identity_to_Google_APIs +[app-identity-credential]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/extensions/appengine/auth/oauth2/AppIdentityCredential.html +[urlshortener-sample]: https://github.com/google/google-api-java-client-samples/tree/master/urlshortener-robots-appengine-sample +[auth-code-flow-set-access-type]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleAuthorizationCodeFlow.Builder.html#setAccessType-java.lang.String- +[data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/DataStoreFactory.html +[stored-credential]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/StoredCredential.html +[appengine-data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/extensions/appengine/datastore/AppEngineDataStoreFactory.html +[google-http-client]: https://github.com/googleapis/google-http-java-client +[memory-data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/MemoryDataStoreFactory.html +[file-data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/FileDataStoreFactory.html +[appengine-credential-store]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html +[appengine-migrate]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html#migrateTo-com.google.api.client.extensions.appengine.datastore.AppEngineDataStoreFactory- +[datastore-migrate]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html#migrateTo-com.google.api.client.util.store.DataStore- +[datastore-credential-listener]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/DataStoreCredentialRefreshListener.html +[add-refresh-listener]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.Builder.html#addRefreshListener-com.google.api.client.auth.oauth2.CredentialRefreshListener- +[authorization-code-grant]: https://tools.ietf.org/html/rfc6749#section-4.1 +[authorization-code-flow]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html +[auth-code-flow-load]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#loadCredential-java.lang.String- +[auth-code-flow-new]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#newAuthorizationUrl-- +[token-request]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#newTokenRequest-java.lang.String- +[create-and-store]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#createAndStoreCredential-com.google.api.client.auth.oauth2.TokenResponse-java.lang.String- +[datastore-get]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/DataStore.html#get-java.lang.String- +[auth-code-request-url]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeRequestUrl.html +[auth-code-response-url]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeResponseUrl.html +[auth-code-token-request]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeTokenRequest.html +[datastore-set]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/DataStore.html#set(java.lang.String,%20V) +[credential]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/Credential.html +[oauth2-web-server]: https://developers.google.com/accounts/docs/OAuth2WebServer +[abstract-code-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/servlet/auth/oauth2/AbstractAuthorizationCodeServlet.html +[abstract-code-callback-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/servlet/auth/oauth2/AbstractAuthorizationCodeCallbackServlet.html +[users-api]: https://cloud.google.com/appengine/docs/java/users/ +[security-authentication]: https://cloud.google.com/appengine/docs/java/config/webxml#Security_and_Authentication +[abstract-gae-code-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AbstractAppEngineAuthorizationCodeServlet.html +[abstract-gae-code-callback-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AbstractAppEngineAuthorizationCodeCallbackServlet.html +[calendar-sample]: https://github.com/google/google-api-java-client-samples/tree/master/calendar-appengine-sample +[storage-sample]: https://github.com/GoogleCloudPlatform/cloud-storage-docs-xml-api-examples +[service-accounts]: https://developers.google.com/accounts/docs/OAuth2ServiceAccount +[plus-sample]: https://github.com/google/google-api-java-client-samples/tree/master/plus-serviceaccount-cmdline-sample +[set-service-account-user]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.Builder.html#setServiceAccountUser-java.lang.String- +[oauth2-installed-app]: https://developers.google.com/accounts/docs/OAuth2InstalledApp +[oauth2-user-agent]: https://developers.google.com/accounts/docs/OAuth2UserAgent +[browser-client-request]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleBrowserClientRequestUrl.html +[javascript-client]: https://developers.google.com/api-client-library/javascript/ +[play-services]: https://developer.android.com/google/play-services/index.html +[account-manager]: http://developer.android.com/reference/android/accounts/AccountManager.html +[tasks-sample]: https://github.com/google/google-api-java-client-samples/tree/master/tasks-android-sample \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 000000000..d62852330 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,79 @@ +--- +title: Setup Instructions +--- + +# Setup Instructions + +You can download the Google API Client Library for Java and its dependencies in +a zip file, or you can use a dependency manager such as Maven or gradle to +install the necessary jars from the Maven Central repository. + +## Maven + +The Google API Client Library for Java is in the central Maven repository. The +Maven `groupId` for all artifacts for this library is `com.google.api-client`. + +To ensure all dependency versions work together and to avoid having to manually +choose and specify versions for each dependency, we recommend first importing +the `com.google.cloud:libraries-bom` in the `dependencyManagement` section of +your `pom.xml`: + +```xml + + + + com.google.cloud + libraries-bom + 2.2.0 + pom + import + + + +``` + +Then you add the individual dependencies you need without version numbers to the +dependencies section: + +```xml + + com.google.api-client + google-api-client + +``` + +On Android, you may need to explicitly exclude unused dependencies: + +```xml + + com.google.api-client + google-api-client + + + xpp3 + xpp3 + + + httpclient + org.apache.httpcomponents + + + junit + junit + + + android + com.google.android + + + +``` + +## Download the library with dependencies + +Download the latest assembly zip file from Maven Central and extract it on your +computer. This zip contains the client library class jar files and the +associated source jar files for each artifact and their dependencies. You can +find dependency graphs and licenses for the different libraries in the +dependencies folder. For more details about the contents of the download, +see the contained `readme.html` file. diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 000000000..e2806b871 --- /dev/null +++ b/docs/support.md @@ -0,0 +1,67 @@ +--- +title: Support +--- + +# Support + +## The Google API Client Library for Java community + +### Ask development questions + +Ask questions on StackOverflow: + +* When you ask questions about the Google API Client Library for Java, use the + [google-api-java-client][so-google-api-client] tag. Before you post a new + question, review the [most asked questions][so-maq]. +* For questions about Google APIs, use the [google-api][so-google-api] tag. +* Optionally include a tag to specify the language or platform, for example + [java][so-java], [android][so-android], or [google-app-engine][so-java-gae]. +* For tips on asking StackOverflow questions, see [How to Ask][so-how-to-ask]. + + + +### File feature requests and defects + +You can suggest features and report issues on our public [Issue Tracker][issues]. +This is a great place for the community to discuss and track implementations of +features or resolution of bug fixes, as well as share workarounds and patches. + +If you find a bug: + +* View [known bugs][bugs], and if a known bug corresponds to the issue you are + seeing, "star" it or comment on it. +* If the issue you are seeing has not yet been reported, + [file a bug report][new-issue]. + +If you have a feature request: + +* View [existing feature requests][feature-requests], and if a requested feature + corresponds to a feature you would like, "star" it or comment on it . +* If the feature has not yet been requested, + [file a feature request][new-issue]. + +### Contribute + +This is an [open-source][api-client] library, and [contributions][contributions] +are welcome. + +### Keep up with the library + +You can also take a look at the [release notes][releases]. + +[so-google-api-client]: http://stackoverflow.com/questions/tagged/google-api-java-client +[so-maq]: http://stackoverflow.com/questions/tagged/google-api-java-client?sort=faq&pagesize=50 +[so-google-api]: http://stackoverflow.com/questions/tagged/google-api +[so-java]: http://stackoverflow.com/questions/tagged/google-api-java-client+java +[so-android]: http://stackoverflow.com/questions/tagged/google-api-java-client+android +[so-java-gae]: http://stackoverflow.com/questions/tagged/google-api-java-client+java+google-app-engine +[so-how-to-ask]: http://stackoverflow.com/questions/ask +[issues]: https://github.com/googleapis/google-api-java-client/issues +[bugs]: https://github.com/googleapis/google-api-java-client/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+bug%22 +[feature-requests]: https://github.com/googleapis/google-api-java-client/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+feature+request%22 +[new-issue]: https://github.com/google/google-api-java-client/issues/new +[api-client]: https://github.com/googleapis/google-api-java-client +[contributions]: https://github.com/googleapis/google-api-java-client/blob/master/CONTRIBUTING.md +[releases]: https://github.com/googleapis/google-api-java-client/releases +