2007 年 9 月
简介
刚开始使用不熟悉的 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 客户端库
- 访问 http://code.google.com/p/gdata-java-client/downloads/list
- 下载最新版本的客户端库 (
gdata-src.java-1.x.x.java.zip) 和示例 (gdata-samples.java-1.x.x.java.zip)。 - 将客户端库来源提取到您的计算机上。
- 找到
gdata/java/build-src/build.properties并打开相应文件。 - 修改外部依赖项，使其指向本地机器上
.jar文件的位置。
注意：在 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 等热门工具。下面是一些可能对您有用的其他链接：
- GData Java 客户端库主页
- Google Data API 列表
- 以下 Google Data API 提供 Java 开发者指南：
- 在阴影中编码：将 Eclipse 与 Google Data API 搭配使用
- Google Data API Java 客户端 Eclipse 插件
如果您在使用 Java 客户端库时遇到任何 API 相关问题，可以在特定 API 的论坛中发帖告知我们。