Google Data Java 客户端库使用入门

Stephanie Liu,Google Data API 团队
2007 年 9 月
  1. 简介
  2. 安装依赖项
    1. 在 Windows 上
    2. 在 Mac OS X 上
    3. 在 Linux 设备上
  3. 安装 Google Data 客户端库
  4. 运行示例
  5. 构建自己的应用
  6. 总结
  7. 附录:设置环境变量

简介

刚开始使用不熟悉的 API 进行开发时,总是会遇到一些困难,因此本文提供了有关如何下载和安装 Google Data API (“GData”) Java 客户端库的分步说明。接下来,我将介绍如何获取所有依赖项并设置所需的环境变量。您很快就能将不同的 GData 服务混搭在一起!

使用 Eclipse?

请参阅在阴凉处编码:将 Eclipse 与 Google Data API 搭配使用一文。

安装依赖项

GData Java 客户端库具有以下外部依赖项。以下部分将介绍如何在您喜爱的操作系统(或您在工作中使用的操作系统)上安装这些依赖项。

  • JDK(Java 开发套件)版本 1.5 及更高版本
  • Apache Ant 版本 1.7 及更高版本
  • Sun 的 JavaMail API 1.4+ 中的 mail.jar
  • Sun 的 JavaBeansActivationFramework 中的 activation.jar。只有媒体专用 API(包括 Document List Data API、Picasa 网络相册 API 和 YouTube Data API)才需要此权限。
  • Sun 的 Servlet API 版本 2.3+ 中的 servlet.jar。仅当执行“sample.authsub”或“sample.gbase.recipe”软件包中的代码示例时,才需要此文件。

部分 .jar 依赖项仅为特定示例所必需,但为避免 build 错误,最好获取所有依赖项。选择您要使用的操作系统以继续操作:WindowsMac OS XLinux

安装 Google Data 客户端库

  1. 访问 http://code.google.com/p/gdata-java-client/downloads/list
  2. 下载最新版本的客户端库 (gdata-src.java-1.x.x.java.zip) 和示例 (gdata-samples.java-1.x.x.java.zip)。
  3. 将客户端库来源提取到您的计算机上。
  4. 找到 gdata/java/build-src/build.properties 并打开相应文件。
  5. 修改外部依赖项,使其指向本地机器上 .jar 文件的位置。
  6. 注意:在 Windows 上,请务必转义反斜杠。例如,

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

运行示例

所有可用的示例都位于 gdata-samples.java-1.x.x.java.zip 归档文件中的 gdata/java/sample 下。gdata/java/build-samples/build.properties 文件包含库中包含的样本的所有输入值。将 sample.credentials.usernamesample.credentials.password 设置为有效的用户名和密码。我们可以使用 Ant 来构建和执行示例。

打开命令提示符,切换到 gdata/java 目录,然后输入以下内容,测试是否已正确安装所有内容:

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

您可能会收到一些信息或警告消息,但请务必留意最后的 BUILD SUCCESSFUL 消息!如果您未收到成功消息,请参阅问题排查部分

输入以下内容,试用更具互动性的示例:

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

如需了解如何运行特定示例,请前往 gdata/java/build-samples 并查看相应示例的 build 文件。查找 samples run 部分。

问题排查

如果您的 build 失败并显示类似如下的错误消息,

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

或者,您会收到有关项目缺少必需文件的类似错误消息,这可能是因为您运行的是旧版 Ant。输入 ant -version,确保您运行的是 1.7 或更高版本。请参阅上文中的依赖项说明,获取最新版本的 Ant。

构建自己的应用

下一个问题是如何构建自己的应用。我将介绍一个使用 Calendar 服务的“Hello, World!”等效程序,以展示基本功能。如需了解详情,请参阅 Java 客户端库的开发者指南以及各个产品的开发者指南

创建一个名为 CalendarTest.java 的文件。首先,添加以下 import 语句。

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.*;

以下是整个程序(不包含任何异常处理)。

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");

然后,系统会设置资源的网址。在这种情况下,您可以在此处请求经过身份验证的用户的全部日历列表。

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

以下行将在网址上执行实际的 GET 命令,并将生成的 Feed 放入整洁的对象中。

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

下面的 for 循环将遍历每个条目并打印相应标题。请注意,标题以 TextConstruct 格式存储,因此需要额外的函数调用才能获取纯文本。

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

以上内容非常基础,接下来我们再介绍一些其他常见事项。以下代码段将展示如何创建对象并插入该对象。在我们的示例中,它将是一个新的日历活动条目。

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);

另一种常见操作是构建查询。

//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());
}

在调试时,另一项有用的操作是转储原始 XML。您可以使用库中的实用程序来执行此操作。确保已导入 samples.util.*。然后,转储相应 Feed 或条目。

CommonUtils.dump(resultFeed, System.out);

如需更深入的调试工具,请参阅我们的调试 Google Data API 客户端:从程序内部探索流量一文,了解如何从客户端库内部开启日志记录。

这应该能让您了解使用客户端库构建应用是什么样的。如需了解更多详细信息,请参阅总结部分,其中列出了每种 Google Data API 的可用开发者指南。

总结

希望您现在能够使用 GData Java 客户端库构建和运行应用!我没有介绍任何常用的 IDE,但您不妨了解一下 EclipseNetBeans 等热门工具。下面是一些可能对您有用的其他链接:

如果您在使用 Java 客户端库时遇到任何 API 相关问题,可以在特定 API 的论坛中发帖告知我们。