- 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 JavaBeansActivationFramewrok. 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.
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
Pathenvironment variable to easily run JDK executables likejavac. The path you'll want to add will look something likeC:\jdk\bin\. See the Appendix for instructions on how to edit thePathvariable 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
cmdinto the text field. - Type
ant -versioninto 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
.zipdownload. - Extract all files into the location of your choice, like
C:\ant - Add the ant
bindirectory, likeC:\ant\binto yourPathenvironment variable. - Add or edit the
ANT_HOMEenvironment variable to set it as the new location, e.g.C:\ant - Add or edit the
JAVA_HOMEenvironment 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
.zipfile containing JavaMail. - Extract the files to your computer and note the location.
mail.jarwill be under the root directory,javamail-(version)
Getting activation.jar
The JavaBeans Activation Framework is included for media support.
- Visit http://java.sun.com/products/javabeans/jaf/downloads/index.html
- Click the "Download" button.
- Read and accept the License Agreement.
- Click the link for the
.zipfile containing the Activation Framework. - Extract the files to your computer and note the location.
activation.jarwill 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.jarshould be located atC:\Program Files\Apache Software Foundation\Tomcat 6.0\lib
Installing the Google Data Client Library
- Visit http://code.google.com/p/gdata-java-client/downloads/list
- Click on the featured download.
- Extract the file onto your computer.
- Navigate to
gdata/java/build/build.propertiesand open the file. - Edit the external dependencies to point to the locations of the
.jarfiles 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
mail.jar=./lib/mail-1.4.jar
activation.jar=./lib/activation-1.1.jar
Running Samples
All of the available samples are located under gdata/java/sample. The gdata/java/build/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 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 sample.spreadsheet.guidemo.run
To find out how to run a particular sample, go to gdata/java/build 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", "fortytwo"); 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", "fortytwo"); 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/gdata.ops.demo@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 this article about 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 developer guides.
