From 316805cd2a3fcb6bdda01bccc3a6c275e190d957 Mon Sep 17 00:00:00 2001 From: Google Code Exporter Date: Sun, 15 Mar 2015 04:46:50 -0400 Subject: [PATCH] Migrating wiki contents from Google Code --- APIs.md | 437 +++++++++++++++++++++++++++++++++++ Android.md | 41 ++++ Batch.md | 48 ++++ BecomingAContributor.md | 296 ++++++++++++++++++++++++ ClientLogin.md | 43 ++++ DeveloperGuide.md | 36 +++ Downloads.md | 7 + GoogleAppEngine.md | 18 ++ HandlingTimeoutsAndErrors.md | 36 +++ MediaDownload.md | 56 +++++ MediaUpload.md | 80 +++++++ OAuth2.md | 401 ++++++++++++++++++++++++++++++++ ProjectHome.md | 170 ++++++++++++++ ReleaseNotes.md | 322 ++++++++++++++++++++++++++ Samples.md | 53 +++++ Setup.md | 264 +++++++++++++++++++++ Support.md | 48 ++++ TableOfContents.md | 17 ++ 18 files changed, 2373 insertions(+) create mode 100644 APIs.md create mode 100644 Android.md create mode 100644 Batch.md create mode 100644 BecomingAContributor.md create mode 100644 ClientLogin.md create mode 100644 DeveloperGuide.md create mode 100644 Downloads.md create mode 100644 GoogleAppEngine.md create mode 100644 HandlingTimeoutsAndErrors.md create mode 100644 MediaDownload.md create mode 100644 MediaUpload.md create mode 100644 OAuth2.md create mode 100644 ProjectHome.md create mode 100644 ReleaseNotes.md create mode 100644 Samples.md create mode 100644 Setup.md create mode 100644 Support.md create mode 100644 TableOfContents.md diff --git a/APIs.md b/APIs.md new file mode 100644 index 00000000..c480d215 --- /dev/null +++ b/APIs.md @@ -0,0 +1,437 @@ +**This content has moved to https://developers.google.com/api-client-library/java/apis/** + +| [Browse All Samples](http://code.google.com/p/google-api-java-client/source/browse?repo=samples) | [Request a New Sample](http://code.google.com/p/google-api-java-client/issues/entry?template=Request%20a%20Sample) | +|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Click on the Google API to download the client library and samples: + + + + +--- + +# ![http://www.google.com/images/icons/feature/filing_cabinet_search-g32.png](http://www.google.com/images/icons/feature/filing_cabinet_search-g32.png) APIs Discovery Service # +**Description:** Lets you discover information about other Google APIs, such as what APIs are available, the resource and method details for each API. + +This content has moved to https://developers.google.com/api-client-library/java/apis#APIs_Discovery_Service + + +--- + +# ![http://www.google.com/images/icons/product/doubleclick-32.gif](http://www.google.com/images/icons/product/doubleclick-32.gif) Ad Exchange Buyer API # +**Description:** Lets you manage your Ad Exchange Buyer account. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Ad_Exchange_Buyer_API + + +--- + +# ![http://www.google.com/images/icons/product/doubleclick-32.gif](http://www.google.com/images/icons/product/doubleclick-32.gif) Ad Exchange Seller API # +**Description:** Gives Ad Exchange seller users access to their inventory and the ability to generate reports + +This content has moved to https://developers.google.com/api-client-library/java/apis#Ad_Exchange_Seller_API + + +--- + +# ![http://www.google.com/images/icons/product/adsense-32.png](http://www.google.com/images/icons/product/adsense-32.png) AdSense Host API # +**Description:** Gives AdSense Hosts access to report generation, ad code generation, and publisher management capabilities. + +This content has moved to https://developers.google.com/api-client-library/java/apis#AdSense_Host_API + + +--- + +# ![http://www.google.com/images/icons/product/adsense-32.png](http://www.google.com/images/icons/product/adsense-32.png) AdSense Management API # +**Description:** Gives AdSense publishers access to their inventory and the ability to generate reports + +This content has moved to https://developers.google.com/api-client-library/java/apis#AdSense_Management_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Admin Reports API # +**Description:** Allows the administrators of Google Apps customers to fetch reports about the usage, collaboration, security and risk for their users. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Admin_Reports_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) BigQuery API # +**Description:** A data platform for customers to create, manage, share and query data. + +This content has moved to https://developers.google.com/api-client-library/java/apis#BigQuery_API + + +--- + +# ![http://www.google.com/images/icons/product/blogger-32.png](http://www.google.com/images/icons/product/blogger-32.png) Blogger API # +**Description:** API for access to the data within Blogger. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Blogger_API + + +--- + +# ![http://www.google.com/images/icons/product/ebooks-32.png](http://www.google.com/images/icons/product/ebooks-32.png) Books API # +**Description:** Lets you search for books and manage your Google Books library. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Books_API + + +--- + +# ![http://www.google.com/images/icons/product/calendar-32.png](http://www.google.com/images/icons/product/calendar-32.png) Calendar API # +**Description:** Lets you manipulate events and other calendar data. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Calendar_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Cloud SQL Administration API # +**Description:** API for Cloud SQL database instance management. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Cloud_SQL_Administration_API + + +--- + +# ![https://www.google.com/images/icons/product/cloud_storage-32.png](https://www.google.com/images/icons/product/cloud_storage-32.png) Cloud Storage API # +**Description:** Lets you store and retrieve potentially-large, immutable data objects. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Cloud_Storage_API + + +--- + +# ![http://www.google.com/images/icons/product/compute_engine-32.png](http://www.google.com/images/icons/product/compute_engine-32.png) Compute Engine API # +**Description:** API for the Google Compute Engine service. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Compute_Engine_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) CustomSearch API # +**Description:** Lets you search over a website or collection of websites + +This content has moved to https://developers.google.com/api-client-library/java/apis#CustomSearch_API + + +--- + +# ![http://www.google.com/images/icons/product/doubleclick-32.gif](http://www.google.com/images/icons/product/doubleclick-32.gif) DFA Reporting API # +**Description:** Lets you create, run and download reports. + +This content has moved to https://developers.google.com/api-client-library/java/apis#DFA_Reporting_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) DoubleClick Bid Manager API # +**Description:** API for viewing and managing your reports in DoubleClick Bid Manager. + +This content has moved to https://developers.google.com/api-client-library/java/apis#DoubleClick_Bid_Manager_API + + +--- + +# ![https://ssl.gstatic.com/docs/doclist/images/drive_icon_32.png](https://ssl.gstatic.com/docs/doclist/images/drive_icon_32.png) Drive API # +**Description:** The API to interact with Drive. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Drive_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Enterprise Apps Reseller API # +**Description:** Lets you create and manage your customers and their subscriptions. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Enterprise_Apps_Reseller_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Enterprise Audit API # +**Description:** Lets you access user activities in your enterprise made through various applications. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Enterprise_Audit_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Enterprise License Manager API # +**Description:** Licensing API to view and manage license for your domain. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Enterprise_License_Manager_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) External API For Ads DoubleClick Search # +**Description:** Let's you create and list campaigns, ad groups, and criterion in Ads DoubleClick Search. + +This content has moved to https://developers.google.com/api-client-library/java/apis#External_API_For_Ads_DoubleClick_Search + + +--- + +# ![http://www.google.com/images/icons/product/freebase-32.png](http://www.google.com/images/icons/product/freebase-32.png) Freebase API # +**Description:** Topic and MQL APIs provide you structured access to Freebase data. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Freebase_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Fusion Tables API # +**Description:** API for working with Fusion Tables data. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Fusion_Tables_API + + +--- + +# ![http://www.google.com/images/icons/product/affiliatenetwork-32.png](http://www.google.com/images/icons/product/affiliatenetwork-32.png) Google Affiliate Network API # +**Description:** Lets you have programmatic access to your Google Affiliate Network data. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Affiliate_Network_API + + +--- + +# ![http://www.google.com/images/icons/product/analytics-32.png](http://www.google.com/images/icons/product/analytics-32.png) Google Analytics API # +**Description:** View and manage your Google Analytics data + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Analytics_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google App State API # +**Description:** The Google App State API. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_App_State_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Civic Information API # +**Description:** An API for accessing civic information. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Civic_Information_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Cloud Datastore API # +**Description:** API for accessing Google Cloud Datastore. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Cloud_Datastore_API + + +--- + +# ![http://www.google.com/images/icons/feature/font_api-32.gif](http://www.google.com/images/icons/feature/font_api-32.gif) Google Fonts Developer API # +**Description:** The Google Fonts Developer API. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Fonts_Developer_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Identity Toolkit API # +**Description:** Help the third party sites to implement federated login. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Identity_Toolkit_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Maps Coordinate API # +**Description:** Lets you view and manage jobs in a Coordinate team. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Maps_Coordinate_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Mirror API # +**Description:** API for interacting with Glass users via the timeline. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Mirror_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google OAuth2 API # +**Description:** Lets you access OAuth2 protocol related APIs. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_OAuth2_API + + +--- + +# ![http://www.google.com/images/icons/product/android-32.png](http://www.google.com/images/icons/product/android-32.png) Google Play Android Developer API # +**Description:** Lets Android application developers access their Google Play accounts. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Play_Android_Developer_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Play Game Services API # +**Description:** The API for Google Play Game Services. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Play_Game_Services_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Play Game Services Management API # +**Description:** The Management API for Google Play Game Services. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Play_Game_Services_Management_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Google Site Verification API # +**Description:** Lets you programatically verify ownership of websites or domains with Google. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google_Site_Verification_API + + +--- + +# ![http://www.google.com/images/icons/product/gplus-32.png](http://www.google.com/images/icons/product/gplus-32.png) Google+ API # +**Description:** The Google+ API enables developers to build on top of the Google+ platform. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google+_API + + +--- + +# ![http://www.google.com/images/icons/product/gplus-32.png](http://www.google.com/images/icons/product/gplus-32.png) Google+ API # +**Description:** The Google+ API enables developers to build on top of the Google+ platform. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Google+_API + + +--- + +# ![http://www.google.com/images/icons/product/discussions-32.gif](http://www.google.com/images/icons/product/discussions-32.gif) Groups Migration API # +**Description:** Groups Migration Api. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Groups_Migration_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Groups Settings API # +**Description:** Lets you manage permission levels and related settings of a group. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Groups_Settings_API + + +--- + +# ![http://www.google.com/images/icons/product/orkut-32.png](http://www.google.com/images/icons/product/orkut-32.png) Orkut API # +**Description:** Lets you manage activities, comments and badges in Orkut. More stuff coming in time. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Orkut_API + + +--- + +# ![http://www.google.com/images/icons/product/pagespeed-32.png](http://www.google.com/images/icons/product/pagespeed-32.png) PageSpeed Insights API # +**Description:** Lets you analyze the performance of a web page and get tailored suggestions to make that page faster. + +This content has moved to https://developers.google.com/api-client-library/java/apis#PageSpeed_Insights_API + + +--- + +# ![http://www.google.com/images/icons/feature/predictionapi-32.png](http://www.google.com/images/icons/feature/predictionapi-32.png) Prediction API # +**Description:** Lets you access a cloud hosted machine learning service that makes it easy to build smart apps + +This content has moved to https://developers.google.com/api-client-library/java/apis#Prediction_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) Search API For Shopping # +**Description:** Lets you search over product data. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Search_API_For_Shopping + + +--- + +# ![http://www.google.com/images/icons/product/app_engine-32.png](http://www.google.com/images/icons/product/app_engine-32.png) TaskQueue API # +**Description:** Lets you access a Google App Engine Pull Task Queue over REST. + +This content has moved to https://developers.google.com/api-client-library/java/apis#TaskQueue_API + + +--- + +# ![http://www.google.com/images/icons/product/tasks-32.png](http://www.google.com/images/icons/product/tasks-32.png) Tasks API # +**Description:** Lets you manage your tasks and task lists. + +This content has moved to https://developers.google.com/api-client-library/java/apis#Tasks_API + + +--- + +# ![http://www.google.com/images/icons/product/translate-32.png](http://www.google.com/images/icons/product/translate-32.png) Translate API # +**Description:** Lets you translate text from one language to another + +This content has moved to https://developers.google.com/api-client-library/java/apis#Translate_API + + +--- + +# ![http://www.google.com/images/icons/product/search-32.gif](http://www.google.com/images/icons/product/search-32.gif) URL Shortener API # +**Description:** Lets you create, inspect, and manage goo.gl short URLs + +This content has moved to https://developers.google.com/api-client-library/java/apis#URL_Shortener_API + + +--- + +# ![http://www.google.com/images/icons/product/youtube-32.png](http://www.google.com/images/icons/product/youtube-32.png) YouTube Analytics API # +**Description:** Retrieve your YouTube Analytics reports. + +This content has moved to https://developers.google.com/api-client-library/java/apis#YouTube_Analytics_API + + +--- + +# ![http://www.google.com/images/icons/product/youtube-32.png](http://www.google.com/images/icons/product/youtube-32.png) YouTube Data API # +**Description:** Programmatic access to YouTube features. + +This content has moved to https://developers.google.com/api-client-library/java/apis#YouTube_Data_API + + + + +--- + + +# Google Data APIs # + +We do not provide service-specific libraries for the Google Data APIs because they are built on an older infrastructure that does not have a Discovery Service. Nevertheless, the base Google API Client Library for Java fully supports Google Data APIs as long as you write your own [Atom XML data model](http://javadoc.google-api-java-client.googlecode.com/hg/1.4.1-beta/com/google/api/client/googleapis/xml/atom/package-summary.html). Please take a look at the following examples for typical usage. + +We've written a few samples to demonstrate how this works: + * Content API for Shopping + * [Samples](http://code.google.com/apis/shopping/content/sample-apps/java/) (note that these samples are built on old version 1.1-alpha of the library and will not work with the latest version of the library) + * Google Cloud Storage API + * [storage-serviceaccount-cmdline-sample](http://samples.google-api-java-client.googlecode.com/hg/storage-serviceaccount-cmdline-sample/instructions.html?r=default) + * [storage-serviceaccount-appengine-sample](http://samples.google-api-java-client.googlecode.com/hg/storage-serviceaccount-appengine-sample/instructions.html?r=default) + * Picasa Web Albums Data API + * [picasa-cmdline-sample](http://samples.google-api-java-client.googlecode.com/hg/picasa-cmdline-sample/instructions.html?r=default) + * YouTube Data API + * [youtube-jsonc-sample](http://samples.google-api-java-client.googlecode.com/hg/youtube-jsonc-sample/instructions.html?r=default) \ No newline at end of file diff --git a/Android.md b/Android.md new file mode 100644 index 00000000..d87a0c0e --- /dev/null +++ b/Android.md @@ -0,0 +1,41 @@ +If you are developing for Android and the Google API you want to use is included in the [Google Play Services library](https://developer.android.com/google/play-services/index.html), 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 APIs Client Library for Java, which supports Android 1.5 (or higher), and which is described here. + +Contents: + + +# Getting Started # + +Begin by reading the [Android development instructions](http://code.google.com/p/google-http-java-client/wiki/Android) in the Google HTTP Client Library for Java documentation. + +# Authentication # + +As described in the [Android development instructions](http://code.google.com/p/google-http-java-client/wiki/Android), the best practice on Android (since the 2.1 SDK) is to use the [AccountManager](http://developer.android.com/reference/android/accounts/AccountManager.html) class (@Beta) for centralized identity management and credential token storage. + +**OAuth 2.0**
For information about the OAuth 2.0 flow, see the [OAuth 2.0 instructions for Android](OAuth2#Android.md). + +**ClientLogin**
ClientLogin is a [deprecated](https://developers.google.com/accounts/docs/AuthForInstalledApps?csw=1) authentication protocol used by older Google APIs. For new applications, we encourage you to use the more secure [OAuth 2.0](OAuth2.md) protocol. Support for ClientLogin in the Google APIs Client Library for Java will be removed. + +Older Google APIs that support ClientLogin are well supported on Android. To get an auth token, call `AccountManager.getAuthToken()` with the appropriate `authTokenType` for the Google API you are using, for example `cl` for the Google Calendar Data API. + +# 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](http://code.google.com/p/google-api-java-client/source/browse/plus-cmdline-sample/src/main/java/com/google/api/services/samples/plus/cmdline/PlusSample.java?repo=samples) demonstrates how to use the partial-response protocol: + +``` +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(); +``` + +# Samples # + +A good example that uses the generated service-specific library is [tasks-android-sample](http://samples.google-api-java-client.googlecode.com/hg/tasks-android-sample/instructions.html). Another example can be found in [calendar-android-sample](http://samples.google-api-java-client.googlecode.com/hg/calendar-android-sample/instructions.html?r=default), which mixes ClientLogin with the service-specific library. + +# Best-Practices Video (2011) # +In the following hour-long video from Google I/O 2011, Yaniv Inbar describes best practices for accessing Google APIs on Android. + + \ No newline at end of file diff --git a/Batch.md b/Batch.md new file mode 100644 index 00000000..65c7d900 --- /dev/null +++ b/Batch.md @@ -0,0 +1,48 @@ +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](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/batch/BatchRequest.html) and [JsonBatchCallback](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/batch/json/JsonBatchCallback.html). The following example shows how to use these classes with service-specific generated libraries: + +``` +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(); +``` + +A complete example of batch using the [Calendar API](https://developers.google.com/api-client-library/java/apis/calendar/v3) is available in the [calendar-cmdline-sample](http://samples.google-api-java-client.googlecode.com/hg/calendar-cmdline-sample/instructions.html). + +You can also use the batch feature without service-specific generated libraries. To do this: + 1. Change the batch URL to your own URL. + 1. Call [BatchRequest.setBatchUrl](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/batch/BatchRequest.html#setBatchUrl%28com.google.api.client.http.GenericUrl%29). + 1. Queue the HTTP requests by calling [BatchRequest.queue](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/batch/BatchRequest.html#queue%28com.google.api.client.http.HttpRequest,%20java.lang.Class,%20java.lang.Class,%20com.google.api.client.googleapis.batch.BatchCallback%29). + +The following example shows how to use batch in this generic way: + +``` + BatchRequest batch = new BatchRequest(httpTransport, httpRequestInitializer); + batch.setBatchUrl(new GenericUrl(/*your customized batch URL goes here*/)); + batch.queue(httpRequest1, dataClass, errorClass, callback); + batch.queue(httpRequest1, dataClass, errorClass, callback); + batch.execute(); +``` \ No newline at end of file diff --git a/BecomingAContributor.md b/BecomingAContributor.md new file mode 100644 index 00000000..eb660f9c --- /dev/null +++ b/BecomingAContributor.md @@ -0,0 +1,296 @@ +Contents: + + + +# Contributor License Agreements (CLA) # + +Before we can accept your code patches, you need to submit either an individual or a corporate Contributor License Agreement (CLA): + + * If you are an individual writing original source code and you're certain that you own the intellectual property, submit an [individual CLA](https://developers.google.com/open-source/cla/individual). + * If you work for a company, your company must submit a [corporate CLA](https://developers.google.com/open-source/cla/corporate) to indicate that you are allowed to contribute your work to this client library. + +Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we can add you to the official list of contributors. + +# Overview of Submitting Patches # + +To contribute code to this project, follow these general steps: + + 1. Sign a Contributor License Agreement, as described above. + 1. Join our [discussion group](http://groups.google.com/group/google-api-java-client). + 1. Set up your [development environment](BecomingAContributor#Setting_up_the_Development_Environment.md). + 1. Associate each of your changesets with an Issue (a bug report or feature request) in this project's [Issue Tracker](http://code.google.com/p/google-api-java-client/issues/list). Create a new Issue if there isn't one already, change its status to "Started," and assign it to yourself. + 1. Check out code, create a new issue on [codereview.appspot.com](http://codereview.appspot.com), and complete the code review process. Detailed instructions for all these processes are given below. + 1. After your code is reviewed and you receive approval, commit the code. If you are not an official Contributor, a Contributor pulls your changeset into the official repository. + +We use the following tools and processes: + * We use the [Mercurial](http://mercurial.selenic.com/) version control system, which is a "distributed" VCS. If you are not familiar with it, we recommend the tutorial by Joel Spolsky at [hginit.com](http://hginit.com/). + * We use [Maven](http://maven.apache.org/) for the build system, as well as a binary distribution system. + * We use [codereview.appspot.com](http://codereview.appspot.com) for code reviews. (But note that in the codereview.appspot.com tool, the term "issue" means a code-review request, while in the Issue Tracker, an "issue" is a feature request or bug report.) + +If you are an Eclipse developer, use the project-specific code formatting specified in the .settings directory that is automatically processed by Eclipse. + + +# Setting up the Development Environment # + +## Prerequisites ## + 1. Install [Java 6](http://java.com). You might need to set your `JAVA_HOME` variable. + 1. Install [Mercurial (Hg)](http://mercurial.selenic.com/), minimum version 1.6. An optional tutorial is located at [hginit.com](http://hginit.com). + 1. Install [Maven](http://maven.apache.org/download.html). (This document assumes you have basic familiarity with Maven commands.) + 1. Optional: Install the [Android SDK](http://developer.android.com/sdk/index.html) and set your ANDROID\_HOME variable to the install location for Android. + 1. Install [Git](http://git-scm.com/). + +**Set up the Mercurial hgrc file:** + +To be able to check out and make changes to the code, you need to authenticate with the Hg repository. + +Add the following in the `[auth]` section of your ~/.hgrc file with your username and password from https://code.google.com/hosting/settings, as follows: + +``` +[auth] +google-api-java-client.prefix = https://code.google.com/p/google-api-java-client/ +google-api-java-client.username = your_username +google-api-java-client.password = your_password +samples-google-api-java-client.prefix = https://code.google.com/p/google-api-java-client.samples/ +samples-google-api-java-client.username = your_username +samples-google-api-java-client.password = your_password +``` +## Checking out the code ## +We use two Mercurial repositories: + * The "default" repository has the library. The "default" branch has the latest unreleased code under development. Additionally, each release has its own branch, e.g. "1.6" branch for the 1.6.X-beta releases. + * The "samples" repository has all of the samples under the "default" branch. +To check out the default library repository in the development "default" branch, run the following command: + +``` +hg clone https://code.google.com/p/google-api-java-client/ google-api-java-client/default +``` + +To switch to an alternative branch (for example 1.12): + +``` +hg update 1.12 +``` + +To switch back to the development branch: + +``` +hg update default +``` + +To pull in the latest changes from the central server and update your local workspace to the latest changeset: + +``` +hg pull --update +``` + +To check out the "samples" repository: + +``` +cd +hg clone https://code.google.com/p/google-api-java-client.samples/ google-api-java-client/samples +``` + +## Maven ## + +**Install Google Play Services** + +The first time you set up the project, you need to install the google-play-services.jar file. To do this: + 1. Launch Eclipse and select **Window > Android SDK Manager**, or run `android` at the command line. + 1. Scroll to the bottom of the package list and select **Extras > Google Play services**. + +``` +mvn install:install-file \ + -Dfile=$ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar \ + -DgroupId=com.google.android.google-play-services \ + -DartifactId=google-play-services \ + -Dversion=1 \ + -Dpackaging=jar +``` + +**Compile the project** + +To clean, compile, test, and install the project, run the following command: + +``` +mvn clean install +``` + +Maven installs the compiled binaries to a local repository (for example ~/.m2/repository). It searches for binaries in that repository before fetching from the [Maven central repository](http://search.maven.org/#search%7Cga%7C1%7C). + +**Note:** +This library depends on [google-http-java-client](https://code.google.com/p/google-http-java-client/) and [google-oauth-java-client](https://code.google.com/p/google-oauth-java-client/). When working on a new version of all three libraries that are not yet released to Maven central, you must compile them in the following order: + 1. google-http-java-client + 1. google-oauth-java-client + 1. google-api-java-client +Compiling in this order ensures that Maven picks up the compiled binaries for dependent library compilation. + +## Eclipse ## +**Import to Eclipse:** + +The project is designed to work well with Eclipse. To convert the Maven project to an Eclipse project (that is, to create `.classpath`, `project.property` and so on), run the following command: + +``` +mvn eclipse:eclipse +``` +To import the project to an Eclipse workspace: + 1. From within Eclipse, select **File > Import...**. + 1. Select **General > Existing Project into Workspace** and click **Next**. + 1. Next to **Select root directory**, browse to the directory where your project is synced (for example google-api-java-client/default) and click **OK**. + 1. Click **Next** and **Finish**. + +**Add the `M2_REPO` classpath variable to Eclipse:** + +When you run `mvn eclipse:eclipse`, Maven creates the entire dependency classpath by using the `M2_REPO` variable, which is not defined in Eclipse by default. To add the `M2_REPO` classpath variable into the Eclipse IDE, follow these instructions: + + 1. From within Eclipse, select **Window > Preferences** (or on Mac, **Eclipse > Preferences...**). + 1. Select **Java > Build Path > Classpath Variables**. + 1. Click **New...**. + 1. Type `M2_REPO` as the name, and choose the local Maven repository, for example ~/.m2/repository. + 1. Click **OK**. Eclipse reminds you to rebuild all projects to work with the new classpath variable. + 1. Click **Done**. + +You only need to add `M2_REPO` once, and it is shared among all of your Eclipse workspaces. + +# Code Review Process # + +## Downloading the upload.py script ## + +Download the [upload.py](http://codereview.appspot.com/static/upload.py) script and optionally add it to your PATH. + +The first time you run `upload.py`, it asks you for an [application-specific password](http://support.google.com/accounts/bin/answer.py?hl=en&answer=185833): + +``` +Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com +Password for your_email_address@yourdomain.com: +``` + +## Preparing your code for review ## + +Before you send the code for review, you must run Clirr to catch backwards compatibility problems in your code. If any errors are reported, you need to either fix them or update the clirr-ignored-differences.xml file. + +``` +mvn -q clirr:check +``` + +You must also run the FindBugs tool to catch bugs in the code. If any errors are reported, you need to either fix them or update the findbugs-exclude.xml file. (Note that FindBugs is very slow.) + +``` +mvn findbugs:check +``` + +## Starting the code review ## + +When ready for review, create a new issue on codereview.appspot.com: +``` +upload.py --base_url=https://code.google.com/p/google-api-java-client/ --send_mail -r reviewer@somedomain --cc ... +``` + +After making more changes, upload a new patch, for example to issue number 123456: +``` +upload.py -i 123456 +``` + +For more options, run `upload.py --help`. + +The process is similar for samples: + +``` +upload.py --base_url=https://code.google.com/p/google-api-java-client.samples/ --send_mail -r reviewer@somedomain --cc ... +upload.py -i 123456 +``` + +## Code reviewer ## + +If you are a code reviewer, import and test changesets before you approve them, then remove the changes from your local workspace after you're done. + +**Get set up** + +Download the [hg\_import.py](http://google-http-java-client.googlecode.com/hg/hg_import.py) script and make an alias for easy use: +``` +alias hg_import.py='/hg_import.py' +``` + +**Import a changeset** + +To import a patch into your hg clone: + 1. Open the issue within codereview.appspot.com. + 1. For the patch in question, look for "Download raw" at the top right of the patch specification. + 1. Click "raw" to get a URL for the file to import. + +Now import the file. For example: +``` +hg_import.py http://codereview.appspot.com/download/issue123456_10000.diff +``` + +**Test the changeset** + +To run the tests and install, use the following command: + +``` +mvn clean install checkstyle:check +``` + +**Unpatch a changeset** + +When finishing a code review, use the following command to get rid of an imported patch. **Be careful**: It literally erases all of your local changes. +``` +hg revert -a && hg purge +``` + +**Approve a changeset on codereview.appspot.com** + +In general, code cannot be committed into the Hg server until the code reviewer is satisfied that the code is ready. At that point, the convention is to reply with the message "LGTM" (Looks Good To Me). + +## Committing the code ## + +**Important:** Before you commit your code, pull the latest changes into your local workspace and update your local workspace to the latest changeset: + +``` +hg pull --update +``` + +(If the central Mercurial server has changes that you have not yet pulled into your local workspace, committing your code creates a new branch or "head," because the "parent changeset" for your commit is the latest changeset in the server. The only way to resolve this is to merge the heads. To avoid this complexity, run `hg pull --update` as shown above.) + +To commit the code **locally**: +``` +hg commit +``` + +Enter a message such as the following (assuming you are fixing or implementing Issue # 123, as listed in this project's [Issue Tracker](https://code.google.com/p/google-api-java-client/issues/list)): + +``` +api Issue 123: NullPointerException when passing null to processFoo() + +http://codereview.appspot.com/123456/ +``` + +Before the first colon and the description: + + * Include the project, which is `api`, `http`, or `oauth`. + * If this is a fix to a problem on http://code.google.com/p/google-api-java-client/issues, include the Issue number, as shown. + * If this is a change for a particular branch, include the branch number. + +Following the description, always include a link to the issue on the codereview site. This link is important because without it, there's no convenient way to figure out the code review associated with a commit, which is useful for maintaining a history of the discussion. + +To push the change to the server: + +``` +hg push +``` + +If it asks for your password, use the password from https://code.google.com/hosting/settings. + +If during `hg push` you get an error message about creating a new head (perhaps you forgot to run `hg pull --update`), here's how to merge with the latest changes: +``` +hg pull +hg merge +hg commit +hg push +``` + +If you get an HTTP `403 Forbidden` status code, you are not on the list at https://code.google.com/p/google-api-java-client/people/list . Ask one of the Owners to add you to the list as a Committer. + +## Closing the issue ## + +Make sure to close the issue in the code-review tool. To do this: + 1. Select the issue in [codereview.appspot.com](http://codereview.appspot.com). + 1. Click the "X" that is at the top-left, preceding "Id." \ No newline at end of file diff --git a/ClientLogin.md b/ClientLogin.md new file mode 100644 index 00000000..e26a159f --- /dev/null +++ b/ClientLogin.md @@ -0,0 +1,43 @@ +# Legacy Support for ClientLogin # +ClientLogin is a [deprecated](https://developers.google.com/accounts/docs/AuthForInstalledApps?csw=1) authentication protocol used by older Google APIs, and support for it will be removed from the Google APIs Client Library for Java. + +**Do not use ClientLogin for new applications.** Instead, use the more secure [OAuth 2.0](OAuth2.md) authentication protocol. + +**If your existing application uses ClientLogin**, we encourage you to migrate to OAuth 2.0 as soon as possible. For information about how ClientLogin is implemented within the Google APIs Client Library for Java, see the [ClientLogin JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/clientlogin/package-summary.html) ([@Beta](https://code.google.com/p/google-api-java-client/#@Beta)). For general instructions, see [ClientLogin for Installed Applications](http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html). + +# Sample Program # +The following sample program shows ClientLogin used for authentication. You must manually fill in the username and password in order for this sample to work. Otherwise, you will likely get an HTTP `403 Forbidden` status code. + +Do not base new work on the sample; it is provided only for ClientLogin legacy support. + +``` +import com.google.api.client.googleapis.auth.clientlogin.ClientLogin; +import com.google.api.client.http.HttpResponseException; +import com.google.api.client.http.HttpTransport; +import com.google.api.client.http.javanet.NetHttpTransport; + +import java.io.IOException; +import java.lang.System; + +public class ClientLoginSample { + public static void main(String[] args) throws IOException { + // HttpTransport used to send login request. + HttpTransport transport = new NetHttpTransport(); + try { + // authenticate with ClientLogin + ClientLogin authenticator = new ClientLogin(); + authenticator.transport = transport; + // Google service trying to access, e.g., "cl" for calendar. + authenticator.authTokenType = "cl"; + authenticator.username = "username"; + authenticator.password = "password"; + authenticator.authenticate(); + System.out.println("Authentication succeeded."); + } catch (HttpResponseException e) { + // Likely a "403 Forbidden" error. + System.err.println(e.getStatusMessage()); + throw e; + } + } +} +``` \ No newline at end of file diff --git a/DeveloperGuide.md b/DeveloperGuide.md new file mode 100644 index 00000000..6c8613c3 --- /dev/null +++ b/DeveloperGuide.md @@ -0,0 +1,36 @@ +## Getting Started ## + +To get started with the Google APIs Client Library for Java, take a look at the [available samples](http://code.google.com/p/google-api-java-client/source/browse?repo=samples). + +For information about the structure of the library and its multiple components, see the [detailed setup instructions](Setup.md), which include [instructions for Maven users](Setup#Maven.md). + +To ask questions, report bugs, discuss the library, and read the announcements, see the [Support](Support.md) page. + +## Authentication ## + +The library supports the following authentication methods: + * [OAuth 2.0](OAuth2.md) + * [ClientLogin (deprecated Google method)](ClientLogin.md) + +## Batching ## + +The library makes it easier to batch multiple HTTP requests/responses. For details, see the [batch documentation](Batch.md). + +## Media Upload/Download ## + +The library has convenient classes that help with [media upload](MediaUpload.md) and [media download](MediaDownload.md). + +## Supported Java Environments ## +The library supports the following Java environments: + * Java 5 (or higher), standard (SE) and enterprise (EE) + * [Android 1.5 (or higher)](Android.md) (Note that this library's support for Android is [@Beta](https://code.google.com/p/google-api-java-client/#@Beta).) + * [Google App Engine](GoogleAppEngine.md) + + +## GData Java Client Library (deprecated) ## + +If you currently use the [GData Java client library](http://code.google.com/p/gdata-java-client/), you need to migrate to the Google APIs Client Library for Java. For details, see the [migration guide](http://code.google.com/p/gdata-java-client/wiki/MigratingToGoogleApiJavaClient). + +## Contribute ## + +This is an [open-source](http://code.google.com/p/google-api-java-client/source/browse/) library, and [contributions](BecomingAContributor.md) are welcome. \ No newline at end of file diff --git a/Downloads.md b/Downloads.md new file mode 100644 index 00000000..fc329736 --- /dev/null +++ b/Downloads.md @@ -0,0 +1,7 @@ +Starting from version 1.18.0-rc, we host library bundles (including both source and compiled files) on dl.google.com. The latest bundle is always named `google-api-java-client-featured.zip`. + +Google APIs Client Library for Java: +| Latest | [google-api-java-client-featured.zip](http://search.maven.org/remotecontent?filepath=com/google/api-client/google-api-client-assembly/1.18.0-rc/google-api-client-assembly-1.18.0-rc-1.18.0-rc.zip) | +|:-------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Archived | [Archived downloads](https://code.google.com/p/google-api-java-client/downloads/list) | +| Deprecated | [Deprecated downloads](https://code.google.com/p/google-api-java-client/downloads/list?can=4&q=&colspec=Filename+Summary+Uploaded+ReleaseDate+Size+DownloadCount) | \ No newline at end of file diff --git a/GoogleAppEngine.md b/GoogleAppEngine.md new file mode 100644 index 00000000..0a440b6d --- /dev/null +++ b/GoogleAppEngine.md @@ -0,0 +1,18 @@ +Google App Engine is one of the supported Java environments for the Google APIs Client Library for Java. + +# 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](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html)). + * Manage tokens, after they are obtained, by marking them as [PersistenceCapable](https://developers.google.com/appengine/docs/java/datastore/jdo/dataclasses#Class_and_Field_Annotations). + * Simplify the process of making authenticated calls using the access token's [credential](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/Credential.html). + * Insulate you from the details of authentication when writing [servlets](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/auth/oauth2/package-summary.html). + +# Getting Started # + + 1. Install the Google APIs Client Library for Java: + * Follow the [download instructions](Setup#Download_Library_with_Dependencies.md) and put the library .jar files into your war/WEB-INF/lib directory. + * Alternatively, you can use [Maven](Setup#Maven.md). + 1. Learn about [using OAuth 2.0 with the authorization code flow for Google App Engine applications](OAuth2#Google_App_Engine_applications.md). + 1. Learn about [using OAuth 2.0 with the Google App Engine Identity API](OAuth2#Google_App_Engine_identity.md). + 1. Take a look at the [Calendar App Engine sample](http://samples.google-api-java-client.googlecode.com/hg/calendar-appengine-sample/instructions.html). 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](http://www.gwtproject.org/) for the user interface. \ No newline at end of file diff --git a/HandlingTimeoutsAndErrors.md b/HandlingTimeoutsAndErrors.md new file mode 100644 index 00000000..3d2f702e --- /dev/null +++ b/HandlingTimeoutsAndErrors.md @@ -0,0 +1,36 @@ +# Setting Timeouts # + +In the following example, which uses the [Google Analytics API](https://developers.google.com/api-client-library/java/apis/analytics/v3), the `setConnectTimeout` and `setReadTimeout` methods are used to set the connect and read timeouts to three minutes (in milliseconds) for all requests: + +``` +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 # + +A [GoogleJsonResponseException](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/json/GoogleJsonResponseException.html) is thrown from the generated libraries when an error status code is detected in an HTTP response to a Google API that uses the JSON format. +The errors use the format specified in [Error responses](http://code.google.com/apis/urlshortener/v1/getting_started.html#errors). + +The following example shows a way to handle these exceptions: + +``` +Plus.Activities.List listActivities = plus.activities().list("me", "public"); +try { + ActivityFeed feed = listActivities.execute(); + ... +} catch (GoogleJsonResponseException e) { + System.err.println(e.getDetails()); +} +``` \ No newline at end of file diff --git a/MediaDownload.md b/MediaDownload.md new file mode 100644 index 00000000..1c98eee0 --- /dev/null +++ b/MediaDownload.md @@ -0,0 +1,56 @@ +Contents: + + +# Resumable Media Download # + +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](http://google-api-java-client.blogspot.com/2012/05/version-190-beta-released.html) version of the Google APIs 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](https://developers.google.com/drive/web/manage-uploads#resumable). + +# Implementation Details # +The main classes of interest are [MediaHttpDownloader](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/media/MediaHttpDownloader.html) and [MediaHttpDownloaderProgressListener](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/media/MediaHttpDownloaderProgressListener.html). 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](https://developers.google.com/discovery/v1/using), then a convenient download method is created for these methods that takes in an [OutputStream](http://docs.oracle.com/javase/1.5.0/docs/api/org/omg/CORBA/portable/OutputStream.html). (For more about using media download with the Google APIs Discovery Service, see [Media download](https://developers.google.com/discovery/v1/using#discovery-doc-methods-mediadownload).) + +For example: + +``` +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"); + +Drive.Files.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: +``` +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](http://google-api-java-client.blogspot.com/2012/05/version-190-beta-released.html) version of the Google APIs 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](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/media/MediaHttpDownloader.html) to do direct downloads: + +``` +mediaHttpDownloader.setDirectDownloadEnabled(true); +``` \ No newline at end of file diff --git a/MediaUpload.md b/MediaUpload.md new file mode 100644 index 00000000..f771a608 --- /dev/null +++ b/MediaUpload.md @@ -0,0 +1,80 @@ +Contents: + + +# 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](http://google-api-java-client.blogspot.com/2012/03/version-170-beta-released.html) version of the Google APIs Client Library for Java. + +The resumable media upload protocol is similar to the resumable media upload protocol described in the [Google Drive API documentation](https://developers.google.com/drive/web/manage-uploads#resumable). + +# Protocol Design # + +The following sequence diagram shows how the resumable media upload protocol works: +
+ + +# Implementation Details # + +The main classes of interest are [MediaHttpUploader](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/media/MediaHttpUploader.html) and [MediaHttpProgressListener](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/media/MediaHttpUploaderProgressListener.html). + +If methods in the service-specific generated libraries contain the `mediaUpload` parameter in the [Discovery document](https://developers.google.com/discovery/v1/using), then a convenience method is created for these methods that takes an [InputStreamContent](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/http/InputStreamContent.html) as a parameter. (For more about using media upload with the Google APIs Discovery Service, see [Media upload](https://developers.google.com/discovery/v1/using#discovery-doc-methods-mediaupload).) + +For example, the `insert` method of the [Drive API](https://www.googleapis.com/discovery/v1/apis/drive/v2.1beta/rest) supports `mediaUpload`, and you can use the following code to upload a file: + +``` +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: +``` +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](http://google-api-java-client.blogspot.com/2012/05/version-190-beta-released.html) version of the Google APIs 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](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/media/MediaHttpUploader.html) to only do direct uploads: + +``` +mediaHttpUploader.setDirectUploadEnabled(true); +``` \ No newline at end of file diff --git a/OAuth2.md b/OAuth2.md new file mode 100644 index 00000000..9701223d --- /dev/null +++ b/OAuth2.md @@ -0,0 +1,401 @@ +Contents: + + + +# Overview # + +**Purpose:** This document explains how to use the [GoogleCredential](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html) utility class to do OAuth 2.0 authorization with Google services. For information about the generic OAuth 2.0 functions that we provide, see the [Google OAuth Client Library for Java](https://code.google.com/p/google-oauth-java-client/wiki/OAuth2). + +**Summary:** To access protected data stored on Google services, use [OAuth 2.0](https://developers.google.com/accounts/docs/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 APIs Client Library for Java are built on the general-purpose [Google OAuth 2.0 Client Library for Java](http://code.google.com/p/google-oauth-java-client/wiki/OAuth2). + +For details, see the Javadoc documentation for the following packages: + * [com.google.api.client.googleapis.auth.oauth2](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/package-summary.html) (from [google-api-client](Setup#google-api-client.md)) + * [com.google.api.client.googleapis.extensions.appengine.auth.oauth2](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/extensions/appengine/auth/oauth2/package-summary.html) (from [google-api-client-appengine](Setup#google-api-client-appengine.md)) + +# Google Developers Console # + +Before you can access Google APIs, you need to set up a project on the [Google Developers Console](https://console.developers.google.com/) 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 [Google Developers Console Help](https://developers.google.com/console/help/new/). + + +# Credential # + +## GoogleCredential ## + +[GoogleCredential](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html) 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: + +``` +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](http://code.google.com/appengine/docs/java/appidentity/overview.html#Asserting_Identity_to_Google_APIs). 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](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/extensions/appengine/auth/oauth2/AppIdentityCredential.html) (from [google-api-client-appengine](Setup#google-api-client-appengine.md)). 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](http://samples.google-api-java-client.googlecode.com/hg/urlshortener-robots-appengine-sample/instructions.html): + +``` +static Urlshortener newUrlshortener() { + AppIdentityCredential credential = + new AppIdentityCredential(Arrays.asList(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](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html) 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)](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleAuthorizationCodeFlow.Builder.html#setAccessType(java.lang.String))). + +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](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/util/store/DataStoreFactory.html) and [DataStore](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/util/store/DataStore.html) with [StoredCredential](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/StoredCredential.html); or you can use one of the following implementations provided by the library: + * [JdoDataStoreFactory](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/jdo/JdoDataStoreFactory.html): persists the credential using JDO. + * [AppEngineDataStoreFactory](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/datastore/AppEngineDataStoreFactory.html): persists the credential using the Google App Engine Data Store API. + * [MemoryDataStoreFactory](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/util/store/MemoryDataStoreFactory.html) "persists" the credential in memory, which is only useful as a short-term storage for the lifetime of the process. + * [FileDataStoreFactory](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/util/store/FileDataStoreFactory.html): persists the credential in a file. + +**AppEngine Users:** +> [AppEngineCredentialStore](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html) is deprecated and will be removed soon. You are recommended to use [AppEngineDataStoreFactory](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/datastore/AppEngineDataStoreFactory.html) with [StoredCredential](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/StoredCredential.html). If you have credentials stored in the old fasion, you can use the added helper methods [migrateTo(AppEngineDataStoreFactory)](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html#migrateTo%28com.google.api.client.extensions.appengine.datastore.AppEngineDataStoreFactory%29) or [migrateTo(DataStore)](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html#migrateTo%28com.google.api.client.util.store.DataStore%29) to do the migration. + +You may use [DataStoreCredentialRefreshListener](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/DataStoreCredentialRefreshListener.html) and set it for the credential using [GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener)](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.Builder.html#addRefreshListener(com.google.api.client.auth.oauth2.CredentialRefreshListener)). + + + +# Authorization Code Flow # + +Use the authorization code flow to allow the end-user to grant your application access to their protected data on Google APIs. The protocol for this flow is specified in [Authorization Code Grant](http://tools.ietf.org/html/draft-ietf-oauth-v2-23#section-4.1). + +This flow is implemented using [GoogleAuthorizationCodeFlow](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleAuthorizationCodeFlow.html). The steps are: + * End-user logs in to your application. You will need to associate that user with a user ID that is unique for your application. + * Call [AuthorizationCodeFlow.loadCredential(String)](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#loadCredential(java.lang.String)) based on the user ID to check if the end-user's credentials are already known. If so, we're done. + * If not, call [AuthorizationCodeFlow.newAuthorizationUrl()](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#newAuthorizationUrl()) and direct the end-user's browser to an authorization page to grant your application access to their protected data. + * The Google authorization server will then redirect the browser back to the redirect URL specified by your application, along with a `code` query parameter. Use the `code` parameter to request an access token using [AuthorizationCodeFlow.newTokenRequest(String)](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#newTokenRequest(java.lang.String)). + * Use [AuthorizationCodeFlow.createAndStoreCredential(TokenResponse, String)](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#createAndStoreCredential(com.google.api.client.auth.oauth2.TokenResponse,%20java.lang.String)) to store and obtain a credential for accessing protected resources. + +Alternatively, if you are not using [GoogleAuthorizationCodeFlow](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleAuthorizationCodeFlow.html), you may use the lower-level classes: + + * Use [DataStore.get(String)](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/util/store/DataStore.html#get%28java.lang.String%29) to load the credential from the store based on the user ID. + * Use [GoogleAuthorizationCodeRequestUrl](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleAuthorizationCodeRequestUrl.html) to direct the browser to the authorization page. + * Use [AuthorizationCodeResponseUrl](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/AuthorizationCodeResponseUrl.html) to process the authorization response and parse the authorization code. + * Use [GoogleAuthorizationCodeTokenRequest](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleAuthorizationCodeTokenRequest.html) to request an access token and possibly a refresh token. + * Create a new [GoogleCredential](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html) and store it using [DataStore.set(String, V)](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/util/store/DataStore.html#set%28java.lang.String,%20V%29). + * Access protected resources using the [GoogleCredential](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html). Expired access tokens will automatically be refreshed using the refresh token (if applicable). Make sure to use [DataStoreCredentialRefreshListener](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/auth/oauth2/DataStoreCredentialRefreshListener.html) and set it for the credential using [GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener)](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.Builder.html#addRefreshListener(com.google.api.client.auth.oauth2.CredentialRefreshListener))]. + +When you set up your project in the [Google Developers Console](http://console.developers.google.com), you select among different credentials, depending on the flow you are using. For more details, see [Setting up OAuth 2.0](https://developers.google.com/console/help/new/#generatingoauth2) and [OAuth 2.0 Scenarios](https://developers.google.com/accounts/docs/OAuth2#scenarios). Below we provide code snippets for each of the flows. + +## Web server applications ## + +The protocol for this flow is explained in [Using OAuth 2.0 for Web Server Applications](https://developers.google.com/accounts/docs/OAuth2WebServer). + +This library provides servlet helper classes to significantly simplify the authorization code flow for basic use cases. You just provide concrete subclasses of [AbstractAuthorizationCodeServlet](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/servlet/auth/oauth2/AbstractAuthorizationCodeServlet.html) and [AbstractAuthorizationCodeCallbackServlet](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/servlet/auth/oauth2/AbstractAuthorizationCodeCallbackServlet.html) (from [google-oauth-client-servlet](http://code.google.com/p/google-oauth-java-client/wiki/Setup#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. [JdoDataStoreFactory](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/jdo/JdoDataStoreFactory.html) (from [google-oauth-client-servlet](http://code.google.com/p/google-oauth-java-client/wiki/Setup#google-oauth-client-servlet)) is a good option for persisting the credential using JDO. + +``` +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](http://code.google.com/appengine/docs/java/users/overview.html). 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](http://code.google.com/appengine/docs/java/config/webxml.html#Security_and_Authentication) (in web.xml). + +The primary difference from the servlet case is that you provide concrete subclasses of [AbstractAppEngineAuthorizationCodeServlet](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/auth/oauth2/AbstractAppEngineAuthorizationCodeServlet.html) and [AbstractAppEngineAuthorizationCodeCallbackServlet](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/auth/oauth2/AbstractAppEngineAuthorizationCodeCallbackServlet.html) (from [google-oauth-client-appengine](http://code.google.com/p/google-oauth-java-client/wiki/Setup#google-oauth-client-appengine)). They extend the abstract servlet classes and implement the `getUserId` method for you using the Users Java API. [AppEngineDataStoreFactory](http://javadoc.google-http-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/extensions/appengine/datastore/AppEngineDataStoreFactory.html) (from [google-http-client-appengine](http://code.google.com/p/google-http-java-client/wiki/Setup#google-http-client-appengine)) is a good option for persisting the credential using the Google App Engine Data Store API. + +Example taken (slightly modified) from [calendar-appengine-sample](http://samples.google-api-java-client.googlecode.com/hg/calendar-appengine-sample/instructions.html): + +``` +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(); + } +} +``` + +Please also see [storage-serviceaccount-appengine-sample](https://github.com/GoogleCloudPlatform/cloud-storage-docs-xml-api-examples) for an additional example. + +## Service accounts ## + +[GoogleCredential](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html) also supports [service accounts](https://developers.google.com/accounts/docs/OAuth2ServiceAccount). 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 Developers console](#Google_Developers_Console.md). + +Example code taken from [plus-serviceaccount-cmdline-sample](http://samples.google-api-java-client.googlecode.com/hg/plus-serviceaccount-cmdline-sample/instructions.html): + +``` +HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport(); +JsonFactory jsonFactory = JacksonFactory.getDefaultInstance(); +... +// Build service account credential. +GoogleCredential credential = new GoogleCredential.Builder().setTransport(httpTransport) + .setJsonFactory(jsonFactory) + .setServiceAccountId(SERVICE_ACCOUNT_EMAIL) + .setServiceAccountScopes(Collections.singleton(PlusScopes.PLUS_ME)) + .setServiceAccountPrivateKeyFromP12File(new File("key.p12")) + .build(); +// set up global Plus instance +plus = new Plus.Builder(httpTransport, jsonFactory, credential) + .setApplicationName(APPLICATION_NAME).build(); +... +``` + +Please also see [storage-serviceaccount-cmdline-sample](https://github.com/GoogleCloudPlatform/cloud-storage-docs-xml-api-examples) for an additional example. + +### 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.BuildersetServiceAccountUser(String)](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.Builder.html#setServiceAccountUser%28java.lang.String%29). + + +## Installed applications ## + +This is the command-line authorization code flow described in [Using OAuth 2.0 for Installed Applications](https://developers.google.com/accounts/docs/OAuth2InstalledApp). + +Example snippet from [plus-cmdline-sample](http://samples.google-api-java-client.googlecode.com/hg/plus-cmdline-sample/instructions.html) + +``` +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 ## + +These are the typical steps of the the browser-based client flow described in [Using OAuth 2.0 for Client-side Applications](https://developers.google.com/accounts/docs/OAuth2UserAgent): + + * Redirect the end user in the browser to the authorization page using [GoogleBrowserClientRequestUrl](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/com/google/api/client/googleapis/auth/oauth2/GoogleBrowserClientRequestUrl.html) to grant your browser application access to the end user's protected data. + * Use the [Google API Client Library for JavaScript](http://code.google.com/p/google-api-javascript-client/) to process the access token found in the URL fragment at the redirect URI registered at the [Google Developers Console](#Google_Developers_Console.md). + +Sample usage for a web application: + +``` +public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { + String url = new GoogleBrowserClientRequestUrl("812741506391.apps.googleusercontent.com", + "https://oauth2-login-demo.appspot.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](https://code.google.com/p/google-api-java-client/#@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](https://developer.android.com/google/play-services/index.html), 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 APIs Client Library for Java, which supports Android 1.5 (or higher), and which is described here. The support for Android in the Google APIs Client Library for Java is [@Beta](https://code.google.com/p/google-api-java-client/#@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](http://developer.android.com/reference/android/accounts/AccountManager.html). 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 Developers Console](#Google_Developers_Console.md). 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](http://samples.google-api-java-client.googlecode.com/hg/tasks-android-sample/instructions.html): + +``` +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; + } +} +``` \ No newline at end of file diff --git a/ProjectHome.md b/ProjectHome.md new file mode 100644 index 00000000..4ce80287 --- /dev/null +++ b/ProjectHome.md @@ -0,0 +1,170 @@ +| [Developer's Guide](DeveloperGuide.md) | [Libraries and Samples](https://developers.google.com/api-client-library/java/apis/) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/index.html) | [Get Help](Support.md) | +|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +# Google APIs Client Library for Java # + +This has moved to GitHub: https://github.com/google/google-api-java-client + +_Issues have been migrated to the [GitHub issue tracker](https://github.com/google/google-api-java-client/issues). If you own an open issue on this site, you can find a copy of it on GitHub. Please leave your comments over there._ + + * [Overview](#Overview.md) + * [Highlighted Features](#Highlighted_Features.md) + * [Dependencies](#Dependencies.md) + * [Important Warnings](#Important_Warnings.md) + * [@Beta](#@Beta.md) + * [Deprecations](#Deprecations.md) + +# Overview # + +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](http://code.google.com/p/google-api-java-client/wiki/OAuth2) library with a consistent interface. + * Lightweight, efficient XML and JSON data models that support any data schema. + * Support for [protocol buffers](https://code.google.com/p/protobuf/). + * A set of [generated libraries for Google APIs](https://developers.google.com/api-client-library/java/apis/). + +**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](https://code.google.com/p/google-api-java-client/source/browse/bigquery-appengine-sample/?repo=samples#bigquery-appengine-sample%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fapi%2Fclient%2Fsample%2Fbigquery%2Fappengine%2Fdashboard%253Fstate%253Dclosed). 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](https://developers.google.com/api-client-library/java/apis/). The API-specific Java packages include both the core google-api-java-client and the client-specific libraries. + +If you are using the old GData library, you need to [migrate](http://code.google.com/p/gdata-java-client/wiki/MigratingToGoogleApiJavaClient). + +**Developing for Android** + +If you are developing for Android and the Google API you want to use is included in the [Google Play Services library](https://developer.android.com/google/play-services/index.html), you should use that library for the best performance and experience. + +To access other Google APIs, you can use the Google APIs Client Library for Java, which supports [Android 1.5 (or higher)](Android.md). + +**Other Java environments** + +In addition to Android 1.5 or higher, the Google APIs Client Library for Java supports the following Java environments: + * Java 5 (or higher), standard (SE) and enterprise (EE) + * [Google App Engine](GoogleAppEngine.md) + +Not supported: Google Web Toolkit (GWT), Java mobile (ME), and Java 1.4 (or earlier). + +# Highlighted Features # +**The library makes it simple to call Google APIs.** + +> You can call Google APIs using Google service-specific generated libraries with the Google APIs Client Library for Java. Here's an example that makes a call to the [Google Calendar API](https://developers.google.com/google-apps/calendar/): + +``` + // Show events on user's calendar. + View.header("Show Calendars"); + CalendarList feed = client.calendarList().list().execute(); + View.display(feed); +``` + +**The library makes authentication easier.** + +> The authentication library can reduce the amount of code needed to handle [OAuth 2.0](OAuth2.md), and sometimes a few lines is all you need. For example: + +``` + /** Authorizes the installed application to access user's protected data. */ + private static Credential authorize() throws Exception { + // load client secrets + GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY, + new InputStreamReader(CalendarSample.class.getResourceAsStream("/client_secrets.json"))); + // set up authorization code flow + GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder( + httpTransport, JSON_FACTORY, clientSecrets, + Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory(dataStoreFactory) + .build(); + // authorize + return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user"); + } +``` +**The library makes batching and media upload/download easier.** + +> The library offers helper classes for [batching](Batch.md), [media upload](MediaUpload.md), and [media download](MediaDownload.md). + +**The library runs on Google App Engine.** + +> [App Engine-specific helpers](GoogleAppEngine.md) make quick work of authenticated calls to APIs, and you do not need to worry about exchanging code for tokens. For example: + +``` + @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(); + ... + } +``` + +**The library runs on [Android (@Beta)](#@Beta.md).** + +> If you are developing for Android and the Google API you want to use is included in the [Google Play Services library](https://developer.android.com/google/play-services/index.html), you should use that library for the best performance and experience. + +> To access other Google APIs, you can use the Google Client Library for Java's Android-specific helper classes, which are are well-integrated with [Android AccountManager](http://developer.android.com/reference/android/accounts/AccountManager.html). For example: + +``` + @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(); + } +``` + +**The library is easy to install.** + +> The Google APIs Client Library for Java is easy to install, and you can download the binary directly from the [Downloads page](Downloads.md), or you can use Maven or Gradle. +> To use Maven, add the following lines to your pom.xml file: + +``` + + + + com.google.api-client + google-api-client + 1.18.0-rc + + + +``` + +> To use Gradle, add the following lines to your build.gradle file: + +``` + repositories { + mavenCentral() + } + dependencies { + compile 'com.google.api-client:google-api-client:1.18.0-rc' + } +``` + +# Dependencies # +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://code.google.com/p/google-http-java-client/) + * [Google OAuth Client Library for Java](http://code.google.com/p/google-oauth-java-client/) + +# Important Warnings # + +## @Beta ## + +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). + +## Deprecations ## + +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. + + + \ No newline at end of file diff --git a/ReleaseNotes.md b/ReleaseNotes.md new file mode 100644 index 00000000..300b3f38 --- /dev/null +++ b/ReleaseNotes.md @@ -0,0 +1,322 @@ + + +# Version 1.18.0-rc # + +_April 10, 2014_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.18.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/jdiff/changes.html) | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +# Version 1.16.0-rc # + +_August 5, 2013_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.16.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.16.0-rc/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.16.0-rc/jdiff/changes.html) | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + + * [Updated to google-http-java-client version 1.16.0-rc](http://google-http-java-client.blogspot.com/2013/08/version-1160-rc-released.html) + * [Updated to google-oauth-java-client version 1.16.0-rc](http://google-oauth-java-client.blogspot.com/2013/08/version-1160-rc-released.html) + * [[Issue 783](https://code.google.com/p/google-api-java-client/issues/detail?id=783)] Created google-api-client-protobuf for the generated service-specific libraries based on the Protobuf format + * [[Issue 772](https://code.google.com/p/google-api-java-client/issues/detail?id=772)] Fixed a bug where MediaHttpUploader.serverErrorCallback() would not work if the data was partially or fully uploaded + * [[Issue 796](https://code.google.com/p/google-api-java-client/issues/detail?id=796)] Removed Beta API deprecated in 1.15 _(backwards incompatible change)_ + * [[Issue 530](https://code.google.com/p/google-api-java-client/issues/detail?id=530)] Added the App Engine test framework to google-api-client-appengine + + +# Version 1.15.0-rc # + +_May 10, 2013_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.15.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.15.0-rc/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.15.0-rc/jdiff/changes.html) | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Announcing the first release candidate of the Google API Java Client library! The library is finally going out of beta. + +Note that there are still some features of the library in active development that may require backwards incompatible changes in future releases before they are ready to fully go out of beta. Each of these features is annotated with a @Beta tag. + +In addition, the core and generated libraries have fully transitioned from our own Maven repository to the Central Maven Repository. +Users of older versions should remove the reference to our `` at `https://google-api-client-libraries.appspot.com/mavenrepo` in pom.xml, in order to fetch the latest version from the Central Repository. + +Highlights: + + * Updated to [google-http-java-client version 1.15.0-rc](http://google-http-java-client.blogspot.com/2013/05/version-1150-rc-released.html) + * Updated to [google-oauth-java-client version 1.15.0-rc](http://google-oauth-java-client.blogspot.com/2013/05/version-1150-rc-released.html) + * [[Issue 686](https://code.google.com/p/google-api-java-client/issues/detail?id=686)]: Marked specific parts of the library as Beta + * [[Issue 753](https://code.google.com/p/google-api-java-client/issues/detail?id=753)]: Removed deprecated API from 1.14 (backwards incompatible) + * [[Issue 745](https://code.google.com/p/google-api-java-client/issues/detail?id=745)]: Added Google Compute Engine service accounts + * [[Issue 755](https://code.google.com/p/google-api-java-client/issues/detail?id=755)]: Added ability to specify public certs URL for ID Token verification + * [[Issue 734](https://code.google.com/p/google-api-java-client/issues/detail?id=734)]: Allowed exponential backoff behavior to be customized via backoff handlers. + +# Version 1.14.1-beta # + +_Mar 25, 2013_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.14.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.14.1-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.14.1-beta/jdiff/changes.html) | +|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + + * Updated to [google-http-java-client version 1.14.1-beta](http://google-http-java-client.blogspot.com/2013/03/version-1141-beta-released.html) + * Updated to [google-oauth-java-client version 1.14.1-beta](http://google-oauth-java-client.blogspot.com/2013/03/version-1141-beta-released.html) + * [[Issue 685](http://code.google.com/p/google-api-java-client/issues/detail?id=685)]: Restrict trusted CAs to only those used by Google + * [[Issue 705](http://code.google.com/p/google-api-java-client/issues/detail?id=705)]: Updated to the latest OpenID Connect specification + * [[Issue 693](http://code.google.com/p/google-api-java-client/issues/detail?id=693)]: Now generate a BigInteger instead of UnsignedLong for uint64 _(backwards incompatible change)_ + * [[Issue 647](http://code.google.com/p/google-api-java-client/issues/detail?id=647)]: Added support for Google’s subscriptions protocol + * [[Issue 650](http://code.google.com/p/google-api-java-client/issues/detail?id=650)]: Removed some deprecated API from 1.13 _(backwards incompatible change)_ + * [[Issue 708](http://code.google.com/p/google-api-java-client/issues/detail?id=708)]: Now uses supportsMediaDownload flag from Discovery to determine if a method supports media download + * [[Issue 443](http://code.google.com/p/google-api-java-client/issues/detail?id=443)]: Fixed an issue where empty XScopes files were being generated + * [[Issue 437](http://code.google.com/p/google-api-java-client/issues/detail?id=437)]: Added methods to decode and encode base64 data to generated classes + * [[Issue 693](http://code.google.com/p/google-api-java-client/issues/detail?id=693)]: Generate a clone method in model classes + * [[Issue 466](http://code.google.com/p/google-api-java-client/issues/detail?id=466)] and [[Issue 692](http://code.google.com/p/google-api-java-client/issues/detail?id=692)]: Now throw an exception if a required schema parameter isn’t specified or required content is missing + * [[Issue 579](http://code.google.com/p/google-api-java-client/issues/detail?id=579)] and [[Issue 581](http://code.google.com/p/google-api-java-client/issues/detail?id=581)]: Fixed issues with resumable direct downloads and uploads + * [[Issue 697](http://code.google.com/p/google-api-java-client/issues/detail?id=697)]: Renamed dependencies files to match package names. + + +# Version 1.13.2-beta # + +_Jan 17, 2013_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.13.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.13.2-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.13.2-beta/jdiff/changes.html) | +|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + + * Updated to [google-http-java-client version 1.13.1-beta](http://google-http-java-client.blogspot.com/2013/01/version-1131-beta-released.html) + * Updated to [google-oauth-java-client version 1.13.1-beta](http://google-oauth-java-client.blogspot.com/2013/01/version-1131-beta-released.html) + * [[Issue 673](http://code.google.com/p/google-api-java-client/issues/detail?id=673)] Fixed: NullPointerException on error when doing resumable media upload + * [[Issue 663](http://code.google.com/p/google-api-java-client/issues/detail?id=663)] Fixed: range query request in MediaHttpUploader#serverErrorCallback fails with a 411 + * [[Issue 662](http://code.google.com/p/google-api-java-client/issues/detail?id=662)] MediaHttpUploader enforces that chunk sizes are multiples of 256KB + * [[Issue 660](http://code.google.com/p/google-api-java-client/issues/detail?id=660)] Deprecated GoogleHeaders in preference of HttpHeaders, and deprecated GoogleUrl in preference of GenericUrl (backwards incompatible change) + * [[Issue 653](http://code.google.com/p/google-api-java-client/issues/detail?id=653)] Change GET to POST if URI is too long + * [[Issue 649](http://code.google.com/p/google-api-java-client/issues/detail?id=649)] Support PEM file format as input format for service accounts + * [[Issue 641](http://code.google.com/p/google-api-java-client/issues/detail?id=641)] MediaHttpUploader: direct upload sets the request headers + * [[Issue 638](http://code.google.com/p/google-api-java-client/issues/detail?id=638)] MediaHttpUploader now respects AbstractGoogleClientRequest.setDisableGZipContent(true) + * [[Issue 634](http://code.google.com/p/google-api-java-client/issues/detail?id=634)] MediaHttpDownloader: added setContentRange + * [[Issue 591](http://code.google.com/p/google-api-java-client/issues/detail?id=591)] MediaHttpUploader.upload() requires a known InputStreamContent size + * AbstractGoogleClient now logs a warning if no application name has been set. + +# Version 1.12.0-beta # + +_Nov 8, 2012_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.12.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.12.0-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.12.0-beta/jdiff/changes.html) | +|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + + * Updated to [google-http-java-client version 1.12](http://google-http-java-client.blogspot.com/2012/11/version-1120-beta-released_2495.html). + * Updated to [google-oauth-java-client version 1.12](http://google-oauth-java-client.blogspot.com/2012/11/version-1120-beta-released.html). + * Google API libraries version skipped from 1.9 to 1.12 so we can match the version of the core google-api-java-client library and thus reduce confusion. + * Maven: repository URL of the Google API libraries has changed to http://google-api-client-libraries.appspot.com/mavenrepo + * Updated [calendar-android-sample](http://samples.google-api-java-client.googlecode.com/hg/calendar-android-sample/instructions.html) and [tasks-android-sample](http://samples.google-api-java-client.googlecode.com/hg/tasks-android-sample/instructions.html) to demonstrate best practice of using Google Play services for OAuth 2. + * [[Issue 629](http://code.google.com/p/google-api-java-client/issues/detail?id=629)] Fixed the 411 Length Required error in custom PUT methods. + * [[Issue 561](http://code.google.com/p/google-api-java-client/issues/detail?id=561)] Added [GoogleAccountCredential](http://javadoc.google-api-java-client.googlecode.com/hg/1.12.0-beta/com/google/api/client/googleapis/extensions/android/gms/auth/GoogleAccountCredential.html) for Android. + * [[Issue 55](http://code.google.com/p/google-oauth-java-client/issues/detail?id=55)] Fixed [FileCredentialStore](http://javadoc.google-oauth-java-client.googlecode.com/hg/1.12.0-beta/com/google/api/client/extensions/java6/auth/oauth2/FileCredentialStore.html) failure on Windows. + * [[Issue 601](http://code.google.com/p/google-api-java-client/issues/detail?id=601)] Service-specific Eclipse Android properties file has been added. + * [[Issue 642](http://code.google.com/p/google-api-java-client/issues/detail?id=642)] Fixed classpath entries in the generated libraries manifest. + * [[Issue 643](http://code.google.com/p/google-api-java-client/issues/detail?id=643)] Using wrong version of the core library now throws an Error. + * [[Issue 645](http://code.google.com/p/google-api-java-client/issues/detail?id=645)] setXYZRequestInitializer has been added to the generated libraries Builder. + * [[Issue 622](http://code.google.com/p/google-api-java-client/issues/detail?id=622)] Can now execute using HEAD. + * [[Issue 220](http://code.google.com/p/google-api-java-client/issues/detail?id=220)] Added support for non-json alt types. + +# Version 1.11.0-beta # + +_Sept 25, 2012_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.11.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [New Features in generated library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=Milestone%3DCodeGenVersion1.8.0+status%3DFixed&colspec=ID+Type+Priority+Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.11.0-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.11.0-beta/jdiff/changes.html) | +|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + + * [[Issue 574](http://code.google.com/p/google-api-java-client/issues/detail?id=574)] Removed deprecated classes/methods/fields from version 1.10. + * [[Issue 310](http://code.google.com/p/google-api-java-client/issues/detail?id=310)] Added command line auth helpers to google-api-java-client. + * [[Issue 594](http://code.google.com/p/google-api-java-client/issues/detail?id=594)] Renamed g-a-c-android2 to g-a-c-android. + * [[Issue 597](http://code.google.com/p/google-api-java-client/issues/detail?id=597)] Created properties files for Eclipse Android support. + * [[Issue 389](http://code.google.com/p/google-api-java-client/issues/detail?id=389)] Added support for UnsignedLong in service-specific libraries + * [[Issue 583](http://code.google.com/p/google-api-java-client/issues/detail?id=583)] DateTime is now used for “date” values in service-specific libraries + * [[Issue 525](http://code.google.com/p/google-api-java-client/issues/detail?id=525)] Added support for redirects in BatchRequest. + * [[Issue 560](http://code.google.com/p/google-api-java-client/issues/detail?id=560)] Batch now adds authorization to the top-level request. + * Updated to google-http-java-client version 1.11. + * Updated to google-oauth-java-client version 1.11. + +# Version 1.10.3-beta # + +_June 25, 2012_ + +| [Bugs Fixed](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone=Version1.10.3%20status=Fixed&colspec=ID%20Type%20Priority%20Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.10.3-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.10.3-beta/jdiff/changes.html) | +|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +[Bugs Fixed](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone=Version1.10.3%20status=Fixed&colspec=ID%20Type%20Priority%20Summary):
+Issue [527](http://code.google.com/p/google-api-java-client/issues/detail?id=527): Proguard does not strip out GoogleJsonError.ErrorInfo anymore.
+Issue [528](http://code.google.com/p/google-api-java-client/issues/detail?id=528): Proguard does not strip out model. anymore.
+Updated to google-http-java-client version 1.10.3-beta.
+Updated to google-oauth-java-client version 1.10.1-beta.
+ + +# Version 1.10.2-beta # + +_June 18, 2012_ + +| [Bugs Fixed](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone=Version1.10.2%20status=Fixed&colspec=ID%20Type%20Priority%20Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.10.2-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.10.2-beta/jdiff/changes.html) | +|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +[Bugs Fixed](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone=Version1.10.2%20status=Fixed&colspec=ID%20Type%20Priority%20Summary):
+Issue [521](http://code.google.com/p/google-api-java-client/issues/detail?id=521): Fixed resumable upload failure when writing multiple chunks.
+Issue [512](http://code.google.com/p/google-api-java-client/issues/detail?id=512): Added exponential backoff to Batch.
+ +# Version 1.10.1-beta # + +_June 14, 2012_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.10.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [New Features in generated library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=Milestone%3DCodeGenVersion1.7.0+status%3DFixed&colspec=ID+Type+Priority+Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.10.1-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.10.1-beta/jdiff/changes.html) | +|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + * [[Issue 516](http://code.google.com/p/google-api-java-client/issues/detail?id=516)] Changed accessType and approvalPrompt defaults in GoogleAuthorizationCodeFlow. + * [[Issue 402](http://code.google.com/p/google-api-java-client/issues/detail?id=402)] Fixed memory leaks. + * [[Issue 125](http://code.google.com/p/google-http-java-client/issues/detail?id=125)] Fixed issue of creating UrlFetchTransport in GAE SDK 1.6.6 in google-http-java-client. + * [[Issue 116](http://code.google.com/p/google-http-java-client/issues/detail?id=116)] Fixed CloseGuard error after EOFException in google-http-java-client. + * [[Issue 78](http://code.google.com/p/google-http-java-client/issues/detail?id=78)] Fixed memory leaks in google-http-java-client. + * [[Issue 118](http://code.google.com/p/google-http-java-client/issues/detail?id=118)] UriTemplate.expand now supports Iterable for list parameters in google-http-java-client. + * [[Issue 514](http://code.google.com/p/google-api-java-client/issues/detail?id=514)] Added HttpRequestInitializer to constructor and Builder of generated service-specific libraries. + * [[Issue 511](http://code.google.com/p/google-api-java-client/issues/detail?id=511)] Moved enableGZipContent to JsonHttpRequest and removed builder() methods. + * [[Issue 500](http://code.google.com/p/google-api-java-client/issues/detail?id=500)] Updated GoogleClient to use rootUrl and servicePath. + * Improvements to the surface of the service-specific generated libraries: + * [[Issue 505](http://code.google.com/p/google-api-java-client/issues/detail?id=505)] New structure for jars in zip package of generated libraries. + * [[Issue 483](http://code.google.com/p/google-api-java-client/issues/detail?id=483)] setFields are now overridden. + * [[Issue 387](http://code.google.com/p/google-api-java-client/issues/detail?id=387)] Created an isX() method for boolean parameters. + * [[Issue 515](http://code.google.com/p/google-api-java-client/issues/detail?id=515)] Generated service-specific libraries now use rootUrl rather than baseUrl. + * [[Issue 518](http://code.google.com/p/google-api-java-client/issues/detail?id=518)] Added Maven archtype catalog. + * Updated to google-http-java-client version 1.10. + * Updated to google-oauth-java-client version 1.10. + +# Version 1.9.0-beta # + +_May 18, 2012_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.9.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [New Features in generated library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=Milestone%3DCodeGenVersion1.6.0+status%3DFixed&colspec=ID+Type+Priority+Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.9.0-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.9.0-beta/jdiff/changes.html) | +|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + * [[Issue 308](http://code.google.com/p/google-api-java-client/issues/detail?id=308)] Added support for [Batch](http://code.google.com/p/google-api-java-client/wiki/Batch). + * [[Issue 448](http://code.google.com/p/google-api-java-client/issues/detail?id=448)] Added support for [Resumable Media Download](http://code.google.com/p/google-api-java-client/wiki/MediaDownload#Resumable_Media_Download). + * [[Issue 391](http://code.google.com/p/google-api-java-client/issues/detail?id=391)] Added support for [Direct Media Upload](http://code.google.com/p/google-api-java-client/wiki/MediaUpload#Direct_Media_Upload). + * [[Issue 459](http://code.google.com/p/google-api-java-client/issues/detail?id=459)] [GoogleIdTokenVerifier](http://javadoc.google-api-java-client.googlecode.com/hg/1.9.0-beta/com/google/api/client/googleapis/auth/oauth2/GoogleIdTokenVerifier.html) now has support for specifying multiple client ids. + * [[Issue 452](http://code.google.com/p/google-api-java-client/issues/detail?id=452)] Handled connection errors in [MediaHttpUploader](http://javadoc.google-api-java-client.googlecode.com/hg/1.9.0-beta/com/google/api/client/googleapis/media/MediaHttpUploader.html). + * [[Issue 473](http://code.google.com/p/google-api-java-client/issues/detail?id=473)] [MediaHttpUploader](http://javadoc.google-api-java-client.googlecode.com/hg/1.9.0-beta/com/google/api/client/googleapis/media/MediaHttpUploader.html) now handles input streams that do not support mark(). + * Improvements to the surface of the service-specific generated libraries: + * [[Issue 215](http://code.google.com/p/google-api-java-client/issues/detail?id=215)] Added support for specifying HTTP headers on a request. + * [[Issue 346](http://code.google.com/p/google-api-java-client/issues/detail?id=346)] Handled case where default value for alt parameter is not json. + * [[Issue 489](http://code.google.com/p/google-api-java-client/issues/detail?id=489)] Fixed compilation error when method names are the same name as the collection. + * [[Issue 490](http://code.google.com/p/google-api-java-client/issues/detail?id=490)] Fixed compilation error when deeply nested classes have the same name as one of its ancestors. + * [[Issue 480](http://code.google.com/p/google-api-java-client/issues/detail?id=480)] Removed xpp3 as a dependency for Android. + * [[Issue 461](http://code.google.com/p/google-api-java-client/issues/detail?id=461)] Generalized dependency instructions for non-Android. + * [[Issue 487](http://code.google.com/p/google-api-java-client/issues/detail?id=487)] Created new structure for jars in the zip package. + * [[Issue 471](http://code.google.com/p/google-api-java-client/issues/detail?id=471)] Removed deprecated classes/methods/fields from version 1.8. + * Updated to [google-http-java-client version 1.9](http://google-http-java-client.blogspot.com/2012/05/version-190-beta-released.html). + * Updated to [google-oauth-java-client version 1.9](http://google-oauth-java-client.blogspot.com/2012/05/version-190-beta-released.html). + +# Version 1.8.0-beta # + +_April 4, 2012_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.8.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [New Features in generated library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=Milestone%3DCodeGenVersion1.5.0+status%3DFixed&colspec=ID+Type+Priority+Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.8.0-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.8.0-beta/jdiff/changes.html) | +|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + * Improvements to the surface of the service-specific generated libraries: + * [[Issue 434](http://code.google.com/p/google-api-java-client/issues/detail?id=434)] Added support for direct media download. + * [[Issue 444](http://code.google.com/p/google-api-java-client/issues/detail?id=444)] Resumable media upload now uses the base URL set through builder.setBaseUrl. + * [[Issue 436](http://code.google.com/p/google-api-java-client/issues/detail?id=436)] [GoogleKeyInitializer](http://javadoc.google-api-java-client.googlecode.com/hg/1.8.0-beta/com/google/api/client/googleapis/services/GoogleKeyInitializer.html) has been added. + * [[Issue 440](http://code.google.com/p/google-api-java-client/issues/detail?id=440)] [GoogleJsonResponseException](http://javadoc.google-api-java-client.googlecode.com/hg/1.8.0-beta/com/google/api/client/googleapis/json/GoogleJsonResponseException.html) no longer throws an NPE when the response has no content. + * [[Issue 430](http://code.google.com/p/google-api-java-client/issues/detail?id=430)] [GoogleIdTokenVerifier](http://javadoc.google-api-java-client.googlecode.com/hg/1.8.0-beta/com/google/api/client/googleapis/auth/oauth2/GoogleIdTokenVerifier.html) now supports arbitary client\_ids. + * [[Issue 431](http://code.google.com/p/google-api-java-client/issues/detail?id=431)] [AppIdentityCredential.intercept](http://javadoc.google-api-java-client.googlecode.com/hg/1.8.0-beta/com/google/api/client/googleapis/extensions/appengine/auth/oauth2/AppIdentityCredential.html#intercept(com.google.api.client.http.HttpRequest)) now throws IOException on AppIdentityServiceFailureException. + * [[Issue 145](http://code.google.com/p/google-api-java-client/issues/detail?id=145)] Constructors that take required parameters for compile-time checking. + * [[Issue 432](http://code.google.com/p/google-api-java-client/issues/detail?id=432)] Some deprecated classes/methods/fields from version 1.7 have been removed. + * Updated to [google-http-java-client version 1.8](http://google-http-java-client.blogspot.com/2012/04/version-183-beta-released.html). + * Updated to [google-oauth-java-client version 1.8](http://google-oauth-java-client.blogspot.com/2012/04/version-180-beta-released.html). + +# Version 1.7.0-beta # + +_Mar 12, 2012_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.7.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [New Features in generated library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=Milestone%3DCodeGenVersion1.4.0+status%3DFixed&colspec=ID+Type+Priority+Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.7.0-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.7.0-beta/jdiff/changes.html) | +|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + * [[Issue 2](http://code.google.com/p/google-api-java-client/issues/detail?id=2)] Resumable media upload is now supported. + * [[Issue 365](http://code.google.com/p/google-api-java-client/issues/detail?id=365)] Updated to the latest [OAuth 2.0](http://code.google.com/p/google-api-java-client/wiki/OAuth2) (draft 23). + * [[Issue 338](http://code.google.com/p/google-api-java-client/issues/detail?id=338)] Support for client\_secrets.json has been added. + * [[Issue 406](http://code.google.com/p/google-api-java-client/issues/detail?id=406)] Google ID Tokens based on JSON Web Tokens is now supported. + * [[Issue 321](http://code.google.com/p/google-api-java-client/issues/detail?id=321)] Asserting identity on Google App Engine to Google APIs is now supported. + * [[Issue 140](http://code.google.com/p/google-api-java-client/issues/detail?id=140)] Exponential backoff is now supported. + * Improvements to the surface of the service-specific generated libraries: + * [[Issue 306](http://code.google.com/p/google-api-java-client/issues/detail?id=306)] Top level schema classes which are arrays are now generated correctly. + * [[Issue 304](http://code.google.com/p/google-api-java-client/issues/detail?id=304)] Inner classes for unnamed objects. + * [[Issue 359](http://code.google.com/p/google-api-java-client/issues/detail?id=359)] OAuth 2.0 scopes are now generated. + * Library version now includes a revision number, e.g. “rev2”, that indicates a revision of the API without changing the version. + * [[Issue 407](http://code.google.com/p/google-api-java-client/issues/detail?id=407)] Split and renamed extension projects to be more intuitive. + * [[Issue 352](http://code.google.com/p/google-api-java-client/issues/detail?id=352)] Deprecated classes/methods/fields from version 1.6 have been removed. + * Updated to [google-http-java-client version 1.7](http://google-http-java-client.blogspot.com/2012/03/version-170-beta-released.html). + * Updated to [google-oauth-java-client version 1.7](http://google-oauth-java-client.blogspot.com/2012/03/version-170-beta-released.html). + +# Version 1.6.0-beta # + +_Nov 8, 2011_ + +| [New Features in base library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.6.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [New Features in generated library](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=Milestone%3DCodeGenVersion1.3.0+status%3DFixed&colspec=ID+Type+Priority+Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.6.0-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.6.0-beta/jdiff/changes.html) | +|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + * Many improvements to the surface of the generated libraries. Improvements are listed [here](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=Milestone%3DCodeGenVersion1.3.0+status%3DFixed&colspec=ID+Type+Priority+Summary). + * The service-specific client now adheres to the Builder pattern to follow our thread-safety style guidelines. + * The global parameters (prettyPrint, fields, keys etc) are now generated in a service-specific class that extends [JsonHttpRequest](http://javadoc.google-http-java-client.googlecode.com/hg/1.6.0-beta/com/google/api/client/http/json/JsonHttpRequest.html) and are initialized with [JsonHttpRequestInitializer](http://javadoc.google-http-java-client.googlecode.com/hg/1.6.0-beta/com/google/api/client/http/json/JsonHttpRequestInitializer.html). + * Better exception model by introducing [GoogleJsonResponseException](http://javadoc.google-api-java-client.googlecode.com/hg/1.6.0-beta/com/google/api/client/googleapis/json/GoogleJsonResponseException.html). + * Updated to [google-http-java-client](http://code.google.com/p/google-http-java-client/wiki/ReleaseNotes#Version_1.6.0-beta) version 1.6. + * Updated to [google-oauth-java-client](http://code.google.com/p/google-oauth-java-client/wiki/ReleaseNotes#Version_1.6.0-beta) version 1.6. + * All [samples](http://code.google.com/p/google-api-java-client/source/browse/?repo=samples) have been updated. + +# Version 1.5.1-beta # + +_Oct 25, 2011_ + +| [Bugs Fixed](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone=Version1.5.1%20status=Fixed&colspec=ID%20Type%20Priority%20Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.5.1-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.5.1-beta/jdiff/changes.html) | +|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +[Bugs Fixed](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone=Version1.5.1%20status=Fixed&colspec=ID%20Type%20Priority%20Summary):
+Issue [329](http://code.google.com/p/google-api-java-client/issues/detail?id=329): Update pom.xml to point to google-http-java-client 1.5.3-beta and google-oauth-java-client 1.5.2-beta
+Issue [325](http://code.google.com/p/google-api-java-client/issues/detail?id=325): Add Javadoc that refreshToken can be null in GoogleAccessProtectedResource
+Please take a look at the [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.5.1-beta/index.html). + + +--- + + +# Version 1.5.0-beta # + +_Sep 19, 2011_ + +| [New Features](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone=Version1.5.0%20status=Fixed&colspec=ID%20Type%20Priority%20Summary) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.5.0-beta/index.html) | [JDiff](http://javadoc.google-api-java-client.googlecode.com/hg/1.5.0-beta/jdiff/changes.html) | +|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Announcing the release of the new [Google HTTP Client Library for Java](http://code.google.com/p/google-http-java-client) and [Google OAuth Client Library for Java](http://code.google.com/p/google-oauth-java-client) split off from the [Google API Client Library for Java](http://code.google.com/p/google-api-java-client)! These are the core package that work with any HTTP REST, OAuth 1.0a or OAuth 2.0 (draft 10) service on the web. + +For more details, please take a look at our blog post on the Google Code Blog ["Google APIs Client Library for Java: now with OAuth 2.0"](http://googlecode.blogspot.com/2011/09/google-apis-client-library-for-java-now.html). + + +--- + + +# Version 1.4.1-beta # + +_May 7, 2011_ + +| [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.4.1-beta/index.html) | [JDiff relative to 1.3.2-alpha](http://javadoc.google-api-java-client.googlecode.com/hg/1.4.1-beta/jdiff/changes.html) | [New Features](http://code.google.com/p/google-api-java-client/issues/list?can=1&q=milestone%3DVersion1.4.0+status%3DFixed&colspec=ID+Type+Priority+Summary&x=component&y=milestone&cells=tiles) | [Compatibility notes with 1.3](http://google-api-java-client.googlecode.com/hg/google-api-client-assembly/readme.html) | +|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +Highlights: + * [Generated libraries for Google APIs](http://code.google.com/p/google-api-java-client/wiki/Setup#Generated_libraries_for_Google_APIs) based on the new Google API infrastructure, like Google Buzz. + * Better OAuth 2.0 support, including ability to [refresh expired tokens](http://javadoc.google-api-java-client.googlecode.com/hg/1.4.1-beta/com/google/api/client/googleapis/auth/oauth2/draft10/GoogleAccessProtectedResource.html), and [servlet-based 3-legged flows](http://javadoc.google-api-java-client.googlecode.com/hg/1.4.1-beta/com/google/api/client/googleapis/extensions/auth/helpers/oauth2/draft10/GoogleOAuth2ThreeLeggedFlow.html) that persist credentials + * Smarter data model that supports Java features like enums, generic types, and primitive arrays, as well as support for JSON nulls + * [Android JSON Factory](http://javadoc.google-api-java-client.googlecode.com/hg/1.4.1-beta/com/google/api/client/extensions/android3/json/AndroidJsonFactory.html) implementation that works with the built-in streaming JSON library on Honeycomb (SDK 3.0) or higher. \ No newline at end of file diff --git a/Samples.md b/Samples.md new file mode 100644 index 00000000..7ff7fdab --- /dev/null +++ b/Samples.md @@ -0,0 +1,53 @@ +# Available Samples # + +To view all the samples that are available for the Google APIs Client Library for Java, browse through the [samples in the project site](http://code.google.com/p/google-api-java-client/source/browse?repo=samples). Each sample has an instructions.html file that explains how to set up and use the sample. (To more easily view the instructions in a browser, visit http://samples.google-api-java-client.googlecode.com/hg/.) + +We welcome contributions for samples for other APIs, as described in our guide to [becoming a contributor](BecomingAContributor.md). + +If you would like to request a sample for other APIs that are not listed here, please post your requests on the API specific sites such as developers.google.com or [StackOverflow](http://stackoverflow.com/) + + +# Google+ Sample # + +A complete Google+ example is given in the [plus-cmdline-sample](http://samples.google-api-java-client.googlecode.com/hg/plus-cmdline-sample/instructions.html) sample. + +The following code snippet shows a short example of how to use the client library with the [Google+ API](https://developers.google.com/+/api/). + +``` +... + +String APPLICATION_NAME = "PlusSample"; +java.io.File DATA_STORE_DIR = + new java.io.File(System.getProperty("user.home"), ".store/plus_sample"); +FileDataStoreFactory dataStoreFactory; + +// Set up the HTTP transport and JSON factory +HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport(); +JsonFactory jsonFactory = JacksonFactory.getDefaultInstance(); + +// Load client secrets +GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(jsonFactory, + new InputStreamReader(PlusSample.class.getResourceAsStream("/client_secrets.json"))); + +// Set up authorization code flow +GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder( + httpTransport, jsonFactory, clientSecrets, + Collections.singleton(PlusScopes.PLUS_ME)).setDataStoreFactory(dataStoreFactory) + .build(); + +// Authorize +Credential credential = + new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user"); + +// Set up the main Google+ class +Plus plus = new Plus.Builder(httpTransport, jsonFactory, credential) + .setApplicationName(APPLICATION_NAME) + .build(); + +// Make a request to access your profile and display it to console +Person profile = plus.people().get("me").execute(); +System.out.println("ID: " + profile.getId()); +System.out.println("Name: " + profile.getDisplayName()); +System.out.println("Image URL: " + profile.getImage().getUrl()); +System.out.println("Profile URL: " + profile.getUrl()); +``` \ No newline at end of file diff --git a/Setup.md b/Setup.md new file mode 100644 index 00000000..cd41604a --- /dev/null +++ b/Setup.md @@ -0,0 +1,264 @@ +You can download the Google APIs Client Library for Java and its dependencies in a zip file, or you can use Maven. + + +Also see the [ProGuard setup instructions](http://code.google.com/p/google-http-java-client/wiki/Setup#ProGuard) that are part of the Google HTTP Client Library for Java documentation. + +# Download the Library with Dependencies # + +Download the latest zip file, which you can find on the [Downloads page](Downloads.md), and extract it on your computer. This zip file 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 readme.html file. + +## Eclipse ## + +If you use [Eclipse](http://www.eclipse.org), set the "Source attachment" for each class .jar file to its corresponding "-sources" .jar file. + +## Android ## + +If you are developing for Android and the Google API you want to use is included in the [Google Play Services library](https://developer.android.com/google/play-services/index.html), use that library for the best performance and experience. + +If you are using the Google APIs Client Library for Java with Android, it is important to know which dependencies are compatible with Android, specifically which Android SDK level. Android applications require the following .jar files, or newer compatible versions, from the libs folder: + * google-api-client-1.18.0-rc.jar + * google-api-client-android-1.18.0-rc.jar + * google-oauth-client-1.18.0-rc.jar + * google-http-client-1.18.0-rc.jar + * google-http-client-android-1.18.0-rc.jar + * gson-2.1.jar + * jackson-core-asl-1.9.11.jar + * jackson-core-2.1.3.jar + * jsr305-1.3.9.jar + * protobuf-java-2.4.1.jar + +**WARNING:** For Android, you MUST place the .jar files in a directory named "libs" so that the APK packager can find them. Otherwise, you will get a `NoClassDefFoundError` error at runtime. + +## Google App Engine ## + +Google App Engine applications require the following .jar files, or newer compatible versions, from the libs folder: + * google-api-client-1.18.0-rc.jar + * google-api-client-appengine-1.18.0-rc.jar + * google-api-client-servlet-1.18.0-rc.jar + * google-oauth-client-1.18.0-rc.jar + * google-oauth-client-appengine-1.18.0-rc.jar + * google-oauth-client-servlet-1.18.0-rc.jar + * google-http-client-1.18.0-rc.jar + * google-http-client-appengine-1.18.0-rc.jar + * gson-2.1.jar + * jackson-core-asl-1.9.11.jar + * jackson-core-2.1.3.jar + * jdo2-api-2.3-eb.jar + * jsr305-1.3.9.jar + * protobuf-java-2.4.1.jar + * transaction-api-1.1.jar + * xpp3-1.1.4c.jar + +## Servlet ## + +Servlet applications require the following .jar files, or newer compatible versions, from the libs folder: + * google-api-client-1.18.0-rc.jar + * google-api-client-servlet-1.18.0-rc.jar + * google-oauth-client-1.18.0-rc.jar + * google-oauth-client-servlet-1.18.0-rc.jar + * google-http-client-1.18.0-rc.jar + * commons-logging-1.1.1.jar + * gson-2.1.jar + * httpclient-4.0.1.jar + * httpcore-4.0.1.jar + * jackson-core-asl-1.9.11.jar + * jackson-core-2.1.3.jar + * jdo2-api-2.3-eb.jar + * jsr305-1.3.9.jar + * protobuf-java-2.4.1.jar + * transaction-api-1.1.jar + * xpp3-1.1.4c.jar + +## Generic Java ## + +General purpose Java 5 applications require the following .jar files, or newer compatible versions, from the libs folder: + * google-api-client-1.18.0-rc.jar + * google-oauth-client-1.18.0-rc.jar + * google-http-client-1.18.0-rc.jar + * google-http-client-jackson2-1.18.0-rc.jar + * commons-logging-1.1.1.jar + * gson-2.1.jar + * httpclient-4.0.1.jar + * httpcore-4.0.1.jar + * jackson-core-asl-1.9.11.jar + * jackson-core-2.1.3.jar + * jsr305-1.3.9.jar + * protobuf-java-2.4.1.jar + * xpp3-1.1.4c.jar + +# Generated Libraries for Google APIs # + +Take a look at the [setup instructions for the generated libraries for Google APIs](https://developers.google.com/api-client-library/java/apis/). + +# Maven # + +The Google APIs Client Library for Java is in the central [Maven](http://maven.apache.org) repository. The Maven `groupId` for all artifacts for this library is `com.google.api-client`. Specific Maven instructions are given for each module (below). + +If you use [Eclipse](http://www.eclipse.org), install the [Maven plugin](http://www.eclipse.org/m2e/). Also make sure to set your Eclipse preferences as follows: + 1. Within Eclipse, select **Window > Preferences** (or on Mac, **Eclipse > Preferences**). + 1. Select **Maven** and select the following options: + * "Download Artifact Sources" + * "Download Artifact JavaDoc" + +# Google Plugin for Eclipse # + +With Google Plugin for Eclipse 2.6, you can [add Google APIs to your App Engine or Android project](https://developers.google.com/eclipse/docs/googleapis). To do this: + 1. Within Eclipse, right-click on a project and select **Google > Add Google APIs**. + 1. Select the Google API you need from the list of available Google APIs. + 1. Click Finish. +Eclipse will automatically download the API client library (along with its dependencies and source) onto your project's classpath and into the war/WEB-INF/lib directory. It will provide you with update notifications when the Google API or the client library has been updated. + +**WARNING:** Eclipse will show "Update available" when a newer version of the library is available. To update, use the same **Google > Add Google APIs** utility. Make sure to update all the Google API libraries on your project. Also, you must remove any old versions of the .jar files that this tool updates in your war/WEB-INF/lib directory. + +# Modules # + +This library is composed of nine modules: [google-api-client](#google-api-client.md), [google-api-client-android](#google-api-client-android.md), [google-api-client-appengine](#google-api-client-appengine.md), [google-api-client-servlet](#google-api-client-servlet.md), [google-api-client-gson](#google-api-client-gson.md), [google-api-client-jackson2](#google-api-client-jackson2.md), [google-api-client-java6](#google-api-client-java6.md), [google-api-client-protobuf](#google-api-client-protobuf.md), and [google-api-client-xml](#google-api-client-xml.md). + +## google-api-client ## + +The Google HTTP Client Library for Java (google-api-client) is designed to be compatible with all supported Java platforms, including Android. + +Maven usage: + +``` + + com.google.api-client + google-api-client + 1.18.0-rc + +``` + +On Android, you will need to explicitly exclude unused dependencies: + +``` + + com.google.api-client + google-api-client + 1.18.0-rc + + + xpp3 + xpp3 + + + httpclient + org.apache.httpcomponents + + + junit + junit + + + android + com.google.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. + +Maven usage: + +``` + + com.google.api-client + google-api-client-android + 1.18.0-rc + +``` + +## 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. + +Maven usage: + +``` + + com.google.api-client + google-api-client-servlet + 1.18.0-rc + +``` + +## google-api-client-appengine ## + +Google App Engine extensions to the Google HTTP 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. + +Maven usage: + +``` + + com.google.api-client + google-api-client-appengine + 1.18.0-rc + +``` + +## google-api-client-gson ## +GSON extensions to the Google HTTP Client Library for Java (google-api-client-gson). This module depends on google-api-client and google-http-client-gson. + +Maven usage: + +``` + + com.google.api-client + google-api-client-gson + 1.18.0-rc + +``` + +## google-api-client-jackson2 ## +Jackson2 extensions to the Google HTTP Client Library for Java (google-api-client-jackson2). This module depends on google-api-client and google-http-client-jackson2. + +Maven usage: + +``` + + com.google.api-client + google-api-client-jackson2 + 1.18.0-rc + +``` + +## google-api-client-java6 ## +Java 6 (and higher) extensions to the Google HTTP Client Library for Java (google-api-client-java6). This module depends on google-api-client and google-oauth-client-java6. + +Maven usage: + +``` + + com.google.api-client + google-api-client-java6 + 1.18.0-rc + +``` + +## google-api-client-protobuf ## +[Protocol buffer](https://developers.google.com/protocol-buffers/docs/overview) extensions to the Google HTTP Client Library for Java (google-api-client-protobuf). This module depends on google-http-client-protobuf and google-api-client. + +Maven usage: + +``` + + com.google.api-client + google-api-client-protobuf + 1.18.0-rc + +``` + +## google-api-client-xml ## +XML extensions to the Google HTTP Client Library for Java (google-api-client-xml). This module depends on google-api-client and google-http-client-xml. + +Maven usage: + +``` + + com.google.api-client + google-api-client-xml + 1.18.0-rc + +``` \ No newline at end of file diff --git a/Support.md b/Support.md new file mode 100644 index 00000000..dde6a0ea --- /dev/null +++ b/Support.md @@ -0,0 +1,48 @@ +# The Google APIs Client Library for Java Community # + +## Ask Development Questions ## + +Ask questions on StackOverflow: + * When you ask questions about the Google APIs Client Library for Java, use the [google-api-java-client](http://stackoverflow.com/questions/tagged/google-api-java-client) tag. Before you post a new question, review the [most asked questions](http://stackoverflow.com/questions/tagged/google-api-java-client?sort=faq&pagesize=50). + * For questions about Google APIs, use the [google-api](http://stackoverflow.com/questions/tagged/google-api) tag. + * Optionally include a tag to specify the language or platform, for example [java](http://stackoverflow.com/questions/tagged/google-api-java-client+java), [android](http://stackoverflow.com/questions/tagged/google-api-java-client+android), or [google-app-engine](http://stackoverflow.com/questions/tagged/google-api-java-client+google-app-engine). + * For tips on asking StackOverflow questions, see [How to Ask](http://stackoverflow.com/questions/ask). +| **Note:** Please do not email the project contributors directly. | +|:-----------------------------------------------------------------| + +## File Feature Requests and Defects ## + +You can suggest features and report issues on our public [Issue Tracker](https://code.google.com/p/google-api-java-client/issues/list). 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](http://code.google.com/p/google-api-java-client/issues/list?can=2&q=Type%3DDefect&sort=priority&colspec=ID+Milestone+Summary), 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](http://code.google.com/p/google-api-java-client/issues/entry). + +If you have a feature request: + * View [existing feature requests](http://code.google.com/p/google-api-java-client/issues/list?can=2&q=type%3DEnhancement&sort=milestone+priority&colspec=ID+Milestone+Summary), 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](http://code.google.com/p/google-api-java-client/issues/entry?template=Request%20a%20Feature). + +If you have a sample request: + * View existing [samples for Google APIs](Samples.md). View existing [sample requests](http://code.google.com/p/google-api-java-client/issues/list?can=2&q=type%3DSample&sort=priority&colspec=ID+Priority+Summary), and if a requested sample corresponds to a sample you would like, "star" it or comment on it. + * If the sample has not been requested, [file a sample request](http://code.google.com/p/google-api-java-client/issues/entry?template=Request%20a%20Sample). + +## Discuss ## + +We've established a [discussion group](http://groups.google.com/group/google-api-java-client) for both users and contributors to discuss the Google APIs Client Library for Java. + +## Contribute ## + +This is an [open-source](http://code.google.com/p/google-api-java-client/source/browse/) library, and [contributions](BecomingAContributor.md) are welcome. + +## Keep Up with the Library ## + +For the latest news about the Google APIs Client Library for Java, read the [announcements blog](http://google-api-java-client.blogspot.com/), or [subscribe to its feed](http://google-api-java-client.blogspot.com/feeds/posts/default). + +You can also take a look at the [release notes](ReleaseNotes.md). + + +<hr/> + + +# Migrating from GData Java Client # +For information about migrating from the [GData Java Client Library](http://code.google.com/p/gdata-java-client/) to the Google APIs Client Library for Java, see the [migration guide](http://code.google.com/p/gdata-java-client/wiki/MigratingToGoogleApiJavaClient). \ No newline at end of file diff --git a/TableOfContents.md b/TableOfContents.md new file mode 100644 index 00000000..67b44fcb --- /dev/null +++ b/TableOfContents.md @@ -0,0 +1,17 @@ +## [Developer's Guide](DeveloperGuide.md) ## + * [Download and Setup](Setup.md) + * [Samples](Samples.md) + * [Support](Support.md) + * [Android](Android.md) + * [OAuth 2.0](OAuth2.md) + * [ClientLogin (Deprecated)](ClientLogin.md) + * [Batch](Batch.md) + * [Media Upload](MediaUpload.md) + * [Media Download](MediaDownload.md) + * [Google App Engine](GoogleAppEngine.md) + * [Timeouts and Errors](HandlingTimeoutsAndErrors.md) + * [Release Notes](ReleaseNotes.md) + * [Becoming a Contributor](BecomingAContributor.md) + +| [Discussion](http://groups.google.com/group/google-http-java-client) | [JavaDoc](http://javadoc.google-api-java-client.googlecode.com/hg/1.18.0-rc/index.html) | +|:---------------------------------------------------------------------------------------------------------------------------------------------------------------| \ No newline at end of file