// 
//     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.
//

= Начало работы с веб-службами RESTful
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Начало работы с веб-службами RESTful - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Начало работы с веб-службами RESTful

REST (REpresentational State Transfer, передача состояния представления) является архитектурным стилем для распределенных систем данных гипермедиа, например, World Wide Web. В основе архитектуры RESTful лежит принцип определения ресурсов по универсальным идентификаторам ресурсов (Universal Resource Identifiers, URI). Управление этими ресурсами осуществляется с помощью стандартного интерфейса, например HTTP, а обмен информацией происходит с помощью представлений этих ресурсов. В этом учебном руководстве сначала вкратце описывается REST, а затем описывается, как IDE NetBeans поддерживает этот стиль архитектуры.


image::images/netbeans-stamp-80-74-73.png[title="Содержимое этой страницы применимо к IDE NetBeans 7.2, 7.3, 7.4 и 8.0"]


*Для работы с этим учебным курсом требуется следующее программное обеспечение и ресурсы.*

|===
|Программное обеспечение или материал |Требуемая версия 

|link:https://netbeans.org/downloads/index.html[+IDE NetBeans+] |Пакетная загрузка Java EE 

|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Комплект для разработчика на языке Java (JDK)+] |версия 7 или 8 

|Cервер приложений, совместимый с 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)

 
|База данных jdbc/sample на 
сервере базы данных Java DB (Derby) или сервере базы данных MySQL. 
сервер базы данных

 |

В ДБ Java (Derby) база данных jdbc/образец базы данных создается IDE NetBeans 
при установке IDE с сервером приложений GlassFish.

На MySQL среда IDE заполняет пример базы данных после создания его на сервере MySQL изнутри IDE.

 
|===

Сервер GlassFish можно установить через Интернет и пи распространении IDE NetBeans с помощью Java EE. Также можно воспользоваться link:https://glassfish.java.net/download.html[+страницей загрузок сервера GlassFish+].

*Важно! *Для проектов Java EE 6 и Java EE 7 требуется GlassFish Server или Oracle WebLogic Server 12c.


==  Введение

Веб-службы RESTful представляют собой службы, созданные с помощью архитектурного стиля RESTful. Создание веб-служб с применением подхода RESTful становится популярной альтернативой использованию технологий развертывания служб в сети Интернет на основе SOAP, поскольку этот подход отличается простотой и удобством, а также предоставляет возможность передачи данных непосредственно по HTTP.

Среда IDE поддерживает быструю разработку веб-служб RESTful при помощи JSR 311 (интерфейса API Java для веб-служб RESTful (JAX-РТС)) и Jersey (примера реализации JAX-РТС).

Для получения более подробных данных обратитесь к разделу

* link:http://jcp.org/en/jsr/detail?id=311[+JSR 311: JAX-RS: интерфейс API Java для веб-служб RESTful+]
* link:http://jersey.dev.java.net/[+Jersey, пример реализации JAX-RS (JSR 311) с открытым исходным кодом для создания веб-служб RESTful+]

Помимо создания веб-служб RESTful среда IDE также поддерживает тестирование, создание клиентских приложений с возможностью доступа к веб-службам RESTful и создание кода для вызова веб-служб (как RESTful, так и служб на основе SOAP).

Ниже приведен список возможностей RESTful, предоставляемых средой IDE:

1. быстрое создание веб-служб RESTful на основе классов объектов JPA и шаблонов;
2. быстрое создание кода для вызова веб-служб, таких как Карты Googlе, Yahoo! News Search и StrikeIron, путем перетаскивания компонентов из диспетчера веб-служб в окно служб;
3. создание клиентов Java RESTful для служб, зарегистрированных в диспетчере веб-служб;
4. создание тестовых клиентов для тестирования веб-служб RESTful;
5. логическое представление для удобного перехода по классам реализации веб-службы RESTful в проекте;

В этом учебном курсе рассматривается создание, реализация и тестирование веб-служб RESTful при помощи среды IDE.


== Веб-службы RESTful, сохранение состояния, классы сущностей

Веб-службы RESTful в Java используют link:http://en.wikipedia.org/wiki/Java_Persistence_API[+интерфейс API сохранения состояния Java+] для связи с базами данных. Говоря конкретнее, веб-службы RESTful используют _классы сущностей_ и _блок сохранения состояния_ как они определены в интерфейсе API сохранения состояния. Классы сущностей – это классы Java, сопоставленные с объектами в реляционной базе данных. Согласно link:http://download.oracle.com/javaee/5/tutorial/doc/bnbqa.html[+руководству по Java EE5+]: "Сущностью называется упрощенный объект области сохранения состояния. Как правило, сущность представляет таблицу в реляционной базе данных, и каждый экземпляр сущности соответствует строке в этой таблице. Блок сохранения состояния состоит из набора сущностных классов, источника данных, поставщика сохранения состояния и собственного имени блока сохранения состояния, как определено в файле  ``persistence.xml`` .

IDE NetBeans можно использовать либо для создания классов логических объектов и веб-служб RESTful в одном процессе или среду IDE можно использовать для создания веб-служб RESTful на основе существующих классов логических объектов. В этом учебном курсе мы используем мастер создания служб RESTful из базы данных для автоматического создания классов сущностей и веб-служб RESTful в одном процессе. Мастер автоматически создаст блок сохранения состояния.


== Использование сервера баз данных MySQL

Если использовать сервер базы данных MySQL вместо JavaDB (Derby), необходимо зарегистрировать сервер базы данных в среде IDE и добавить базу данных  ``sample``  к серверу.

*Чтобы использовать сервер базы данных MySQL с этим учебным курсом, выполните следующие действия.*

1. Зарегистрируйте сервер MySQL в среде IDE, если он еще не зарегистрирован. Для регистрации сервера MySQL перейдите в окно 'Службы' среды IDE, щелкните правой кнопкой мыши узел Databases и выберите 'Регистрация сервера MySQL'. 
image::images/register-mysql-server.png[]

[start=2]
. 
Откроется диалоговое окно, в которое следует ввести параметры своего сервера MySQL, включая имя и пароль пользователя, являющегося администратором. См. раздел "Настройка свойств сервера MySQL" в разделе link:../ide/install-and-configure-mysql-server.html[+Подключение к базе данных MySQL+].

image::images/basic-mysql-properties.png[]

[start=3]
. Запустите сервер MySQL и подключитесь к нему. См. раздел "Запуск сервера MySQL" в разделе link:../ide/install-and-configure-mysql-server.html[+Подключение к базе данных MySQL+].

[start=4]
. Щелкните правой кнопкой мыши узел сервера MySQL и выберите Create Database ("Создать базу данных"). Откроется диалоговое окно создания базы данных MySQL. 
image::images/create-database.png[]

[start=5]
. Введите  ``sample``  в качестве имени новой базы данных. Предоставьте полный доступ корневому пользователю или пользователю по своему выбору.
image::images/new-database-name.png[]

[start=6]
. Нажмите кнопку "ОК". Откроется диалоговое окно, сообщающее, что именем примера базы данных является  ``sample``  и спрашивающее, следует ли создать таблицы, объекты и данные для этой базы данных.
image::images/create-sample-contents.png[]

[start=7]
. Нажмите кнопку "Да". Среда IDE создаст и заполнит базу данных, а также добавит подключение к ней.
image::images/generated-db.png[]


== Создание веб-служб RESTful из базы данных

Целью данного упражнения является создание проекта, а затем создание классов сущностей и веб-служб RESTful из базы данных.

В данном разделе используется база данных JavaDB (Derby) и источник данных jdbc/sample. JavaDB входит в состав SDK. Источник данных jdbc/образец источника данных создается IDE NetBeans автоматически при установке IDE совместно с GlassFish.


=== Создание проекта

Для создания веб-служб RESTful нужен проект веб-приложения Java.

*Для создания проекта выполните следующие действия:*

1. Выберите 'Файл' > 'Создать проект' (Ctrl-Shift-N в Windows и Linux, ⌘-Shift-N в ОС Mac). В области "Категории" выберите "Java Web". В области "Projects" выберите "Web Application". Нажмите кнопку "Далее". Откроется мастер создания веб-приложений.

Как вариант, можно создать веб-приложение Maven. Выберите 'Файл' > 'Создать проект' (Ctrl-Shift-N в Windows и Linux, ⌘-Shift-N в ОС Mac). В Categories ("Категории) выберите Maven. В Projects ("Проекты") выберите Maven Web Application ("Веб-приложение Maven") и нажмите кнопку Next ("Далее").


[start=2]
. Введите в поле "Имя проекта" текст  ``CustomerDB`` . Нажмите кнопку "Далее".

[start=3]
. Выберите Java EE 6 Web либо Java EE 7 Web. В списке 'Сервер' выберите нужный сервер, но помните, что для проектов Java EE требуется GlassFish Server 3.x или 4.x. Пропустите все последующие настройки и нажмите 'Готово'.

*Важное замечание для проектов Maven. * В NetBeans IDE 7.2 при создании веб-приложения Maven невозможно указать сервер. Однако сервер должен быть указан до создания блока сохранения состояния. Поэтому после создания веб-приложения Maven откройте свойства проекта и установите сервер в Run Рroperties ("Свойства выполнения"). Чтобы открыть свойства проекта, щелкните правой кнопкой мыши в узле 'Проект' и выберите 'Свойства' в контекстном меню.


=== Создание классов сущностей и служб RESTful

Когда веб-приложение Java создано, добавьте к проекту классы сущностей и веб-службы RESTful.

*Для создания сущностных классов и веб-служб RESTful выполните следующие действия.*

1. Щелкните правой кнопкой мыши узел  ``CustomerDB``  и выберите New ("Создать") > Other ("Другое") > Web Services ("Веб службы") > RESTful Web Services from Database ("Веб-службы RESTful из базы данных"). На панели Database Tables ("Таблицы базы данных") откроется мастер создания веб-службы RESTful.
image::images/open-wizard.png[]

[start=2]
. При использовании сервера GlassFish выберите в раскрывающемся списке "Источник данных" на панели "Таблицы" источник данных  ``jdbc/sample`` .

При использовании сервера Tomcat выберите jdbc:derby://localhost:1527/sample. Если сервер базы данных Derby не запускается автоматически, необходимо запустить его на вкладке "Базы данных" в окне "Службы".

*Примечание для пользователей MySQL.* Необходимо будет создать новый источник данных. Выберите New Data Source ("Создать источник данных"), дайте ему произвольное описательное имя и выберите подключение к базе данных  ``jdbc:mysql://localhost:3306/sample`` . Это подключение было создано при создании примера базы данных в MySQL. 
image::images/new-mysql-datasource.png[]


[start=3]
. Выберите в области "Доступные таблицы" таблицу CUSTOMER и нажмите кнопку "Добавить". Таблица DISCOUNT_CODE, связанная с таблицей CUSTOMER, также добавляется в область "Выбранные таблицы" автоматически. Если вы используете базу данных MySQL или некоторые версии Derby, также добавляется таблица MICRO_MARKET. Теперь отображается следующее (версия Derby): 

image::images/select-tables.png[title="Панель 'Таблицы баз данных' новых классов сущностей из мастера баз данных, в которых показаны выделенные таблицы CUSTOMER и DISCOUNT_CODE"]

[start=4]
. Нажмите кнопку "Далее". Откроется страница Entity Classes ("Классы сущностей"). В поле 'Имя пакета' введите  ``entities`` . Теперь отображается следующее (версия Derby).

*Примечание.* Веб-службы RESTful из мастера баз данных автоматически создают аннотации JAXB. Если классы сущностей для приложения Java EE создаются при помощи мастера создания классов сущностей на основе базы данных и если впоследствии эти классы будут использоваться для создания веб-службы RESTful, убедитесь, что установлен флажок 'Создать аннотации JAXB'. Аннотации JAXB также можно вручную добавить к классам сущностей перед запуском мастера создания веб-служб RESTful из классов сущностей. Дополнительные сведения приведены в документе link:http://netbeans.dzone.com/nb-generate-simpler-rest[+NetBeans to Generate Simpler RESTful Web Services ("Использование NetBeans для создания более простых веб-служб RESTful") +].

image::../../../images_www/articles/71/websvc/rest/entity-classes.png[]

[start=5]
. Нажмите кнопку "Далее". Откроется панель, в которой можно задать имя и расположение созданных классов служб и пакеты. В проектах Java EE предусмотрена возможность изменения имени и местоположения класса конфигурации приложения REST.

Для этого учебного курса примите параметры по умолчанию и нажмите кнопку "Готово". При на нажатии на кнопку 'Готово' IDE создает классы сущностей и служб. В проектах Java EE IDE также создает класс конфигурации приложения, который является подклассом для Application.

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

Теперь среда IDE создаст веб-службы RESTful. Когда среда IDE выполнит это, загляните в окно Projects ("Проекты"). Созданные классы сущностей находятся в пакете  ``entities`` , а классы служб - в пакете  ``service`` . Веб-службы RESTful Java EE на основе базы данных создают экземпляр  ``EntityManager``  в каждом классе службы. Это устраняет нужду в классах контроллеров JPA и упрощает код.


== Тестирование веб-служб RESTful

Целью этого упражнения является тестирование приложения. Вы создадите новое веб-приложения для тестирования, затем с помощью мастера IDE создадите тесты в новом проекте.

1. В главном меню выберите "Файл" > "Новый проект".
2. В списке 'Тип проекта' в категории 'Java Web' выберите 'Веб-приложение'. Нажмите кнопку "Далее".
3. В поле 'Имя проекта' введите *WebServicesTest*. Нажмите кнопку "Далее".
4. В качестве целевого сервера выберите GlassFish Server, а в качестве версии Java EE - Java EE 6 Web или Java EE 7 Web. Нажмите 'Готово'.
5. Щелкните правой кнопкой мыши узел проекта  ``CustomerDB``  и выберите 'Тестировать веб-службы RESTful'. Откроется диалоговое окно, запрашивающее, следует ли создать тестовый клиент внутри проекта службы или в другом веб-проекте Java. Это позволяет обойти ограничения безопасности в некоторых браузерах. Можно использовать любой веб-проект, если он настроен на развертывание в том же домене сервера, что и проект CustomerDB. 
image::../../../images_www/articles/71/websvc/rest/configure-test-client.png[]

[start=6]
. Выберите *Тестовый веб-клиент в проекте* и нажмите 'Обзор'.

[start=7]
. Выберите проект WebServiceTest в диалоговом окне 'Выбор проекта'. Нажмите кнопку "ОК".

IDE создает файл  ``test-resbeans.html``  в проекте WebServiceTest. Кроме того, IDE автоматически запускает сервер и выполняет развертывание приложения CustomerDB.

Если в окне 'Результаты' появилось сообщение об ошибке, указывающее на отсутствие одного или нескольких классов и невозможность сборки проекта, добавьте в библиотеки компиляции библиотеки Jersey. Щелкните правой кнопкой мыши узел проекта и выберите команду "Свойства". Выберите в меню дерева "Свойства" пункт "Библиотеки". Щелкните "Добавить библиотеку" и перейдите к библиотекам Jersey.


[start=8]
. Щелкните проект WebServiceTest правой кнопкой мыши и выберите 'Выполнить'.

[start=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="Целевая страница средства тестирования веб-службы RESTful в браузере"]

Слева расположен набор корневых ресурсов. Здесь они названы  ``entities.customer`` ,  ``entities.discountCodes``  и  ``entities.microMarket`` .


[start=10]
. Щелкните узел  ``entities.customer`` . В поле "Выбрать метод для тестирования" выберите GET (приложение/json) или GET (приложение/xml). Нажмите кнопку тестирования. Тестируемый клиент отправляет запрос и выводит результат в разделе 'Результат тестирования'. Тестируемый клиент отображается по умолчанию в представлении необработанных данных На следующем изображении отображается отклик на запрос приложения/xml.
image::images/test-rest-raw.png[]

В разделе результатов тестирования отображается 5 вкладок.

* 'Табличное представление' - это неструктурированное представление, в котором отображаются все URI в полученном документе. В настоящее время в этом представлении отображается только предупреждение о том, что связь контейнера и содержимого контейнера не допускается.
* В представлении необработанных данных отображаются фактически возвращенные данные. В зависимости от выбранного типа MIME ( ``application/xml``  или  ``application/json`` ) данные будут представлены в формате XML или JSON, соответственно.
* На вкладке подресурсов отображаются URL-адреса корневого ресурса и подресурсов. Если веб-служба RESTful построена на основе базы данных, корневой ресурс представляет таблицу базы данных, а подресурсы – столбцы.
* На вкладке заголовков представлены данные заголовка HTTP.
* На вкладке монитора HTTP отображаются текущие запросы HTTP, а также отправленные и полученный ответы.

Закройте браузер и вернитесь к среде IDE.

link:/about/contact_form.html?to=3&subject=Feedback:%20Getting%20Started%20with%20REST%20Services%20in%20NetBeans%20IDE%20[+Отправить отзыв по этому учебному курсу+]


== Дополнительные сведения

Дополнительные сведения об использовании IDE NetBeans для разработки приложений Java EE см. следующие ресурсы:

* link:http://netbeans.dzone.com/nb-generate-simpler-rest[+Использование NetBeans для создания упрощенных веб-служб RESTful+]
* link:../../trails/web.html[+Учебная карта по веб-службам+]
* Youtube: link:http://www.youtube.com/watch?v=cDdfVMro99s[+Веб-службы RESTful, сборка и развертывание (Часть 1)+]
* Youtube: link:http://www.youtube.com/watch?v=_c-CCVy4_Eo[+Тестирование RESTful NetBeans и вызов ресурсов RESTful (Часть 2)+]

Для отправки комментариев и предложений, получения поддержки и новостей о последних разработках, связанных с Java EE IDE NetBeans link:../../../community/lists/top.html[+присоединяйтесь к списку рассылки nbj2ee@netbeans.org+].