Getting Started with the Google Data Java Client Library

Stephanie Liu, Google Data APIs Team
September 2007
  1. Introduction
  2. Installing Dependencies
    1. On Windows
    2. On Mac OS X
    3. On Linux
  3. Installing the Google Data Client Library
  4. Running Samples
  5. Building Your Own Applications
  6. Conclusion
  7. Appendix: Setting Environment Variables

Introduction

It's never easy to start developing with an unfamiliar API, so this article has step-by-step instructions on how to download and install the Google Data APIs ("GData") Java Client Library. I'll go through getting all of the dependencies and setting the environment variables you'll need. You'll be mashing up different GData services in no time!

Using Eclipse?

Check out the Coding in the Shade: Using Eclipse with Google Data APIs article.

Installing Dependencies

The GData Java Client Library has the following external dependencies. The following sections will describe how to install these dependencies on your favorite operating system (or the OS that you're stuck with at work).

  • JDK (Java Development Kit) version 1.5+
  • Apache Ant version 1.7+
  • mail.jar in Sun's JavaMail API 1.4+
  • activation.jar in Sun's JavaBeansActivationFramework. This is only required for media specific APIs including Document List Data API, Picasa Web Album API, and YouTube Data API.
  • servlet.jar in Sun's Servlet API version 2.3+. This is required only if executing code samples in 'sample.authsub' or 'sample.gbase.recipe' packages.

A few of the .jar dependencies are only required for specific samples, but to avoid build errors, it's best just to get everything. Choose your operating system of choice to continue: Windows, Mac OS X, or Linux.

Installing the Google Data Client Library

  1. Visit http://code.google.com/p/gdata-java-client/downloads/list
  2. Download the latest version of the client library (gdata-src.java-1.x.x.java.zip) and the samples (gdata-samples.java-1.x.x.java.zip).
  3. Extract the client library source onto your computer.
  4. Navigate to gdata/java/build-src/build.properties and open the file.
  5. Edit the external dependencies to point to the locations of the .jar files on your local machine.

    6. Note: On Windows, be sure to escape the backslashes. For example,

    servlet.jar=C:\\Program Files\\Apache Software Foundation\\Tomcat 6.0\\lib\\servlet-api.jar

Running Samples

All of the available samples are located under gdata/java/sample from the gdata-samples.java-1.x.x.java.zip archive. The gdata/java/build-samples/build.properties file contains all the input values for the samples contained in the library. Set sample.credentials.username and sample.credentials.password to a valid username and password. We can use Ant to build as well as execute the samples.

Test to see if you've installed everything correctly by opening a command prompt, changing to the gdata/java directory, and typing:

ant -f build-samples.xml sample.calendar.run

You may receive some info or warning messages, but just look for the BUILD SUCCESSFUL message at the end! See the troubleshooting section if you don't get a success message.

Try out a more interactive sample by typing:

ant -f build-samples.xml sample.spreadsheet.guidemo.run

To find out how to run a particular sample, go to gdata/java/build-samples and check the build file for that sample. Look for the samples run section.

Troubleshooting

If your build fails with an error message like,

BUILD FAILED
Target 'core.sample.core.util.build' does not exist in this project. It is used from target 'sample.calendar.build'.

Total time: 0 seconds

or a similar error message about an essential file missing from the project, you may be running an older version of Ant. Type ant -version to make sure you're running 1.7 or higher. Refer to the dependency instructions above to get the latest version of Ant.

Building Your Own Applications

The next question is how to build your own application. I'll go through a "Hello, World!" equivalent program using the Calendar service to exhibit basic functionality. More detailed information can be found in the Java Client Library's developer guide, as well as the individual product developer guides.

Create a file called CalendarTest.java. Start by including the following import statements.

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.acl.*;
import com.google.gdata.data.calendar.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;

import java.net.*;
import java.io.*;

import sample.util.*;

Here is the whole program (without any exception handling).

public class CalendarTest {

    public static void main(String[] args) {
        CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
        myService.setUserCredentials("root@gmail.com", "pa$$word");

        URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");
        CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

        System.out.println("Your calendars:");
        System.out.println();

        for (int i = 0; i < resultFeed.getEntries().size(); i++) {
          CalendarEntry entry = resultFeed.getEntries().get(i);
          System.out.println("\t" + entry.getTitle().getPlainText());
        }

    }
}

This little program will request all the calendars you own and display all the titles. It's a little longer than the canonical "Hello, World!" example, but it's very simple once we break it down. The first couple of lines creates a service object and sets the user credentials.

CalendarService myService = new CalendarService("exampleCo-exampleApp-1.0");
myService.setUserCredentials("root@gmail.com", "pa$$word");

Then, the URL of the resource is set. In this case, this is where you can request the list of all calendars from the authenticated user.

URL feedUrl = new URL("http://www.google.com/calendar/feeds/default/allcalendars/full");

The line below will execute the actual GET command on the URL and put the resultant feed into a tidy object.

CalendarFeed resultFeed = myService.getFeed(feedUrl, CalendarFeed.class);

The for loop below will iterate through each entry and print the title. Note that the title is stored as a TextConstruct, so an extra function call is required to get the plain text.

for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    CalendarEntry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
}

That was pretty basic - let's go through a few other common things. The following snippet will show you how to create an object and insert it. For our example, it will be a new calendar event entry.

URL postURL = new URL("http://www.google.com/calendar/feeds/root@gmail.com/private/full");
CalendarEventEntry myEvent = new CalendarEventEntry();

//Set the title and description
myEvent.setTitle(new PlainTextConstruct("Pi Day Party"));
myEvent.setContent(new PlainTextConstruct("I am throwing a Pi Day Party!"));

//Create DateTime events and create a When object to hold them, then add
//the When event to the event
DateTime startTime = DateTime.parseDateTime("2007-03-14T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2007-03-14T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEvent.addTime(eventTimes);

// POST the request and receive the response:
CalendarEventEntry insertedEntry = myService.insert(postURL, myEvent);

Another common operation is building a query.

//Create a new query object and set the parameters
Query myQuery = new Query(feedURL);
myQuery.setFullTextQuery("Pi");

//Send the request with the built query URL
CalendarEventFeed myResultsFeed = myService.query(myQuery, CalendarEventFeed.class);

//Take the first match and print the title
if (myResultsFeed.getEntries().size() > 0) {
    CalendarEventEntry firstMatchEntry = new CalendarEventEntry();
    myResultsFeed.getEntries().get(0);
    System.out.println(firstMatchEntry.getTitle().getPlainText());
}

While debugging, another useful operation is dumping out the raw XML. There's a handy utility that you can use to do this in the library. Make sure samples.util.* is imported. Then, dump the feed or entry.

CommonUtils.dump(resultFeed, System.out);

For even deeper debugging tools, check out our Debugging Google Data API Clients: Exploring Traffic from Within your Program article on how to turn on logging from within the client library.

This should give you a feel for what building apps using the client library is like. For more detailed information, see the conclusion section for a list of available developer guides for each Google Data API.

Conclusion

Hopefully, you're now able to build and run applications using the GData Java Client Library! I didn't go into any of the popular IDEs that you can use, but you may want to look into popular tools like Eclipse or NetBeans. Here are some additional links that may be helpful:

If you have any questions on using Java Client Library with any API, you can let us know by posting in the API specific forums.