Stephanie Liu,Google Data API 团队
2007 年 9 月
- 简介
- 安装依赖项
- 在 Windows 上
- 在 Mac OS X 上
- 在 Linux 设备上
- 安装 Google Data 客户端库
- 运行示例
- 构建自己的应用
- 总结
- 附录:设置环境变量
简介
刚开始使用不熟悉的 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。
在 Windows 上
适用于 Windows 操作系统的说明。
安装 Java
Sun 以 JDK(Java 开发工具包)的形式提供 Java 开发软件包。其中包含 JRE(Java 运行时环境)以及编写、编译、测试和调试 Java 应用所需的一切。如果您已安装 Java,请跳至安装 Ant。
注意:您需要拥有管理员权限才能安装 JDK。
- 访问 http://java.sun.com/javase/downloads/index.jsp
- 点击最新更新旁边的“下载”。
- 阅读并接受许可协议。
- 下载某个 Windows 安装文件。
- 运行安装程序。
- 修改
Path
环境变量,以便轻松运行 javac
等 JDK 可执行文件。您要添加的路径应类似于 C:\jdk\bin\
。如需了解如何在 Windows 中修改 Path
变量,请参阅附录。
如果您在安装 JDK 时遇到任何问题,请查看 Sun 网站上的详细安装说明。
安装 Ant
Apache Ant 是一款类似于 make
(但更好)的 Java 构建工具。您将使用它来构建库并执行示例。如果您已安装 Ant,请检查其版本是否为 1.7 或更高版本。
- 依次点击“开始”菜单和“运行”。
- 在文本字段中输入
cmd
。
- 在提示中输入
ant -version
,即可查看您使用的版本。
如果您使用的是 1.7 及更高版本,请直接跳到获取 mail.jar
。如果您的 Ant 版本低于 1.7 或您未安装 Ant,请按以下步骤操作。
- 访问 http://ant.apache.org/bindownload.cgi
- 点击
.zip
下载的下载链接。
- 将所有文件解压缩到所选位置,例如
C:\ant
- 将 ant
bin
目录(例如 C:\ant\bin
)添加到 Path
环境变量中。
- 添加或修改
ANT_HOME
环境变量,将其设置为新位置,例如 C:\ant
- 添加或修改
JAVA_HOME
环境变量,使其指向 Java 的安装位置,例如 C:\jdk
。
如果您遇到任何问题,可以在 Ant 的网站上找到详细的安装说明。
获取 mail.jar
包含 JavaMail API 以支持媒体。
- 访问 http://java.sun.com/products/javamail/downloads/index.html
- 点击“下载”按钮。确保您下载的是 1.4 版或更高版本。
- 阅读并接受许可协议。
- 点击包含 JavaMail 的
.zip
文件的链接。
- 将文件解压缩到您的计算机,并记下相应位置。
mail.jar
将位于根目录 javamail-(version)
下
获取 activation.jar
包含 JavaBeans Activation Framework 以提供媒体支持。
- 访问 JAF 下载页面。
- 点击“下载”按钮。
- 阅读并接受许可协议。
- 点击包含 Activation Framework 的
.zip
文件的链接。
- 将文件解压缩到您的计算机,并记下相应位置。
activation.jar
将位于根目录 jaf-(version)
下
获取 servlet.jar
servlet.jar
(可能称为 servlet-api.jar
)可在 servlet 容器(J2EE、Tomcat、WebLogic 等)中找到。它用于 AuthSub 和 Google Base 示例。以下说明介绍了如何获取 Tomcat 6.x。
- 访问 http://tomcat.apache.org/download-60.cgi
- 点击“核心二进制分发”下的“Windows 服务安装程序”下载链接。
- 运行安装程序。
- 如果您保留默认设置,
servlet-api.jar
应位于 C:\Program Files\Apache Software Foundation\Tomcat 6.0\lib
如需查看更多 Tomcat 设置和安装文档,请点击此处。
好了,现在您可以安装 GData Java 客户端库了。
在 Mac OS X 上
Mac OS X 操作系统的说明。
安装 Java
如果您使用的是 Mac OS X,则需要完成的工作更少!Apple 已在每个实例中包含一个完全配置且可随时使用的 JDK(Java 开发工具包)。如需了解详情,请访问 Apple 的 Java 网站。
安装 Ant
Apache Ant 是一款类似于 make
(但更好)的 Java 构建工具。您将使用它来构建库并执行示例。您可能已经安装了 Ant,但请检查您安装的版本是否为 1.7 或更高版本。
- 打开一个终端窗口。(按 Command + 空格键,然后输入“终端”以查找该应用)
- 在命令提示符处,输入:
ant -version
如果您运行的 ant 版本低于 1.7,请按以下步骤操作以获取最新版本。
- 访问 http://ant.apache.org/bindownload.cgi
- 点击
.zip
下载的下载链接。
- 打开一个终端窗口。(按 Command + 空格键,然后输入“终端”以查找该应用)
- 在命令提示符处,输入以下内容:
cd ~/Desktop
sudo sh
mv apache-ant-(version)-bin.zip /usr/local/
cd /usr/local/
unzip apache-ant-(version)-bin.zip
chown (your account name):(your account name) apache-ant-(version)
ln -s apache-ant-(version) ant
如果您遇到任何问题,可以在 Ant 的网站上找到详细的安装说明。这篇博文还详细说明了上述 shell 命令的含义。
获取 mail.jar
包含 JavaMail API 以支持媒体。
- 访问 http://java.sun.com/products/javamail/downloads/index.html
- 点击“下载”按钮。确保您下载的是 1.4 版或更高版本。
- 阅读并接受许可协议。
- 点击包含 JavaMail 的
.zip
文件的链接。
- 将文件解压缩到您的计算机,并记下相应位置。
mail.jar
将位于根目录 javamail-(version)
下
获取 activation.jar
包含 JavaBeans Activation Framework 以提供媒体支持。
- 访问 JAF 下载页面。
- 点击“下载”按钮。
- 阅读并接受许可协议。
- 点击包含 Activation Framework 的
.zip
文件的链接。
- 将文件解压缩到您的计算机,并记下相应位置。
activation.jar
将位于根目录 jaf-(version)
下
获取 servlet.jar
servlet.jar
(可能称为 servlet-api.jar
)可在 servlet 容器(J2EE、Tomcat、WebLogic 等)中找到。它用于 AuthSub 和 Google Base 示例。以下说明介绍了如何获取 Tomcat 6.x。
- 访问 http://tomcat.apache.org/download-60.cgi
- 点击“核心二进制分发”下的
.zip
下载。
- 将文件解压缩到您的计算机,并记下相应位置。
servlet.jar
将位于 apache-tomcat-(version)/lib
下
如需查看更多 Tomcat 设置和安装文档,请点击此处。
好了,现在您可以安装 GData Java 客户端库了。
在 Linux 上
适用于 Linux 操作系统的说明。
安装 Java
本教程将使用 Sun 的 JDK(Java 开发工具包)。如果您拥有 root 访问权限,请按照以下说明操作。如果不是,您可以按照这些说明在主目录中安装 JDK。如果您已安装 JDK 1.5 及更高版本,请跳至安装 Ant。
如果您拥有 root 权限:
- 访问 http://java.sun.com/javase/downloads/index.jsp
- 点击最新版本旁边的“下载”。
- 阅读并接受许可协议。
- 点击并下载“Linux 平台”下的 RPM 文件自解压文件。
- 打开终端窗口,切换到下载文件的目录,然后执行以下操作:
su
chmod a+x jdk-6(version)-linux-i586-rpm.bin
./jdk-6(version)-linux-i586-rpm.bin
- 同意许可协议。
如果您没有 root 权限:
- 访问 http://java.sun.com/javase/downloads/index.jsp
- 点击最新版本旁边的“下载”。
- 阅读并接受许可协议。
- 点击并下载“Linux 平台”下的自解压 build(而非 RPM)。
- 打开终端窗口,切换到下载文件的目录,然后输入以下命令:
chmod +x jdk-6(version)-linux-i586-rpm.bin
- 切换到您要安装文件的目录。
- 运行自解压二进制文件。如果您要在当前目录中安装,只需输入
./jdk-6(version)-linux-i586-rpm.bin
- 同意许可协议。
如果您遇到问题,可以点击此处查看更详细的安装说明。
安装 Ant
GData Java 客户端库需要 Ant 1.7 或更高版本。如果您已安装 Ant,请在命令提示符下输入 ant -version
,检查版本。如果您需要获取最新版本,或者尚未安装该应用,请按照以下说明操作。如果已设置好 Java 和 Ant 安装,请直接跳到获取 mail.jar
。
- 访问 http://ant.apache.org/bindownload.cgi
- 点击
.tar.gz
下载的下载链接。
- 如需提取文件,请打开终端窗口,将目录更改为下载文件的目录,然后输入以下命令:
gunzip apache-ant-(version)-bin.tar.gz
tar xvf apache-ant-(version)-bin.tar
- 将 ant
bin
目录添加到 PATH
环境变量。
- 添加或修改
ANT_HOME
环境变量,将其设置为新位置。
- 添加或修改
JAVA_HOME
环境变量,将其设置为 JDK 的安装位置。
如果您遇到任何问题,可以点击此处查看详细的 Ant 安装文档。
获取 mail.jar
包含 JavaMail API 以支持媒体。
- 访问 http://java.sun.com/products/javamail/downloads/index.html
- 点击“下载”按钮。确保您下载的是 1.4 版或更高版本。
- 阅读并接受许可协议。
- 点击包含 JavaMail 的
.zip
文件的链接。
unzip
文件到您的计算机,并记下相应位置。mail.jar
将位于根目录 javamail-(version)
下
获取 activation.jar
包含 JavaBeans Activation Framework 以提供媒体支持。
- 访问 JAF 下载页面。
- 点击“下载”按钮。
- 阅读并接受许可协议。
- 点击包含 Activation Framework 的
.zip
文件的链接。
unzip
文件到您的计算机,并记下相应位置。activation.jar
将位于根目录 jaf-(version)
下
获取 servlet.jar
servlet.jar
(可能称为 servlet-api.jar
)可在 servlet 容器(J2EE、Tomcat、WebLogic 等)中找到。它用于 AuthSub 和 Google Base 示例。以下说明介绍了如何获取 Tomcat 6.x。
- 访问 http://tomcat.apache.org/download-60.cgi
- 下载“核心二进制文件分发”下的
.tar.gz
文件。
- 使用
gunzip
和 tar
解压缩下载内容,如上文的安装 Ant 部分所示。
servlet.jar
将位于 apache-tomcat-(version)/lib
下
现在,您应该已具备获取 GData Java 客户端库所需的一切条件!
安装 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 等热门工具。下面是一些可能对您有用的其他链接:
如果您在使用 Java 客户端库时遇到任何 API 相关问题,可以在特定 API 的论坛中发帖告知我们。
附录:设置环境变量
有关在 Windows 或 Linux 上设置环境变量的说明。您无需为 Mac OS X 设置任何内容。
Windows
系统变量将应用于计算机上的所有用户。如果您因没有管理员权限而无法修改系统变量,请按照此处的说明操作。
如果您拥有管理员权限:
- 右键点击“我的电脑”,然后选择“属性”。
- 点击“高级”标签页。
- 点击“环境变量”。
- “添加”或“修改”系统变量:(替换为本地机器上的位置)
- 添加或修改
ANT_HOME
并将值设置为 C:\ant
- 添加或修改
JAVA_HOME
并将值设置为 C:\jdk
- 添加或修改
Path
,并在末尾附加 ;C:\ant\bin;C:\jdk\bin
(分号用于分隔目录路径)
- 添加或修改
CLASSPATH
,并根据您要使用的服务附加所需的 .jar
文件。确保包含“.”&mhash; 这表示当前目录。.;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar
等。
- 重新启动以确保这些更改生效。
注意:请确保变量不包含引号(单引号或双引号),并且不以“\”或“/”结尾。
如果您没有管理员权限:
- 右键点击“我的电脑”,然后选择“属性”。
- 点击“高级”标签页。
- 点击“环境变量”。
- “添加”或“修改”用户变量:(替换为本地计算机上的位置)
- 添加或修改
ANT_HOME
并将值设置为 C:\ant
- 添加或修改
JAVA_HOME
并将值设置为 C:\jdk
- 添加或修改
Path
,并在末尾附加 ;C:\ant\bin;C:\jdk\bin
(分号用于分隔目录路径)
- 添加或修改
CLASSPATH
,并根据您要使用的服务附加所需的 .jar
文件。确保包含“.”&mhash; 这表示当前目录。.;C:\gdata\java\lib\gdata-core-1.0.jar;C:\gdata\java\lib\gdata-calendar-1.0.jar
等。
- 重新启动以确保这些更改生效。
注意:请确保变量不包含引号(单引号或双引号),并且不以“\”或“/”结尾。
您刚刚修改的用户变量将仅应用于您的用户个人资料。
Linux
- 在您选择的编辑器中打开位于主目录中的
.bash_profile
文件。
- 将以下内容添加到
.bash_profile
中,并替换为您机器上文件的实际位置:
export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk
export PATH=${PATH}:${ANT_HOME}/bin
- 您需要添加将要使用的服务的
.jar
文件。例如 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
来确定变量
注意:请确保变量不包含引号(单引号或双引号),并且不以“\”或“/”结尾。