Bianor blog

Introduction

Google Calendar team has developed API for several programming languages (Python, PHP, .Net, Java, JavaScript) that wraps basic data API interaction using raw XML/HTTP. These APIs allow applications to view, manage and update calendars and calendar events in the form of Google Data API (GData) feeds. GData provides standard protocol, based on RSS and Atom for reading and writing data on Google’s applications.

I am going to cover only the Java API for interaction with Google Calendar, which hides the complexity of raw XML/HTTP.

Getting started

First of all you need to download the client libraries of the API. You need two jars from Google Calendar API: data-calendar-1.0.jar and gdata-client-1.0.jar. These libraries depend on mail.jar and activation.jar so you need to obtain them too.

In order to work with Google Calendar there is a certain procedure that you have to follow:

1. First you have to construct appropriate URL to the service that you need to access.
2. Create a new com.google.gdata.client.calendar.CalendarService instance, by setting your application name.
3. Set credentials. (Authenticate to the system)
4. Execute a method call for select, create, update or delete data.

Authentication

You can choose to work with public or private data (feeds) from the calendar service. For the public data you do not need any authentication to the calendar service and you can only read this data without consequent modification. If you need access to private data you have to authenticate. There are three different ways to do that: AuthSub proxy authentication, ClientLogin which is username / password authentication and MagicCookie authentication, which grants read-only permission for access to the data.

1. AuthSub proxy authentication.

To use this authentication you need to construct URL that depends on the service you want to access and redirect the user to that URL. Then Google Authentication service will authenticate the user and will return to your system “one time use” token that will grant you access to the user’s data. You can use this token to make only one access to calendar service. If you need to access the service more than once or if you need to store the token for future use you can exchange it for session token. Once a session token is acquired you can store it in your data base (for example) and use it later.

This approach is useful for web based applications. The user does not share his/her password directly with the application provider, but authenticates to Google Authentication service, which grants access to user’s calendar data.

Let’s see the code that’s needed for that authentication. First we said that there has to be a URL to redirect the user to.

String requestUrl =

AuthSubUtil.getRequestUrl(“http://www.MyApp.com/token.do”, // next page
CalendarService.CALENDAR_ROOT_URL, // scope
false, // secure
true); // session

I am using getRequestUrl method of com.google.gdata.client.http.AuthSubUtil class to generate the redirect URL. It has four parameters. The first one - “next page” is the resource of the web application where Google Authentication service will redirect the user after successful authentication. The second parameter “scope” is the service that we need to access. To authenticate in front Calendar service you need “http://www.google.com/calendar/feeds/” which is available as a constant in CalendarService class. The third parameter shows if the following request is going to be signed by registered application or not. And the last parameter “session” sets if the “one time token” is going to be exchanged as a session token.

As it was already described the next step is to redirect the user to the created URL. This can be done in several ways. Just to illustrate I set the URL as a request attribute called “gRequestUrl” and then use it in a sample JSP page that informs the user for following redirect.

Authenticate at Google:

<p>Application needs access to your Google Calendar account to read your Calendar feed.<br />

To authorize the application to access your account, <b/>
<a href=”${gRequestUrl}”>log in to your account</a>.</p>

The user is redirected to a page where he/she can provide appropriate credentials for accessing his private data. If the user provides them, the authentication service redirects back to your web application on the page previously configured as “next page”, set while creating the URL for authentication. Your page receives as “one time use” token a parameter called token:

http://www.MyApp.com/token.do?token=<ONETIMETOKEN>

You can easily retrieve the token by calling getTokenFromReply from AuthSubUtil class as follows:

String oneTimeToken =

AuthSubUtil.getTokenFromReply(request.getQueryString());

You can exchange this token for a session token. Session token can be used as many times as needed. According то current documentation it does no expire, so it can be saved for later use. Here is the code for exchanging the token:

String sessionToken =

AuthSubUtil.exchangeForSessionToken(oneTimeToken, null);

The first parameter is the “one time token”, the second one is null for not registered application and private key for registered application. For more information you can refer to the documentation.

Once you have the token you can use it with CalendarService object. You have to create instance of CalendarService class which will be your gate to Google Calendar service. Here is an example how to create new CalenarService and how to apply the retrieved session token.

CalendarService calService = new CalendarService(“Bianor-Test-0.1”);
//[company-id]-[app-name]-[app-version]
calService.setAuthSubToken(sessionToken);

The parameter in CalendarService is in form [company-id]-[app-name]-[app-version] and describes your application in front of Google’s Services. You have the option to register you application or to stay unregistered. Depending on your choice Google shows login page with different level of alerts when you request an authorization to user’s account.

As noted when you have session token it will never expire, but you can revoke the token when you finish your work with it. Google usually maintains only several (10) tokens per account, so you are advised to manually destroy them when you finish working with them. This can be done executing:

AuthSubUtil.revokeToken(sessionToken, null);

There is something else you should keep in mind when working with session tokens for a long time. Even though they do not expire, the user may manually revoke them from his/her Google account.

2. ClientLogin with username and password authentication

To use ClientLogin your application needs to know the user name and password. It is suitable for installed applications. To authenticate using this technique you simply need to call setUserCredentials method on CalendarService instance.

CalendarService calService = new CalendarService(“Bianor-Test-0.1”);
calService.setUserCredentials(“user@gmail.com”, “password”);

3. Magic cookie authentication

Magic cookie authentication provides read-only access to private data. I am going to show read-write operations from now on, so I am not going to cover this technique of authentication. You can refer to Authentication documentation.

(next: part II)

Sphere: Related Content

Tags: Google Calendar