Coding in the Shade: Using Eclipse with Google Data APIs

Jeff Fisher, Google Data APIs Team
April 2008

New Google Data APIs Java Client Eclipse Plug-in : Create projects in seconds

As a supplement to this article, an Eclipse plug-in is available to minimize the overhead involved in setting up the Google Data dependencies. It also creates boilerplate code to interact with the API that you are interested in. This provides an easy way to get started developing with the Google Data APIs.


Eclipse is a very handy (and free!) IDE that has a special place in the hearts of many Java programmers. It is not a surprise then, that you might want to use it with the Java client library to make a killer Java application that works with one of the Google Data APIs.

Setting up Eclipse

If you don't have Eclipse installed yet, you've been missing out. Eclipse can make Java development a lot easier, due to its ability to suggest fixes, find missing imports, and autocomplete methods. Go to the downloads page to get the installer for your operating system. To run Eclipse you'll have to have a JRE installed, which is linked to from the Eclipse downloads page. Once you've installed Eclipse, you'll need to create a workspace. These examples use /usr/local/eclipse/workspace.

Installing required libraries

Eclipse provides a lot of Java functionality out of the box, so this should be easy. First things first, grab the latest version of the Java client library from the project downloads page. Note that there are two separate downloads: one for samples, and one for the source code. Download the samples zip, since that includes the compiled JAR files of the Java client library needed to create your own programs. If you are curious about how the client library itself works, you can download the source zip and look through it, but that is outside the scope of this article. Once you've downloaded the samples zip, unzip the file to a convenient directory where you can find the files. The examples use /usr/local/eclipse. This means the JAR files for the project should now be accessible under /usr/local/eclipse/gdata/java/lib.

Now that you have installed the client library, the next thing to do is download some external dependencies so we can include them in the project build path. The INSTALL-samples.txt file contains a list of jars you'll need and locations to download them from. The current list is:

Filename Location
mail.jar Sun's JavaMail API
activation.jar Sun's JavaBeans Activation Framework
servlet-api.jar Apache Tomcat

In this example, these JAR files are downloaded and copied to /usr/local/eclipse/gdata/third_party.

Whew! Now you should have all the pieces you need to start developing a Java application that uses one of the Google Data APIs. Read on!

Creating a new application

The first step is to open Eclipse and select "New > Java Project" from the File menu.

Eclipse new project window

Now click Next and select the Libraries tab. Add in all of the dependent JAR files you downloaded by clicking on Add External JARs.

Adding dependency JARs

You also will have to add in the JAR files from the Java client library. They are located in the java/lib subdirectory of where you extracted the client library. You will always have to include the following JAR files: gdata-client, gdata-client-meta, gdata-core, and gdata-media.

Adding GData JARs

Now choose which API you wish to use. This example uses the Google Documents List API. This requires adding in the appropriate JAR files: gdata-docs and gdata-docs-meta.

Adding DocList JARs

Finally you can click "Finish" and create your new project.

The newly created project

To make a simple test application, create a new class with a main method by selecting "New > Class" from the File menu.

Creating a class

Now I'm going to paste in some code from the Developer's Guide for the Documents List API.

Sample code with errors

You will see a lot of errors until you add the appropriate import statements. Eclipse makes this easy, all you have to do is click on the error markers on the left to get a helpful menu that lets you add imports.

The quickfix menu

Once you have cleaned up the imports, you also have to handle exceptions that can be thrown by our code. The example opts to surround the entire sample code with a very rudimentary exception handler.

Working sample code

Now, assuming that you substitute the username and password with a valid test account you have created, you should be able to see a list of documents owned by that test account when you choose "Run" from the Run menu.

The program output



Now that you have a working instance of Eclipse and all the required JAR files in place, you are well on your way to building an awesome Java application that works with one of the Google Data APIs.

Where to go from here? There are a few links you may find useful:

Java is a trademark of Sun Microsystems, Inc. in the United States and other countries.