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 DependenciesThe 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).
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.
Instructions for the Windows operating system.
Installing JavaThe 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.
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 AntApache 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.
cmd into the text field.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.
.zip download.C:\antbin directory, like C:\ant\bin to your Path environment variable.ANT_HOME environment variable to set it as the new location, e.g. C:\antJAVA_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.jarThe JavaMail API is included for media support.
.zip file containing JavaMail.mail.jar will be under the root directory, javamail-(version)The JavaBeans Activation Framework is included for media support.
.zip file containing the Activation Framework.activation.jar will be under the root directory, jaf-(version)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.
servlet-api.jar should be located at C:\Program Files\Apache Software Foundation\Tomcat 6.0\libMore 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 XInstructions for the Mac OS X operating system.
Installing JavaIf 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 AntApache 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+.
ant -version
If the version of ant you are running is less than 1.7, follow the steps below to get the latest version.
.zip download.cd ~/Desktopsudo shmv apache-ant-(version)-bin.zip /usr/local/cd /usr/local/unzip apache-ant-(version)-bin.zipchown (your account name):(your account name) apache-ant-(version)ln -s apache-ant-(version) antYou 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.jarThe JavaMail API is included for media support.
.zip file containing JavaMail.mail.jar will be under the root directory, javamail-(version)The JavaBeans Activation Framework is included for media support.
.zip file containing the Activation Framework.activation.jar will be under the root directory, jaf-(version)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.
.zip download under Core Binary Distributions.servlet.jar will be found under apache-tomcat-(version)/libMore Tomcat setup and installation documentation can be found here.
Phew, okay, now you're ready to install the GData Java Client Library.
On LinuxInstructions for the Linux operating system.
Installing JavaThis 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:
suchmod a+x jdk-6(version)-linux-i586-rpm.bin./jdk-6(version)-linux-i586-rpm.binIf you don't have root privileges:
chmod +x jdk-6(version)-linux-i586-rpm.bin./jdk-6(version)-linux-i586-rpm.binIf you run into trouble, more detailed installation instructions can be found here.
Installing AntThe 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.
.tar.gz download.gunzip apache-ant-(version)-bin.tar.gztar xvf apache-ant-(version)-bin.tarbin directory to your PATH environment variable.ANT_HOME environment variable to set it as the new location.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.jarThe JavaMail API is included for media support.
.zip file containing JavaMail.unzip the files to your computer and note the location. mail.jar will be under the root directory, javamail-(version)The JavaBeans Activation Framework is included for media support.
.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)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.
.tar.gz file under Core Binary Distributions.gunzip and tar as shown in the Installing Ant section above.servlet.jar will be found under apache-tomcat-(version)/libYou should now have everything you need for getting the GData Java Client Library!
Installing the Google Data Client Librarygdata-src.java-1.x.x.java.zip) and the samples (gdata-samples.java-1.x.x.java.zip).gdata/java/build-src/build.properties and open the file..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
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.
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.
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.
ConclusionHopefully, 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.
Appendix: Setting Environment VariablesInstructions for setting your environment variables on Windows or Linux. You should not have to set anything for Mac OS X.
WindowsSystem 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:
ANT_HOME and set the value to C:\antJAVA_HOME and set the value to C:\jdkPath and append ;C:\ant\bin;C:\jdk\bin to the end (the semicolon separates directory paths)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.Note: Ensure that the variables do not have quotes (either ' or ") and do not end with \ or /.
If you don't have administrative privileges:
ANT_HOME and set the value to C:\antJAVA_HOME and set the value to C:\jdkPath and append ;C:\ant\bin;C:\jdk\bin to the end (the semicolon separates directory paths)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.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.bash_profile file in your editor of choice, located in your home directory..bash_profile, substituting the actual locations of the files on your machine:export ANT_HOME=/usr/local/antexport JAVA_HOME=/usr/local/jdkexport PATH=${PATH}:${ANT_HOME}/bin.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 variablesNote: Ensure that the variables do not have quotes (either ' or ") and do not end with \ or /.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4