HOME / Docs & Support / NetBeans 6.5

REST Web 服务入门

代表性状态传输（REpresentational State Transfer，REST）是一种专门针对分布式超媒体系统的体系结构样式，比如说万维网（World Wide Web）。REST架构的中心思想就是通过统一资源标识符（URI）来识别资源。可以使用标准接口（比如说HTTP）来操作这些资源，并且可以使用这些资源的表示来交换信息。在本教程中，我们首先将学习一些关于REST的知识，然后将讨论 NetBeans IDE 6.0 对这种体系结构风格的支持。

本教程所需要的软件

开始之前，需要在您的计算机上下载并安装以下软件：

NetBeans IDE 6.0 Web & Java EE（下载）。
Java Standard Development Kit（JDK）版本 5.0 或以上（下载）。
Glassfish V2 或 Tomcat Web Server，两者都可在 NetBeans IDE 6.0 安装程序中选择安装。
在 IDE 中，打开 Tools 菜单中的 Plugin Manager，然后安装 RESTful Web 服务插件，如下图所示：

简介

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

IDE 支持使用 JSR 311（Java API for RESTful Web Services，JAX-RS）和 Jersey（JAX-RS 的参考实现）快速开发 REST Web 服务。

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

除了构建 REST Web 服务之外，IDE 还支持测试和构建可访问 REST Web 服务的客户机应用程序，并可生成调用 Web 服务的代码（同时支持 REST 和基于 SOAP 的 Web 服务）。

下面列出了 IDE 所提供的 REST 特性：

通过 JPA 实体类和模式快速创建 REST Web 服务。
通过拖放 REST 组件面板中的组件快速生成可调用各种 Web 服务的代码，比如说 Google Map、Yahoo News Search 和 StrikeIron Web 服务。
通过 REST Web 服务生成 JavaScript 客户桩（client stub），用于构建 REST 客户机应用程序。
生成测试客户机用于测试 REST Web 服务。
通过逻辑视图方便地导航到项目中的 REST Web 服务实现类。

在本教程中，我们将介绍如何通过 IDE 生成、实现和测试 REST Web 服务。

通过数据库生成实体类

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

选择 File > New Project 选项。在 Categories 列表中，选择 Web 选项。在 Projects 列表中，选择 Web Application 选项并单击 Next 按钮。
在 Project Name 字段中，输入 CustomerDB。
在 Server 列表中，选择一个服务器，如 GlassFish。单击 Finish 按钮。
右键单击 CustomerDB 节点，然后选择 New > Entity Classes from Database 选项，如下图所示：

另一种方法是在 New File 向导（Ctrl-N）中从 Persistence 列表中选择它，如下图所示：

新实体向导 1

单击 Next 按钮。

在 Database Tables 面板中，选择 jdbc/sample 数据源。接下来，在 Available Tables 列表中，选择 CUSTOMER 选项并单击 Add 按钮。DISCOUNT_CODE 表（该表与 CUSTOMER 表有一定的关系）将自动添加到 Selected Tables 列表中。IDE 应如下所示：

单击 Next 按钮。
在 Package 字段中，输入 customerdb。IDE 应如下所示：
单击 Create Persistence Unit 按钮。将出现以下对话框：

单击 Create 按钮，然后单击 Finish 按钮。
查看 Projects 窗口。IDE 应如下所示：

通过实体类生成 REST Web 服务

本练习的目标是使用在上一节中生成的实体类来生成 REST Web 服务。

右键单击含有实体类的包，然后选择 New > RESTful Web Services from Entity Classes 选项，如下图所示：
在 New RESTful Web Services from Entity Classes 向导中，单击 Add All 按钮。此时，IDE 应如下所示：

单击 Next 按钮。
在下一个面板中，保留各选项为默认值，如下图所示：

在该界面中，我们可以看到 IDE 将生成的一切内容。IDE 将使用容器-项目模式生成资源类。比如说，对于 Customer 实体类，IDE 将生成一个 CustomersResource 资源类，并生成一个 CustomerResource 项目资源。此外，对于各个资源类，IDE 将生成一个转换器类用于通过相应的实体实例生成资源表示，比如说 CustomersConverter 和 CustomerConverter。而且，另外还有一个称作引用转换器的转换器类（比如说 CustomerRefConverter），可用于表示关系。

单击 Finish 按钮。
查看 Projects 窗口。此时，IDE 应如下所示：

Projects 窗口中的 RESTful Web Services 节点将显示项目中的所有 REST Web 服务。方括号中间的值，比如说 [/customers/]，表示 URI 模板的值。通过双击此节点还可以导航到源代码文件。该视图还显示了所有的 HTTP 方法和子资源定位器（Sub-resource locator）方法。还是一样，通过双击这些节点可以导航各个方法。

我们已经生成了实体类和 REST Web 服务。接下来，我们将测试应用程序。IDE 提供了一个极具实用性的工具，用于测试 REST Web 服务。我们将在下一节中演示该工具的使用。

测试 REST Web 服务

本练习的目标是测试刚才所创建的应用程序。

右键单击项目节点，然后选择 Test RESTful Web Services 选项，如下图所示：

此时将会启动服务器并部署应用程序。最后，应用程序应该显示在浏览器中，其中含有各个 Web 服务的链接：

位于页面左侧的是根资源集合。在本例中，它们的名称为 customers 和 discountCodes。

首先，选择一个根资源，比如说 customers。单击 Methods 下拉列表并选择 GET(application/xml) 或 GET(application/json) 选项。单击 Test 按钮。测试结果将显示在 Test Output 部分中：

Test Output 区域含有 4 个选项卡。Tabular View 是一个平面视图，其中显示了结果文档中的所有 URI。通过单击这些链接可以导航到结果文档中的相应位置。Raw View 视图将显示返回的实际数据。根据所选择的 Mime 类型（application/xml 或 application/json），所显示的数据将分别采用 XML 或 JSON 格式。Headers Tab 将显示 HTTP 报头信息。另一个选项卡是 HTTP Monitor，它显示所发送和接收到的 HTTP 请求及响应。

退出浏览器并返回 IDE。

添加 Google Map 功能

本练习的目标是在我们的 REST Web 服务中添加 Google 地图功能。

在编辑器中打开 CustomerResource ，如下图所示：在 Tools 菜单下面，选择 Palette 选项。注意，编辑器右侧将出现一个选项板，其中含有一些代码片段：
注册并获取一个 Google 地图 Key，地址为 http://www.google.com/apis/maps/signup.html。
在 Google 类别中，将 Map 项目拖动到类的任意位置，然后在 apiKey 字段中输入 Google Map Key，如下所示：

单击 OK 按钮。

IDE 将创建一个 GoogleMapResource 类。CustomerResource 类将使用下面这个方法访问它，该方法也是由 IDE 创建的：

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

右键单击项目节点，然后再次选择 Test RESTful Web Services 选项。当浏览器打开后，单击 googleMap 按钮。应该可以看到以下界面，其中填入了 apiKey。
单击 Test 按钮。注意到 Google 地图将在 Raw View 选项卡中打开：

当您单击某个 Google 地图链接时，将会显示相同的地址。其原因是，该地址是直接硬编码在 GoogleMapResource 类中的。现在，我们将修改先前在 CustomerResource 类中查看的生成方法：

@UriTemplate("googleMap/")
public GoogleMapResource getGoogleMap(@UriParam("customerId")
Integer id) {
    try {
        customerdb.Customer entity = getEntity(id);
        String apiKey = null;
        String address = entity.getAddressline1();
        Integer zoom = null;
        return new GoogleMapResource(apiKey, address, zoom);
    } finally {
        PersistenceService.getInstance().close();
    }
}

将它修改为以下内容：

@UriTemplate("googleMap/")
public GoogleMapResource getGoogleMapResource(
        @UriParam("customerId") Integer id) {
    Customer c = getEntity(id);
    String address = c.getAddressline1() + " " + c.getAddressline2() +
            " " + c.getCity() + " " + c.getState() + " " + c.getZip();
    String mapKey = "abcdef";
    Integer zoom = null;
    return new GoogleMapResource(mapKey, address, zoom);
}

以上代码将提取客户实体（customer entity）中的信息，并将其传递给 GoogleMapResource 实例。

再次测试应用程序。这次，单击左侧栏中的 customers，而不是 googleMap。选择一个输入方法（Input Method）。单击 Test 按钮。单击 /customers/1/ 按钮。单击 Test 按钮。现在，我们已经有了两个链接：一个用于折扣代码（discount code），另一个用于 Google 地图。单击 Google Map 链接，然后再次单击 Test 按钮。注意到，这次将返回正确的 Google 地图条目给用户：