REST 风格的 Web 服务入门

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

软件或资源	要求的版本
NetBeans IDE	Java EE 下载包
Java 开发工具包 (JDK)	版本 6 或 7
符合 Java EE 规范的应用服务器	Oracle WebLogic Server 11g-12c，或者 GlassFish Server Open Source Edition 3.x 或 4.x （除非在 Tomcat 中安装了 EJB 支持插件，否则不适用于 Tomcat）
jdbc/sample 数据库（位于 Java DB (Derby) 数据库服务器或 MySQL 数据库服务器上）	在 Java DB (Derby) 上，jdbc/sample 数据库是由 NetBeans IDE 生成的（如果将 IDE 与 GlassFish 应用服务器一起安装）。通过 IDE 在 MySQL 服务器上创建样例数据库后，IDE 将在 MySQL 上填充该样例数据库。

GlassFish Server 可以随 NetBeans IDE 的 Web 和 Java EE 分发一起安装。或者，还可以访问 GlassFish Server 下载页。

重要说明：Java EE 6 和 Java EE 7 项目需要使用 GlassFish Server 或 Oracle WebLogic Server 12c。

简介

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 服务。
通过在 "Services"（服务）窗口的 Web 服务管理器中拖放组件，快速生成可调用各种 Web 服务的代码，比如 Google 地图、Yahoo News Search 和 StrikeIron Web 服务。
为 Web 服务管理器中的已注册服务生成 REST 风格的 Java 客户端。
生成测试客户端，用于测试 REST 风格的 Web 服务。
提供可轻松浏览项目中 REST 风格的 Web 服务实现类的逻辑视图。
完全集成的 Spring Framework，提供 Spring 事务处理。

在本教程中，将介绍 IDE 如何支持生成、实现和测试 REST 风格的 Web 服务。

REST 风格的 Web 服务、持久性和实体类

Java 中 REST 风格的 Web 服务依靠 Java 持久性 API 与数据库进行通信。具体来说，REST 风格的 Web 服务依赖于持久性 API 中定义的实体类和持久性单元。实体类是指映射到关系数据库中的对象的 Java 类。按照 Java EE5 教程中的说法，“实体是一种小型持久性域对象。通常情况下，实体表示关系数据库中的表，每个实体实例与该表中的一行相对应”。持久性单元包含 persistence.xml 文件中定义的实体类、数据源、持久性提供器以及持久性单元自身的名称集合。

您可以使用 NetBeans IDE 在同一过程中创建实体类和 REST 风格的 Web 服务，也可以使用 IDE 通过现有实体类创建 REST 风格的 Web 服务。在本教程中，将使用 "RESTful Services from Database"（通过数据库生成 REST 风格的服务）向导在相同过程中生成实体类和 REST 风格的 Web 服务。该向导会自动生成持久性单元。

使用 MySQL 数据库服务器

如果使用的是 MySQL 数据库服务器而不是 JavaDB (Derby)，您需要在 IDE 中注册该数据库服务器，然后将 sample 数据库添加到该服务器上。

在本教程中使用 MySQL 数据库服务器：

如果未注册 MySQL 服务器，请在 IDE 中注册该服务器。要注册 MySQL 服务器，请转至 IDE 的 "Services"（服务）窗口，右键单击 "Databases"（数据库）节点，然后选择 "Register MySQL Server"（注册 MySQL 服务器）。
此时将打开一个对话框，您可以在其中键入 MySQL 服务器的配置详细信息，包括管理员用户名和口令。请参见连接到 MySQL 数据库中的“配置 MySQL 服务器属性”。
启动并连接到 MySQL 服务器。请参见连接到 MySQL 数据库中的“启动 MySQL 服务器”。
右键单击 "MySQL Server"（MySQL 服务器）节点，然后选择 "Create Database"（创建数据库）。此时将打开 "Create MySQL Database"（创建 MySQL 数据库）对话框。
键入 sample 作为新数据库名称。为超级用户或所选的用户授予完全访问权限。
单击 "OK"（确定）。此时将打开一个对话框，告知您 sample 是样例数据库的名称，并询问您是否要为该数据库创建表、对象和数据。
单击 "Yes"（是）。IDE 将创建并填充该数据库，并添加与该数据库的连接。

通过数据库创建 REST 风格的 Web 服务

本练习的目标是创建一个项目，并通过数据库生成实体类和 REST 风格的 Web 服务。

此部分使用 JavaDB (Derby) 数据库和 jdbc/sample 数据源。JavaDB 包含在 SDK 中。jdbc/sample 数据源是在同时安装 IDE 与 GlassFish 时由 NetBeans IDE 自动生成的。

创建项目

要创建 REST 风格的 Web 服务，您需要创建 Java Web 应用程序项目。

要创建此项目，请执行以下操作：

选择 "File"（文件）> "New Project"（新建项目）（在 Linux 和 Windows 上为 Ctrl-Shift-N 组合键，在 MacOS 上为 ⌘-Shift-N 组合键）。在 "Categories"（类别）下，选择 "Java Web"。在 "Projects"（项目）下，选择 "Web Application"（Web 应用程序）。单击 "Next"（下一步）。此时将打开新建 Web 应用程序向导。

或者，也可以创建 Maven Web 应用程序。选择 "File"（文件）> "New Project"（新建项目）（在 Linux 和 Windows 上为 Ctrl-Shift-N 组合键，在 MacOS 上为 ⌘-Shift-N 组合键）。在 "Categories"（类别）下，选择 "Maven"。在 "Projects"（项目）下，选择 "Maven Web Application"（Maven Web 应用程序），然后单击 "Next"（下一步）。
在 "Project Name"（项目名称）字段中，输入 CustomerDB。单击 "Next"（下一步）。
选择 "Java EE 6 Web" 或 "Java EE 7 Web"。在 "Server"（服务器）下，选择要使用的服务器，但请注意，Java EE 项目需要使用 GlassFish Server 3.x 或 4.x。依次单击其余选项，然后单击 "Finish"（完成）。
Maven 项目重要说明：在 NetBeans IDE 7.2 中，在创建 Maven Web 应用程序时，您无法设置服务器。而需在创建持久性单元之前设置服务器。因此，在创建 Maven Web 应用程序后，请打开项目的 "Properties"（属性）对话框并在 "Run"（运行）属性中设置服务器。要打开项目的 "Properties"（属性）对话框，请右键单击 "Project"（项目）节点，然后从上下文菜单中选择 "Properties"（属性）。

生成实体类和 REST 风格的服务

在创建 Java Web 应用程序后，将实体类和 REST 风格的 Web 服务添加到项目中。

生成实体类和 REST 风格的 Web 服务：

右键单击 CustomerDB 节点，然后选择 "New"（新建）> "Other"（其他）> "Web Services"（Web 服务）> "RESTful Web Services from Database"（通过数据库创建 REST 风格的 Web 服务）。此时将在 "Database Tables"（数据库表）面板中打开新建 REST 风格的 Web 服务向导。
在 "Database Tables"（数据库表）面板中，如果使用的是 GlassFish Server，请从 "Data Source"（数据源）下拉列表字段中选择 jdbc/sample 数据源。
如果使用的是 Tomcat，请选择 jdbc:derby://localhost:1527/sample。如果 Derby 数据库服务器未能自动启动，需要从 "Services"（服务）窗口的 "Databases"（数据库）标签中启动它。

MySQL 用户注意事项：您必须创建新的数据源。选择 "New Data Source"（新建数据源），指定任意描述性名称，然后选择jdbc:mysql://localhost:3306/sample 数据库连接。在 MySQL 上创建样例数据库时创建了该连接。
在 "Available Tables"（可用表）下，选择 "CUSTOMER"，然后单击 "Add"（添加）。DISCOUNT_CODE 表（与 CUSTOMER 表有关联）将自动添加到 "Selected Tables"（选定表）列表中。如果使用 MySQL 数据库或某些版本的 Derby，则还将添加 MICRO_MARKET 表。现在将显示以下内容（Derby 版本）：
单击 "Next"（下一步）。"Entity Classes"（实体类）页打开。为包名键入 entities。现在将显示以下内容（Derby 版本）。
注："RESTful Web Services from Database"（通过数据库创建 REST 风格的 Web 服务）向导会自动生成 JAXB 标注。如果使用 "Entity Classes from Database"（通过数据库生成实体类）向导为 Java EE 应用程序生成实体类，并且以后可能要通过这些实例类创建 REST 风格的 Web 服务，请确保选中 "Generate JAXB Annotations"（生成 JAXB 标注）框。此外，还可以在运行 "RESTful Web Services from Entity Classes"（通过实体类创建 REST 风格的 Web 服务）向导之前手动将 JAXB 标注添加到实体类中。有关详细信息，请参见用于生成更简单的 REST 风格 Web 服务的 NetBeans。
单击 "Next"（下一步）。打开了一个面板，在其中可以设置生成的服务类和包的名称及位置。对于 Java EE 项目，可以选择更改 REST 应用程序配置类的名称和位置。
Spring 框架应用程序：在 web.xml 部署描述符中注册 REST 风格的资源。不要使用 javax.ws.rs.core.Application。

在本教程中，接受默认值，然后单击 "Finish"（完成）。单击 "Finish"（完成）后，IDE 将生成实体类和服务类。在 Java EE 项目中，IDE 还将生成应用程序配置类，这是应用程序的子类。

IDE 现在将生成 REST 风格的 Web 服务。在 IDE 完成后，查看 "Projects"（项目）窗口。生成的实体类位于 entities 包中，服务位于 service 包中。通过数据库创建的 Java EE REST 风格的 Web 服务将实例化每个服务类中的 EntityManager。这就不需要使用 JPA 控制器类并可生成更简单的代码。

测试 REST 风格的 Web 服务

本练习的目标是试验您的应用程序。您将为测试创建一个新的 Web 应用程序，然后使用 IDE 中的向导在新项目中生成测试。

从主菜单中选择 "File"（文件）> "New Project"（新建项目）。
在 "Java Web" 类别中选择 "Web Application"（Web 应用程序）项目类型。单击 "Next"（下一步）。
为项目名称键入 WebServicesTest。单击 "Next"（下一步）。
选择 "GlassFish Server" 作为目标服务器，并选择 "Java EE 6 Web" 或 "Java EE 7 Web" 作为 Java EE 版本。单击 "Finish"（完成）。
右键单击 CustomerDB 项目节点，并选择 "Test RESTful Web Services"（测试 REST 风格的 Web 服务）。此时将打开一个对话框，询问您是否要在服务项目或其他 Java Web 项目中生成测试客户端。通过此选项，可以解决某些浏览器中的安全限制问题。只要将 Web 项目配置为在 CustomerDB 项目所在的同一个服务器域中部署，您就可以使用任何 Web 项目了。
选择 Web Test Client in Project（项目中的 Web 测试客户端），然后单击 "Browse"（浏览）。
在 "Select Project"（选择项目）对话框中选择 "WebServiceTest" 项目。单击 "OK"（确定）。
IDE 将在 WebServiceTest 项目中生成文件 test-resbeans.html。IDE 还将自动启动服务器并部署 CustomerDB 应用程序。

如果输出窗口显示错误消息，指出一个或多个类不存在，且项目未构建，则请将 Jersey 库添加到编译时库中。右键单击项目节点，然后选择 "Properties"（属性）。在 "Properties"（属性）树状菜单中选择 "Libraries"（库）。单击 "Add Library"（添加库）并定位到 Jersey 库。
右键单击 "WebServiceTest"，然后选择 "Run"（运行）。
将浏览器打开到 http://localhost:8080/WebServicesTest/test-resbeans.html
左侧是根资源集。此处将其命名为 entities.customer、entities.discountCodes 和 entities.microMarket。
单击 entities.customer 节点。在 "Choose method to test"（选择要测试的方法）字段中，选择 GET (application/json) 或 GET (application/xml)。单击 "Test"（测试）。测试客户端发送请求并在 "Test Output"（测试输出）部分中显示结果。默认情况下，测试客户端显示原始视图。以下图像显示了对 application/xml 请求的响应。

"Test Output"（测试输出）区域中有 5 个标签。

表格视图是平面视图，其中显示生成的文档中的所有 URI。当前此视图仅显示警告，指示不允许容器-包含物关系。
"Raw View"（原始视图）显示返回的实际数据。根据您选择的 mime 类型（application/xml 或 application/json），显示的数据将分别为 XML 或 JSON 格式。
"Sub Resource"（子资源）标签将显示根资源和子资源的 URL。当 REST 风格的 Web 服务是基于数据库实体类时，根资源代表了数据库表，而子资源则代表列。
"Headers"（头）标签显示 HTTP 头信息。
"HTTP Monitor"（HTTP 监视）标签显示发送和接收的实际 HTTP 请求数和响应数。

退出浏览器并返回到 IDE。

Spring Framework 中 REST 风格的 Web 服务

Jersey 集成到了 Spring Framework 中。在使用 Spring Framework 创建 Java Web 应用程序时，会自动创建识别 REST 的 Servlet。不过，Spring 3 不包含 aopalliance.jar，REST 风格的 Web 服务需要使用它来注入 EntityManager 对象。

使用 Spring Framework 创建 Java Web 应用程序

按照通过数据库生成实体类中所述在新建项目向导中创建 Java Web 应用程序时，在选择服务器后，单击 "Next"（下一步）而不是单击 "Finish"（完成）将打开向导的 "Frameworks"（框架）面板。选择 "Spring Web MVC"，然后单击 "Finish"（完成）。

注：如果您已创建项目，则可以通过在 "Projects"（项目）窗口中右键单击项目节点，然后在弹出菜单中选择 "Properties"（属性），来添加对 Spring Web MVC 框架的支持。在 "Project Properties"（项目属性）窗口中，选择 "Frameworks"（框架）类别，然后单击 "Add"（添加）并选择 "Spring Web MVC"。

将 aopalliance.jar 添加到项目中

Spring 3 不包含 aopalliance.jar。该应用程序需要使用此库才能注入 EntityManager。要解决问题，您需要下载此 JAR，并将其添加到类路径中。请参见问题 193626 和Spring 论坛。

添加 aopalliance.jar：

从 http://sourceforge.net/projects/aopalliance/files/aopalliance/1.0/ 下载 aopalliance.jar 的 zip 档案。
将该档案解压缩到所选位置。
在 "Projects"（项目）窗口中，右键单击 "Spring RESTful Web Service"（Spring REST 风格的 Web 服务）项目节点并在弹出菜单中选择 "Properties"（属性），然后在 "Project Properties"（项目属性）窗口中选择 "Libraries"（库）类别。
或者，也可以在 "Projects"（项目）窗口中右键单击项目的 "Libraries"（库）节点，然后选择 "Add JAR/Folder"（添加 JAR/文件夹）。
单击 "Add JAR/Folder"（添加 JAR/文件夹），然后在文件系统浏览器中查找 aopalliance.jar。单击 "Open"（打开）。
您需要使用绝对路径引用。
aopalliance.jar 文件现在包含在您的库中。单击 "OK"（确定）。

在启用 Spring 的项目中创建 REST 风格的服务

使用 Spring Framework 创建 Java Web 应用程序并将 aopalliance.jar 添加到项目的类路径后，请运行 "RESTful Web Service from Database"（通过数据库生成 REST 风格的 Web 服务）向导，如生成实体和服务中所述。但是，不会将 REST 风格的资源注册到 javax.ws.rs.core.Application 的子类中。而是使用 web.xml 部署描述符。在所有情况下，Spring Framework 都会生成 web.xml 部署描述符。