Getting Started with the Google Data Java Client Library

Stephanie Liu, Google Data APIs Team
September 2007

Introduction
Installing Dependencies
Installing the Google Data Client Library
Running Samples
Building Your Own Applications
Conclusion
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.

On Windows

Instructions for the Windows operating system.

Installing Java

The Java development package is available from Sun in the form of the JDK (Java Development Kit). The JRE (Java Runtime Environment) and everything else you need to write, compile, test, and debug Java applications are contained within. If you already have Java installed, skip ahead to installing Ant.

Note: You need to have administrative permissions to install the JDK.

Visit http://java.sun.com/javase/downloads/index.jsp
Click "Download" next to the latest update.
Read and accept the License Agreement.
Download one of the Windows Installation files.
Run the installer.
Edit the Path environment variable to easily run JDK executables like javac. The path you'll want to add will look something like C:\jdk\bin\. See the Appendix for instructions on how to edit the Path variable in Windows.

If you have any problems installing the JDK, check out the detailed installation instructions on Sun's website.

Installing Ant

Apache Ant is a build tool for Java similar to make (but better). You'll be using it to build the library and execute samples. If you already have Ant installed, check that it's version 1.7 or higher.

Click the "Start" menu, and then "Run."
Type cmd into the text field.
Type ant -version into the prompt to see which version you have.

If you have 1.7+, skip ahead to getting mail.jar. If your version of Ant is lower than 1.7 or you don't have it installed, follow the steps below.

Visit http://ant.apache.org/bindownload.cgi
Click on the download link for the .zip download.
Extract all files into the location of your choice, like C:\ant
Add the ant bin directory, like C:\ant\bin to your Path environment variable.
Add or edit the ANT_HOME environment variable to set it as the new location, e.g. C:\ant
Add or edit the JAVA_HOME environment variable to where Java is installed, e.g. C:\jdk.

You can find detailed installation instructions at Ant's website if you run into any issues.

Getting mail.jar

The JavaMail API is included for media support.

Visit http://java.sun.com/products/javamail/downloads/index.html
Click the "Download" button. Ensure that you are downloading version 1.4 or greater.
Read and accept the License Agreement.
Click the link for the .zip file containing JavaMail.
Extract the files to your computer and note the location. mail.jar will be under the root directory, javamail-(version)

Getting activation.jar

The JavaBeans Activation Framework is included for media support.

Visit the JAF download page.
Click the "Download" button.
Read and accept the License Agreement.
Click the link for the .zip file containing the Activation Framework.
Extract the files to your computer and note the location. activation.jar will be under the root directory, jaf-(version)

Getting servlet.jar

servlet.jar (it may be called servlet-api.jar) can be found in your servlet container (J2EE, Tomcat, WebLogic, etc.). It is used for the AuthSub and Google Base samples. The following instructions go through getting Tomcat 6.x.

Visit http://tomcat.apache.org/download-60.cgi
Click on the Windows Service Installer download under Core Binary Distributions.
Run the installer.
If you stayed with the default, servlet-api.jar should be located at C:\Program Files\Apache Software Foundation\Tomcat 6.0\lib

More Tomcat setup and installation documentation can be found here.

Phew, okay, now you're ready to install the GData Java Client Library.

On Mac OS X

Instructions for the Mac OS X operating system.

Installing Java

If you're running Mac OS X, you have less work to do! Apple has included a fully configured and ready-to-use JDK (Java Development Kit) with every instance. Check out Apple's Java site for more information.

Installing Ant

Apache Ant is a build tool for Java similar to make (but better). You'll be using it to build the library and execute samples. You probably already have Ant installed as well, but check that you have version 1.7+.

Open a terminal window. (Command + Space bar, then type 'Terminal' to find the application)
At the command prompt, type:

ant -version

If the version of ant you are running is less than 1.7, follow the steps below to get the latest version.

Visit http://ant.apache.org/bindownload.cgi
Click on the download link for the .zip download.
Open a terminal window. (Command + Space bar, then type 'Terminal' to find the application)
At the command prompt, type the following:
- cd ~/Desktop
- sudo sh
- mv apache-ant-(version)-bin.zip /usr/local/
- cd /usr/local/
- unzip apache-ant-(version)-bin.zip
- chown (your account name):(your account name) apache-ant-(version)
- ln -s apache-ant-(version) ant

You can find detailed installation instructions at Ant's website if you run into any issues. This blog post also has a detailed explanation of what the above shell commands mean.

Getting mail.jar

The JavaMail API is included for media support.

Visit http://java.sun.com/products/javamail/downloads/index.html
Click the "Download" button. Ensure that you are downloading version 1.4 or greater.
Read and accept the License Agreement.
Click the link for the .zip file containing JavaMail.
Extract the files to your computer and note the location. mail.jar will be under the root directory, javamail-(version)

Getting activation.jar

The JavaBeans Activation Framework is included for media support.

Visit the JAF download page.
Click the "Download" button.
Read and accept the License Agreement.
Click the link for the .zip file containing the Activation Framework.
Extract the files to your computer and note the location. activation.jar will be under the root directory, jaf-(version)

Getting servlet.jar

Visit http://tomcat.apache.org/download-60.cgi
Click on the .zip download under Core Binary Distributions.
Extract the files to your computer and note the location. servlet.jar will be found under apache-tomcat-(version)/lib

More Tomcat setup and installation documentation can be found here.

Phew, okay, now you're ready to install the GData Java Client Library.

On Linux

Instructions for the Linux operating system.

Installing Java

This tutorial will use Sun's JDK (Java Development Kit). If you have root access, please follow the instructions below. If not, you can just install the JDK in your home directory by following these instructions. If you already have the JDK 1.5+ installed, skip ahead to Installing Ant.

If you have root privileges:

Visit http://java.sun.com/javase/downloads/index.jsp
Click "Download" next to the latest version.
Read and accept the License Agreement.
Click and download the RPM file self extracting file under "Linux Platform."
Open a terminal window, change to the directory where you downloaded the file, and do the following:

su
chmod a+x jdk-6(version)-linux-i586-rpm.bin
./jdk-6(version)-linux-i586-rpm.bin
Agree to the license agreement.

If you don't have root privileges:

Visit http://java.sun.com/javase/downloads/index.jsp
Click "Download" next to the latest version.
Read and accept the License Agreement.
Click and download the self extracting build (not RPM) under "Linux Platform."
Open a terminal window, change to the directory where you downloaded the file, and type the following commands:

chmod +x jdk-6(version)-linux-i586-rpm.bin
Change to the directory where you want to file to be installed.
Run the self extracting binary. If you're installing it in the current directory, then you would just type ./jdk-6(version)-linux-i586-rpm.bin
Agree to the license agreement.

If you run into trouble, more detailed installation instructions can be found here.

Installing Ant

The GData Java Client Library requires Ant 1.7 or above. If you already have Ant installed, check the version by typing ant -version at a command prompt. If you need to get the latest version, or if you don't have it installed, follow the instructions below. Skip ahead to getting mail.jar if your Java and Ant installations are already set up.

Visit http://ant.apache.org/bindownload.cgi
Click on the download link for the .tar.gz download.
Extract the files by bringing up a terminal window, changing to the directory with the downloaded file, and typing the following commands:

gunzip apache-ant-(version)-bin.tar.gz
tar xvf apache-ant-(version)-bin.tar

Add the ant bin directory to your PATH environment variable.
Add or edit the ANT_HOME environment variable to set it as the new location.
Add or edit the JAVA_HOME environment variable to set it as the location that the JDK is installed.

In depth Ant installation documentation can be found here if you run into any issues.

Getting mail.jar

The JavaMail API is included for media support.

Visit http://java.sun.com/products/javamail/downloads/index.html
Click the "Download" button. Ensure that you are downloading version 1.4 or greater.
Read and accept the License Agreement.
Click the link for the .zip file containing JavaMail.
unzip the files to your computer and note the location. mail.jar will be under the root directory, javamail-(version)

Getting activation.jar

The JavaBeans Activation Framework is included for media support.

Visit the JAF download page.
Click the "Download" button.
Read and accept the License Agreement.
Click the link for the .zip file containing the Activation Framework.
unzip the files to your computer and note the location. activation.jar will be under the root directory, jaf-(version)

Getting servlet.jar

Visit http://tomcat.apache.org/download-60.cgi
Download the .tar.gz file under Core Binary Distributions.
Unpackage the download with gunzip and tar as shown in the Installing Ant section above.
servlet.jar will be found under apache-tomcat-(version)/lib

You should now have everything you need for getting the GData Java Client Library!

Installing the Google Data Client Library

Visit http://code.google.com/p/gdata-java-client/downloads/list
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).
Extract the client library source onto your computer.
Navigate to gdata/java/build-src/build.properties and open the file.
Edit the external dependencies to point to the locations of the .jar files on your local machine.

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:

GData Java Client Library homepage
List of Google Data APIs
Java Developer Guides are available for the following Google Data APIs:
Coding in the Shade: Using Eclipse with Google Data APIs
Google Data APIs Java Client Eclipse Plug-in

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.

Appendix: Setting Environment Variables

Instructions for setting your environment variables on Windows or Linux. You should not have to set anything for Mac OS X.

Windows

System variables will apply to all users on the computer. If you can't edit system variables because you don't have administrative privileges, follow the instructions here.

If you have administrative privileges:

Right click "My Computer" and select "Properties."
Click the "Advanced" tab.
Click on "Environment Variables."
"Add" or "Edit" system variables: (substitute the location on your local machine)

Add or Edit ANT_HOME and set the value to C:\ant
Add or Edit JAVA_HOME and set the value to C:\jdk
Add or Edit Path and append ;C:\ant\bin;C:\jdk\bin to the end (the semicolon separates directory paths)
Add or Edit CLASSPATH and append the .jar files you'll need, depending on which services you want to work with. Make sure the "." is included &mhash; this indicates the current directory. .;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar, etc.

Reboot to make sure they take effect.

Note: Ensure that the variables do not have quotes (either ' or ") and do not end with \ or /.

If you don't have administrative privileges:

Right click "My Computer" and select "Properties."
Click the "Advanced" tab.
Click on "Environment Variables."
"Add" or "Edit" user variables: (substitute the location on your local machine)

Add or Edit ANT_HOME and set the value to C:\ant
Add or Edit JAVA_HOME and set the value to C:\jdk
Add or Edit Path and append ;C:\ant\bin;C:\jdk\bin to the end (the semicolon separates directory paths)
Add or Edit CLASSPATH and append the .jar files you'll need, depending on which services you want to work with. Make sure the "." is included &mhash; this indicates the current directory. .;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar, etc.

Reboot to make sure they take effect.

Note: Ensure that the variables do not have quotes (either ' or ") and do not end with \ or /.

The user variables you have just edited will only apply to your user profile.

Linux

Open your .bash_profile file in your editor of choice, located in your home directory.
Add the following to your .bash_profile, substituting the actual locations of the files on your machine:

export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk
export PATH=${PATH}:${ANT_HOME}/bin
You'll need to add the .jar files for the services you'll be using. For example, export CLASSPATH=${CLASSPATH}:/home/username/gdata/java/lib/gdata-core-1.0.jar:/home/username/gdata/java/lib/gdata-calendar-1.0.jar:/home/username/gdata/java/sample/util/lib/sample-util.jar

source .bash_profile to establish the variables

Note: Ensure that the variables do not have quotes (either ' or ") and do not end with \ or /.