// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= REST 风格的 Web 服务入门指南
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: REST 风格的 Web 服务入门指南 - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, REST 风格的 Web 服务入门指南

代表性状态传输 (REST) 是一种用于分布式超媒体系统（如万维网）的体系结构样式。REST 风格的体系结构的核心概念是由统一资源标识符 (URI) 标识的资源。可以使用标准接口（如 HTTP）来处理这些资源以及使用这些资源的表示形式来交换信息。在本教程中，将首先了解一些关于 REST 的知识，然后演示 NetBeans IDE 是如何支持这种体系结构样式的。


image::images/netbeans-stamp-80-74-73.png[title="此页上的内容适用于 NetBeans IDE 7.2、7.3、7.4 和 8.0"]


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

|===
|软件或资源 |要求的版本 

|link:https://netbeans.org/downloads/index.html[+NetBeans IDE+] |Java EE 下载包 

|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Java 开发工具包 (JDK)+] |版本 7 或 8 

|符合 Java EE 规范的应用服务器 |

link:http://www.oracle.com/technetwork/middleware/weblogic/overview/index.html[+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 分发一起安装。或者，还可以访问 link:https://glassfish.java.net/download.html[+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 服务。

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

* link:http://jcp.org/en/jsr/detail?id=311[+JSR 311：JAX-RS：REST 风格的 Web 服务的 Java API+]
* link:http://jersey.dev.java.net/[+Jersey，用于构建 REST 风格的 Web 服务的开源 JAX-RS (JSR 311) 引用实现+]

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

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

1. 通过 JPA 实体类和模式快速创建 REST 风格的 Web 服务。
2. 通过在 "Services"（服务）窗口的 Web 服务管理器中拖放组件，快速生成可调用各种 Web 服务的代码，比如 Google 地图、Yahoo News Search 和 StrikeIron Web 服务。
3. 为 Web 服务管理器中的已注册服务生成 REST 风格的 Java 客户端。
4. 生成测试客户端，用于测试 REST 风格的 Web 服务。
5. 提供可轻松浏览项目中 REST 风格的 Web 服务实现类的逻辑视图。

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


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

Java 中 REST 风格的 Web 服务依靠 link:http://en.wikipedia.org/wiki/Java_Persistence_API[+Java 持久性 API+] 与数据库进行通信。具体来说，REST 风格的 Web 服务依赖于持久性 API 中定义的_实体类_和_持久性单元_。实体类是指映射到关系数据库中的对象的 Java 类。按照 link:http://download.oracle.com/javaee/5/tutorial/doc/bnbqa.html[+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 数据库服务器：*

1. 如果未注册 MySQL 服务器，请在 IDE 中注册该服务器。要注册 MySQL 服务器，请转至 IDE 的 "Services"（服务）窗口，右键单击 "Databases"（数据库）节点，然后选择 "Register MySQL Server"（注册 MySQL 服务器）。 
image::images/register-mysql-server.png[]
2. 
此时将打开一个对话框，您可以在其中键入 MySQL 服务器的配置详细信息，包括管理员用户名和口令。请参见link:../ide/install-and-configure-mysql-server.html[+连接到 MySQL 数据库+]中的“配置 MySQL 服务器属性”。

image::images/basic-mysql-properties.png[]
3. 启动并连接到 MySQL 服务器。请参见link:../ide/install-and-configure-mysql-server.html[+连接到 MySQL 数据库+]中的“启动 MySQL 服务器”。
4. 右键单击 "MySQL Server"（MySQL 服务器）节点，然后选择 "Create Database"（创建数据库）。此时将打开 "Create MySQL Database"（创建 MySQL 数据库）对话框。 
image::images/create-database.png[]
5. 键入  ``sample``  作为新数据库名称。为超级用户或所选的用户授予完全访问权限。
image::images/new-database-name.png[]
6. 单击 "OK"（确定）。此时将打开一个对话框，告知您  ``sample``  是样例数据库的名称，并询问您是否要为该数据库创建表、对象和数据。
image::images/create-sample-contents.png[]
7. 单击 "Yes"（是）。IDE 将创建并填充该数据库，并添加与该数据库的连接。
image::images/generated-db.png[]


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

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

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


=== 创建项目

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

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

1. 选择 "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"（下一步）。

2. 在 "Project Name"（项目名称）字段中，输入  ``CustomerDB`` 。单击 "Next"（下一步）。
3. 选择 "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 服务：*

1. 右键单击  ``CustomerDB``  节点，然后选择 "New"（新建）> "Other"（其他）> "Web Services"（Web 服务）> "RESTful Web Services from Database"（通过数据库创建 REST 风格的 Web 服务）。此时将在 "Database Tables"（数据库表）面板中打开新建 REST 风格的 Web 服务向导。
image::images/open-wizard.png[]
2. 在 "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 上创建样例数据库时创建了该连接。 
image::images/new-mysql-datasource.png[]

3. 在 "Available Tables"（可用表）下，选择 "CUSTOMER"，然后单击 "Add"（添加）。DISCOUNT_CODE 表（与 CUSTOMER 表有关联）将自动添加到 "Selected Tables"（选定表）列表中。如果使用 MySQL 数据库或某些版本的 Derby，则还将添加 MICRO_MARKET 表。现在将显示以下内容（Derby 版本）：

image::images/select-tables.png[title="“通过数据库新建实体类”向导的 "Database Tables"（数据库表）面板，其中显示已选定的 CUSTOMER 和 DISCOUNT_CODE 表"]
4. 单击 "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 标注添加到实体类中。有关详细信息，请参见link:http://netbeans.dzone.com/nb-generate-simpler-rest[+用于生成更简单的 REST 风格 Web 服务的 NetBeans+]。

image::../../../images_www/articles/71/websvc/rest/entity-classes.png[]
5. 单击 "Next"（下一步）。打开了一个面板，在其中可以设置生成的服务类和包的名称及位置。对于 Java EE 项目，可以选择更改 REST 应用程序配置类的名称和位置。

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

image::images/class-name-location.png[]

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


== 测试 REST 风格的 Web 服务

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

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

IDE 将在 WebServiceTest 项目中生成文件  ``test-resbeans.html`` 。IDE 还将自动启动服务器并部署 CustomerDB 应用程序。

如果输出窗口显示错误消息，指出一个或多个类不存在，且项目未构建，则请将 Jersey 库添加到编译时库中。右键单击项目节点，然后选择 "Properties"（属性）。在 "Properties"（属性）树状菜单中选择 "Libraries"（库）。单击 "Add Library"（添加库）并定位到 Jersey 库。

8. 右键单击 "WebServiceTest"，然后选择 "Run"（运行）。
9. 将浏览器打开到 link:http://localhost:8080/WebServicesTest/test-resbeans.html[+http://localhost:8080/WebServicesTest/test-resbeans.html+] 
image::../../../images_www/articles/71/websvc/rest/test-rest1.png[title="浏览器中 REST 风格的 Web 服务测试器登录页"]

左侧是根资源集。此处将其命名为  ``entities.customer`` 、 ``entities.discountCodes``  和  ``entities.microMarket`` 。

10. 单击  ``entities.customer``  节点。在 "Choose method to test"（选择要测试的方法）字段中，选择 GET (application/json) 或 GET (application/xml)。单击 "Test"（测试）。测试客户端发送请求并在 "Test Output"（测试输出）部分中显示结果。默认情况下，测试客户端显示原始视图。以下图像显示了对 application/xml 请求的响应。
image::images/test-rest-raw.png[]

"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。

link:/about/contact_form.html?to=3&subject=Feedback:%20Getting%20Started%20with%20REST%20Services%20in%20NetBeans%20IDE%20[+发送有关此教程的反馈意见+]


== 另请参见

有关使用 NetBeans IDE 开发 Java EE 应用程序的更多信息，请参见以下资源：

* link:http://netbeans.dzone.com/nb-generate-simpler-rest[+用于生成更简单的 REST 风格 Web 服务的 NetBeans+]
* link:../../trails/web.html[+Web 服务学习资源+]
* YouTube：link:http://www.youtube.com/watch?v=cDdfVMro99s[+REST 风格的 Web 服务，构建和部署（第 1 部分）+]
* YouTube：link:http://www.youtube.com/watch?v=_c-CCVy4_Eo[+NetBeans REST 风格的测试和调用 REST 风格的资源（第 2 部分）+]

要发送意见和建议、获得支持以及随时了解 NetBeans IDE Java EE 开发功能的最新开发情况，请link:../../../community/lists/top.html[+加入 nbj2ee@netbeans.org 邮件列表+]。