HOME / Docs & Support / NetBeans 6.0 / Java EE Documentation

Tomcat 中的 REST 风格的 Web 服务入门指南

代表性状态传输 (REpresentational State Transfer, REST) 是一种用于分布式超媒体系统（如万维网）的体系结构样式。REST 风格的体系结构的核心概念是由统一资源标识符 (Uniform Resource Identifier, URI) 标识的资源。可以使用标准接口（如 HTTP）来处理这些资源以及使用这些资源的表示形式来交换信息。

在 GlassFish 中的 REST 风格的 Web 服务入门指南教程中，您首先学习了有关 REST 的一些知识，然后学习了 NetBeans IDE 6.0 如何支持此体系结构样式。为简单起见，该教程是专门针对 GlassFish 应用服务器的。要在 Tomcat 服务器上运行 REST 风格的 Web 服务，您需要执行一些其他配置任务。本教程使用与 GlassFish 中的 REST 风格的 Web 服务入门指南相同的源代码，并为您介绍如何将它们部署到 Tomcat 应用服务器。

简介
将库复制到 Tomcat
通过数据库生成实体类
将 Toplink 库添加到项目
生成基于实体类的 REST 风格的 Web 服务
配置持久性文件
测试 REST 风格的 Web 服务
添加 Google 地图功能

要学习本教程，您需要具备以下软件和资源。

软件或资源	要求的版本
NetBeans IDE	Web & Java EE 版本 6.0
Java Development Kit (JDK)	版本 6 或版本 5
Tomcat Web Server	版本 6.0

Tomcat 可以随同 NetBeans IDE 的 Web 和 Java EE 分发一起安装。此外，也可以访问 Apache Tomcat 下载页。

本教程还需要 REST 风格的 Web 服务插件。在 IDE 中，转至“工具”菜单下的插件管理器，在“已安装”标签下检查是否已安装“REST 风格的 Web 服务”插件。如果未安装，请从“可用插件”标签中安装它，如下所示：

简介

REST 风格的 Web 服务是使用 REST 风格的体系结构样式构建的服务。由于其轻量的特性并且支持直接通过 HTTP 传输数据，使用 REST 风格的方法构建 Web 服务作为一种新兴趋势已经开始替代传统的 Web 服务构建方式，即使用基于 SOAP 的技术在 Internet 上部署服务。

IDE 支持使用 JSR 311 - Java API for RESTful Web Services (JAX-RS) 和 Jersey（JAX-RS 的引用实现）快速开发 REST 风格的 Web 服务。

有关详细信息，请参见以下内容：

除了支持构建 REST 风格的 Web 服务之外，IDE 还支持测试、构建可访问 REST 风格的 Web 服务的客户端应用程序，以及生成用于调用 Web 服务（REST 风格和基于 SOAP）的代码。

下面是 IDE 提供的 REST 风格的功能列表：

通过 JPA 实体类和模式快速创建 REST 风格的 Web 服务。
通过从 REST 风格的组件面板中拖放组件，快速生成用于调用各种 Web 服务（如 Google 地图、Yahoo 新闻搜索和 StrikeIron Web 服务）的代码。
通过 REST 风格的 Web 服务生成 JavaScript 客户端桩模块，用于构建 REST 风格的客户端应用程序。
生成测试客户端，用于测试 REST 风格的 Web 服务。
提供可轻松浏览项目中 REST 风格的 Web 服务实现类的逻辑视图。

在使用本教程之前，您应使用 GlassFish 中的 REST 风格的 Web 服务入门指南，其中介绍了 IDE 如何支持生成、实现和测试 REST 风格的 Web 服务。本教程演示了同一服务，但需要一些其他配置步骤才能在 Tomcat 6.0+ 应用服务器上运行。

将库复制到 Tomcat

Tomcat 需要一组 toplink、derby 和 javax API 才能支持 REST 风格的 Web 服务。这些库不但对本教程有用，而且可让您以后在 Tomcat 上运行 REST 风格的服务。

在下表中，NB_HOME 指 Netbeans 安装目录，TOMCAT_HOME 指 Apache Tomcat 6.x 安装目录，GLASSFISH_HOME 指 Glassfish v2 安装目录。

在复制这些库之后，重新启动计算机。

源目录	库文件	目标目录
`NB_HOME/java_n/modules/ext/toplink`	toplink-essentials.jar toplink-essentials-agent.jar	`TOMCAT_HOME/lib`
`NB_HOME/java_n/modules/ext/jaxws/api`	所有 JAR 文件	`TOMCAT_HOME/endorsed` 如果此目录不存在，请创建它。
`GLASSFISH_HOME/javadb/lib`	derbynet.jar derbyclient.jar	`TOMCAT_HOME/lib`

通过数据库生成实体类

本练习的目标是创建一个项目，并通过数据库生成实体类。

通过数据库创建实体类：

选择“文件”>“新建项目”。在“类别”下选择 "Web"。在“项目”下，选择“Web 应用程序”，然后单击“下一步”。
在“项目名称”下，输入 CustomerDB-Tomcat。
在“服务器”下，选择 Apache Tomcat 6.0.x，单击“完成”。
右键单击 CustomerDB-Tomcat 节点，并选择“新建”>“通过数据库生成实体类”。“新建通过数据库生成实体类”向导将在“数据库表”面板中打开。
在“数据库表”面板中，从“数据源”下拉字段中选择“新建数据源”。这将打开“创建数据源”对话框。
在“JNDI 名称”字段中，键入 jdbc/sample。从“数据库连接”下拉字段中，选择 jdbc:derby://hostname:1527/sample [APP 上的 app]，如下图所示。单击“确定”。对话框关闭并返回到“数据库表”面板。
在“可用表”下，选择 "CUSTOMER"，然后单击“添加”。与 CUSTOMER 表关联的 DISCOUNT_CODE 表也会被自动添加到“选定表”列表中。您现在应该看到下面的屏幕：
单击“下一步”。这将打开“实体类”面板。
在“包”下键入 customer.db.tomcat。
单击“创建持久性单元”。这将打开“创建持久性单元”对话框。接受所有缺省值并单击“创建”。您将返回到“实体类”面板。单击“完成”。
查看“项目”窗口。您现在应该看到下面的屏幕：

将 Toplink 库添加到项目

尽管已将 Toplink 文件添加到了 Tomcat（请参见将库复制到 Tomcat），但仍需要将 TopLink Essentials 库添加到您的项目中，以避免类的强制类型转换异常。您必须在 REST 库的上方添加此库。

右键单击您的项目节点，并从上下文菜单中选择“属性”。这将打开“项目属性”对话框。
在“类别”视图中选择“库”。将打开一个标签，其中显示项目的编译时库。
单击“添加库”。这将打开“添加库”对话框，其中显示一个可用库列表。
滚动查看库列表找到 TopLink Essentials 库。选择该库并单击“添加库”。
现在应回到“项目属性”对话框。TopLink Essentials 应列在编译时库中。请确保选中了“包”框。选择 TopLink 库，并通过单击“上移”将其移至库列表顶部。编译时库列表应如下图所示：
单击“确定”。IDE 会将 TopLink Essentials 添加到项目库的顶部。要检查 TopLink Essentials 库是否存在，请展开项目的“库”节点。库列表应如下图所示：
重新启动 IDE 使更改生效。在重新启动 IDE 后，重新启动 Derby 数据库服务器（“工具”>“Java DB 数据库”>“启动服务器”）。

配置持久性文件

在通过数据库生成实体类中，您创建了一个持久性单元。该持久性单元的配置存储在 persistence.xml 文件中。在“项目”视图中，可以在项目的“配置文件”节点中找到 persistence.xml。

您需要更改此持久性文件，以便使用不同的事务类型，不标识数据源以及将必要的属性传递到持久性提供程序。在 IDE 中打开 persistence.xml。打开 "XML" 标签。编辑该文件，使之匹配以下代码片段（您添加或更改的部分以粗体表示）：

<persistence-unit name="CustomerDB-TomcatPU" transaction-type="RESOURCE_LOCAL">
    <provider>oracle.toplink.essentials.PersistenceProvider</provider>

    <!-- <jta-data-source>jdbc/sample</jta-data-source> --> 

    <properties>
      <property name="toplink.jdbc.user" value="app"/>
      <property name="toplink.jdbc.password" value="app"/>
      <property name="toplink.jdbc.url" value="jdbc:derby://localhost:1527/sample"/>
      <property name="toplink.jdbc.driver" value="org.apache.derby.jdbc.ClientDriver"/>
    </properties>
        </persistence-unit>

生成基于实体类的 REST 风格的 Web 服务

本练习的目标是基于我们之前生成的实体类构建 REST 风格的 Web 服务（请参见通过数据库生成实体类）。

右键单击包含实体类的包，然后选择“新建”>“基于实体类的 REST 风格的 Web 服务”。这将打开“新建基于实体类的 REST 风格的 Web 服务”向导。
在“可用的实体类”字段中，您应看到 Customer 和 DiscountCode 这两个类。单击“全部添加”，它们将移动到“选定的实体类”中。
单击“下一步”，将打开“生成的类”面板。

可以在此处看到 IDE 将为您生成的所有内容。IDE 使用容器条目模式来生成资源类。例如，对于 Customer 实体类，IDE 将生成一个名为 CustomersResource 的容器资源和一个名为 CustomerResource 的条目资源。而且，对于每个资源类，IDE 将生成一个用于从相应的实体实例生成资源表示的转换器类，如 CustomersConverter 和 CustomerConverter。此外，还有一个用于表示关系的调用引用转换器的转换器类，如 CustomerRefConverter。
接受缺省值，然后单击“完成”。
查看“项目”窗口。您现在应该看到下面的屏幕：

“项目”窗口中“REST 风格的 Web 服务”节点显示您项目中所有 REST 风格的 Web 服务。方括号中的值（如 [/customers/]）是 URI 模板的值。您还可以通过双击此节点定位到源文件。该视图还显示了所有 HTTP 方法和子资源定位器方法。同样，您也可以通过双击节点定位到方法。

至此，实体类和 REST 风格的 Web 服务已生成，接下来该测试应用程序了。IDE 提供了一个用于测试 REST 风格的 Web 服务的有用实用程序。我们将会在下一节中用到它。

测试 REST 风格的 Web 服务

本练习的目标是试验我们的应用程序。

右键单击该项目节点，并选择“测试 REST 风格的 Web 服务”。
服务器启动，应用程序部署。最后，浏览器应显示我们的应用程序以及每个 Web 服务的链接：

左侧是根资源集，这里它们被命名为 customers 和 discountCodes。

首先选择 customers 根资源。单击“方法”下拉列表并选择 GET(application/xml) 或 GET(application/json)。单击“测试”。结果将显示在“测试输出”部分：

“测试输出”部分共有 4 个标签。“表格视图”是一个平面视图，它显示生成文档中的所有 URI，您可以通过单击这些链接进行导航。“原始视图”显示返回的实际数据。根据您选择的 mime 类型（application/xml 或 application/json），显示的数据将分别为 XML 或 JSON 格式。“头”标签显示 HTTP 头信息。还有一个名为“HTTP 监视器”的标签，它显示发送和接收的实际 HTTP 请求和响应。

退出浏览器并返回到 IDE。

添加 Google 地图功能

本练习的目标是将 Google 地图功能添加到 REST 风格的 Web 服务。

在编辑器中打开 CustomerResource 类，如下图所示。在“工具”菜单下，选择“组件面板”。注意到编辑器的右侧将显示一个组件面板，其中包含一些代码片段：
请在以下位置注册获取 Google 地图密钥：http://www.google.com/apis/maps/signup.html。Google 地图密钥请求对话框中有一个字段需要输入您网站的 URL。在该字段中键入 http://localhost:8080。

从 "Google" 类别中，拖动“地图”项并将其放在类中的任何位置。这将打开定制 Google 地图对话框。在 "apiKey" 字段中输入 Google 地图密钥，如下图所示：

单击“确定”。IDE 将创建 GoogleMapResource 类。CustomerResource 类使用 IDE 另外创建的以下方法访问该类：

    /**
     * Returns GoogleMapResource sub-resource.
     */
    @Path("googleMap/")
    public GoogleMapResource getGoogleMap() {
        try {
            customer.db.tomcat.Customer entity = getEntity();
            String apiKey = null;
            String address = entity.getAddressline1();
            Integer zoom = null;
            return new GoogleMapResource(apiKey, address, zoom);
        } finally {
            PersistenceService.getInstance().close();
        }
    }

右键单击该项目节点，再次选择“测试 REST 风格的 Web 服务”，然后在浏览器再次打开后单击 googleMap。您应看到下图，其中已填充 apiKey：
单击“测试”按钮。注意到 Google 地图将在“原始视图”标签中打开：
重要说明：在 Firefox 2 中，测试客户端在尝试生成图像时将永远挂起。单击“资源:” 下的 http:.../googleMap/ URL，地图图像将显示在新的浏览器标签中。