REST 风格的 Web 服务入门指南
代表性状态传输 (REpresentational State Transfer, REST) 是一种用于分布式超媒体系统（如万维网）的体系结构样式。REST 风格的体系结构的核心概念是由统一资源标识符 (Uniform Resource Identifier, URI) 标识的资源。可以使用标准接口（如 HTTP）来处理这些资源以及使用这些资源的表示形式来交换信息。在本教程中，将首先了解一些关于 REST 的知识，然后演示 NetBeans IDE 是如何支持这种体系结构样式的。
目录
要学习本教程，您需要具备以下软件和资源。
Tomcat 和 GlassFish 都可以随同 NetBeans IDE 的 Web 和 Java EE 分发一起安装。此外，也可以访问 GlassFish 下载页或 Apache Tomcat 下载页。
简介
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 服务实现类的逻辑视图。
- (NetBeans IDE 6.5) 完全集成的 Spring Framework，提供 Spring 事务处理。
在本教程中，将介绍 IDE 如何支持生成、实现和测试 REST 风格的 Web 服务。
通过数据库生成实体类
本练习的目标是创建一个项目，并通过数据库生成实体类。
- 选择“文件”>“新建项目”。在“类别”下，选择 "Java Web"。在“项目”下选择“Web 应用程序”，然后单击“下一步”。
- 在“项目名称”字段中，输入 CustomerDB。单击“下一步”。
- 在“服务器”下，选择 GlassFish。单击其余选项，然后单击“完成”。
- 打开“服务”标签。在“数据库”列表中，右键单击 "Java DB" 并启动它。
- 右键单击 "CustomerDB" 节点并选择“新建”>“通过数据库生成实体类”。或者，可以在“新建文件”向导（Ctrl-N）的“持久性”类别中选择它。
注意：在 NetBeans IDE 6.5 中，可以在一个向导中生成实体类和 REST 风格的 Web 服务。选择“新建”>“Web 服务”>“基于数据库的 REST 风格的 Web 服务”（而不是选择“新建”>“通过数据库生成实体类”）。按照本操作过程的余下部分以及生成基于实体类的 REST 风格的 Web 服务中所述的步骤执行操作。“新建 - 通过数据库生成实体类”向导的“生成的类”步骤对应于“生成基于实体类的 REST 风格的 Web 服务”的步骤 3。但是，如果按本教程所述单独生成实体类和 REST 风格的 Web 服务，则可以更详细地了解此过程的工作方式。
- 在“数据库表”面板中，从“源”下拉菜单中选择 jdbc/sample 数据源。
注意：在 Tomcat 上，此数据源可能不存在。在本例中，从“数据源”下拉列表中选择“新建数据源”。这将打开“创建数据源”对话框。在“JNDI 名称”字段中键入 jdbc/sample。从“数据库连接”下拉列表中，选择 jdbc:derby://hostname:1527/sample [APP 上的 app]。单击“确定”。对话框关闭并返回到“数据库表”面板。另请参见 NetBeans IDE 6.0 教程：Tomcat 上的 REST 风格服务。
- 在“可用表”下，选择 "CUSTOMER"，然后单击“添加”。DISCOUNT_CODE 表（与 CUSTOMER 表有关联）将自动添加到“选定表”列表中。现在您应该看到以下内容：
单击“下一步”。
- 在“包”字段中，输入 customerdb。现在您应该看到以下内容：
- 单击“创建持久性单元”。此时将显示以下对话框：
单击“创建”。您将返回到“实体类”窗格。单击“完成”，IDE 将创建实体类。
注意：在本教程中，跳过了可选的“映射选项”窗格，在此窗格中可更改用于映射集合的缺省标注。
- 查看“项目”窗口。现在您应该看到以下内容：
生成基于实体类的 REST 风格的 Web 服务
本练习的目标是通过在上一节中生成的实体类来生成 REST 风格的 Web 服务。
- 右键单击包含实体类的包，然后选择“新建”>“基于实体类的 REST 风格的 Web 服务”。
- 在“新建基于实体类的 REST 风格的 Web 服务”向导中，单击“全部添加”。当实体类在“选定的实体类”字段中显示后，单击“下一步”。将打开“生成的类”面板。
- 在“资源包”字段中键入 customerdb.service，在“转换器包”字段中键入 customerdb.converter。接受其他所有缺省设置，如下所示：
可以在此处看到 IDE 将为您生成的所有内容。IDE 使用容器条目模式来生成资源类。例如，对于 Customer 实体类，IDE 将生成一个名为 CustomersResource 的容器资源和一个名为 CustomerResource 的条目资源。而且，对于每个资源类，IDE 将生成一个用于从相应的实体实例生成资源表示的转换器类，如 CustomersConverter 和 CustomerConverter。此外，还有一个用于表示关系的调用引用转换器的转换器类，如 CustomerRefConverter。
单击“完成”。
- 查看“项目”窗口。现在您应该看到以下内容：
“项目”窗口中“REST 风格的 Web 服务”节点显示您项目中所有 REST 风格的 Web 服务。方括号中的值（如 [/customers/]）是 URI 模板的值。您还可以通过双击此节点定位到源文件。该视图还显示了所有 HTTP 方法和子资源定位器方法。同样，您也可以通过双击节点定位到方法。
现在测试应用程序。IDE 提供了一个用于测试 REST 风格的 Web 服务的有用实用程序。您将会在下一节中用到它。
测试 REST 风格的 Web 服务
本练习的目标是试验您的应用程序。
- 右键单击该项目节点，并选择“测试 REST 风格的 Web 服务”。服务器启动，应用程序部署。部署完成后，浏览器将显示应用程序，其中含有到各 Web 服务的链接。
如果输出窗口显示错误消息，指出一个或多个类不存在，且项目未生成，则请将 Jersey 库添加到编译时库中。右键单击项目节点，然后选择“属性”。在“属性”树状菜单中选择“库”。单击“添加库”并定位到 Jersey 库。
左侧是根资源集。此处，它们命名为 customers 和 discountCodes。
- 单击 customers 节点。浏览器窗口显示用于测试 Customers 服务的参数列表。
可以设置下列参数：
- 选择要测试的方法：从下拉列表中选择 GET 或 POST 方法以及 MIME 类型。
- 开始：要显示的第一个实体。请注意编号从 0 开始，而不是从 1 开始。
- 最大数目：可获取的最大实体数目。如果设置为 0，将获取所有实体。
- 展开级别：一项高级功能。有些服务返回无限重复的树状分层结构。此参数指定要在“原始视图”中显示此类分层结构的深度。
- 查询：一项高级功能。根据 JPA 语法搜索 XML 或 JSON 文档。
- 单击“方法”下拉列表，选择 GET(application/xml)。在“最大数目”字段中键入 "3"。保留其他参数中的缺省值，并单击“测试”。测试结果将显示在“测试输出”部分。
“测试输出”部分共有 4 个标签。
- “表格视图”是一个平面视图，它显示生成文档中的所有 URI，您可以通过单击这些链接进行导航。
- “原始视图”显示返回的实际数据。根据您选择的 mime 类型（application/xml 或 application/json），显示的数据将分别为 XML 或 JSON 格式。
- “头”标签显示 HTTP 头信息。
- “HTTP 监视”标签显示发送和接收的实际 HTTP 请求数和响应数。
请注意，尽管您指定了最多显示 3 个实体，但却列出了 6 个结果。打开“原始视图”标签可看到相关的原因。每个实体对应一个 <customer> 元素，测试结果中只有 3 个客户。但是，“表格视图”列出的是 URI，而不是实体，每个实体有两个 URI，一个是父 <customer> 元素的属性，另一个是子 <discountCode> 元素的属性。因此，尽管只有 3 个 customer 实体，但总共有 6 个 URI。
- 退出浏览器并返回到 IDE。
添加 Google 地图功能
本练习的目标是将 Google 地图功能添加到 REST 风格的 Web 服务。
- 在编辑器中打开 CustomerResource 类。
- 将以下方法添加到 CustomerResource：
@GET
@Produces("text/html")
public String getGoogleMap() {
// Drag and drop the getGoogleMap operation here
return "";
}
- 请在以下位置注册获取 Google 地图密钥：http://www.google.com/apis/maps/signup.html。Google 地图密钥请求对话框中有一个字段需要输入您网站的 URL。在该字段中键入 http://localhost:8080。
- 在 IDE 中，打开“服务”标签并展开“Web 服务”节点。在“Web 服务”下面，展开 "Google" 节点。在 "Google" 下，展开 "Map Service"。
- 将 getGoogleMap 项目拖放到在步骤 2 中创建的 getGoogleMap 方法的主体中，具体位置在紧靠 return = null; 代码行的前面。这将打开“定制 getGoogleMap SAAS”对话框。接受缺省选项，然后并单击“确定”。
IDE 将在 CustomerResource 类的 getGoogleMap 方法中添加以下 try 代码块：
@GET
@Produces("text/html")
public String getGoogleMap() {
// Drag and drop the getGoogleMap operation here
try {
String address = "16 Network Circle, Menlo Park";
java.lang.Integer zoom = 15;
String iframe = "false";
RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
//TODO - Uncomment the print Statement below to print result.
//System.out.println("The SaasService returned: "+result.getDataAsString());
} catch (Exception ex) {
ex.printStackTrace();
}
return "";
}
IDE 还会创建 org.netbeans.saas 和 org.netbeans.saas.google 包，其中包含有以下类和资源：
- RestConnection – HttpUrlConnection 的包装器
- RestResponse – HTTP 响应的包装器
- googlemapservice.properties – 存储 API 密钥的属性文件
- GoogleMapService – 包含包装器方法的服务包装器，它使用 RestConnection 调用 Google 地图服务。
- 在 getGoogleMap() 的 try 代码块中，将被注释掉的 print 语句替换为代码行 return result.getDataAsString();。此方法现在如下所示：
@GET
@Produces("text/html")
public String getGoogleMap() {
// Drag and drop the getGoogleMap operation here
try {
String address = "16 Network Circle, Menlo Park";
java.lang.Integer zoom = 15;
String iframe = "false";
RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
return result.getDataAsString();
} catch (Exception ex) {
ex.printStackTrace();
}
return "";
}
- 打开 googlemapservice.properties。粘入在步骤 3 中从 Google 获取的 API 密钥。
- 右键单击 "CustomerDB" 项目节点，并选择“测试 REST 风格的 Web 服务”。IDE 将取消部署，并将您的项目重新部署到服务器上，然后打开含测试客户端的浏览器窗口。
- 单击左侧边栏中的 customers。customers 的测试标准将在主窗格中打开。保留缺省选项不变，然后单击“测试”。这将打开一个用户表。
- 从表中单击 customer1。该客户的测试窗口将在主窗格中打开。从下拉列表中，选择 text/html MIME 类型。单击“测试”。"16 Network Circle, Menlo Park" 的 GoogleMap 将在“原始视图”中打开。
- 将为数据库中的所有客户显示 Menlo Park 地址的 Google 地图。要显示客户实际地址的 Google 地图，应当为数据库中的每个实体创建一个 Customer 实例，并将地址设置为等于包含每个 Customer 的地址变量的字串。如果您使用的是 6.5 之前的 IDE 版本，还需在 try 代码块的末尾添加一行代码以关闭 Customer 的实例。此方法现在如下所示（更改的内容以粗体显示）：
@GET
@Produces("text/html")
public String getGoogleMap() {
try {
Customer c = getEntity();
String address = c.getAddressline1() + " " + c.getAddressline2() + " " +
c.getCity() + " " + c.getState() + " " + c.getZip();
java.lang.Integer zoom = 15;
String iframe = "false";
RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
return result.getDataAsString();
} catch (Exception ex) {
ex.printStackTrace();
}
//The close() method is only necessary with versions of NetBeans IDE earlier than 6.5
finally {
PersistenceService.getInstance().close();
}
return "";
}
- 再次测试 REST 风格的 Web 服务。再次为一个客户选择 text/html MIME 类型。数据库中该客户地址的 Google 地图现在显示在“原始视图”中。对于 customer1，将显示下面的地图：
注意：如果 GoogleMaps 无法找到地址，它将显示放大的海洋视图。
Spring Framework 中 REST 风格的 Web 服务
从 NetBeans IDE 6.5 和 Jersey 0.8 开始，Jersey 集成到了 Spring Framework 中。在使用 Spring Framework 创建 Java Web 应用程序时，会自动创建识别 REST 的 Servlet。用户不需要执行任何额外的步骤。
要使用 Spring Framework 创建 REST 风格的 Web 服务，只需重复本教程中介绍的操作过程，但有一个例外。按照通过数据库生成实体类中所述在“新建项目”向导中创建 Java Web 应用程序时，在选择服务器后，单击“下一步”，而不是单击“完成”。此时将打开“框架”面板。选择 "Spring Web MVC"，然后单击“完成”。
创建 REST 风格的服务后，请注意 Spring 项目与在没有 Spring 的情况下创建的项目之间的以下区别：
- Spring 项目的 customerdb.service 包中没有名为 PersistenceService.java 的类。
- CustomerResource.java 导入 org.springframework.transaction.annotation.Transactional 并包含许多 @Transactional 标注。
之所以存在这两点区别，是因为 Spring Framework 会处理事务和实体管理，而在其他项目中，IDE 必须创建一个使用 javax.transaction.UserTransaction 和 javax.persistence.EntityManager 的类。Spring Framework 会产生更清晰的代码以及更高效的事务处理和实体管理。
有关 NetBeans IDE 中 Spring Framework 项目功能的详细信息，请参见 Spring Framework 简介。
另请参见
有关使用 NetBeans IDE 开发 Java EE 应用程序的更多信息，请参见以下资源：
要发送意见和建议、获得支持以及随时了解 NetBeans IDE Java EE 开发功能的最新进展，请加入 nbj2ee@netbeans.org 邮件列表。
