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 错误，最好获取所有依赖项。选择您要使用的操作系统以继续操作：Windows、Mac OS X 或 Linux。

安装 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.username 和 sample.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，但您不妨了解一下 Eclipse 或 NetBeans 等热门工具。下面是一些可能对您有用的其他链接：

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