Начало работы с веб-службами RESTful

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

Содержание

• Введение
• Веб-службы RESTful, сохранение состояния, классы сущностей
• Создание веб-служб RESTful из базы данных
  • Создание проекта
  • Создание классов сущностей и служб RESTful
• Тестирование веб-служб RESTful
• Добавление функциональности Google Map
• Веб-службы RESTful на платформе Spring
  • Создание веб-приложений Java с помощью платформы Spring
  • Добавление aopalliance.jar к проекту
  • Создание служб RESTful в проекте с поддержкой Spring
  • Ошибки компиляции

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

Программное обеспечение или ресурс	Требуемая версия
Среда IDE NetBeans	Набор загрузки Java EE
Комплект для разработчика на языке Java (JDK)	Версия 6 или 7
Веб-сервер или сервер приложений, совместимый с Java EE	Веб-сервер Tomcat 6.x-7.x, Oracle WebLogic Server 11g-12c, или GlassFish Server Open Source Edition 3.x. Важно: при использовании сервера Tomcat при работе с этим учебным курсом воспользуйтесь вики-страницами NetBeans по использованию Tomcat с REST.
База данных jdbc/sample на сервере базы данных Java DB (Derby) или сервере базы данных MySQL. сервер базы данных	На сервере Java DB (Derby) база данных jdbc/sample создается средой IDE NetBeans при установке среды IDE с сервером приложений GlassFish. На MySQL среда IDE заполняет пример базы данных после создания его на сервере MySQL изнутри IDE.

Серверы Tomcat и GlassFish могут быть установлены при помощи дистрибутива "Web и Java EE" среды IDE NetBeans. Также можно воспользоваться страницей загрузок GlassFish Server или страницей загрузок Apache Tomcat.

Важно! Для работы с проектами Java EE 6 необходим Tomcat 7.x или GlassFish Server 3.x, или Oracle WebLogic Server 12c.

Введение

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

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

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

• JSR 311: JAX-RS: интерфейс API Java для веб-служб RESTful
• 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 в проекте;
6. полностью интегрированная платформа Spring с возможностью обработки транзакций Spring.

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

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

Веб-службы RESTful в Java используют интерфейс API сохранения состояния Java для связи с базами данных. Говоря конкретнее, веб-службы RESTful используют классы сущностей и блок сохранения состояния как они определены в интерфейсе API сохранения состояния. Классы сущностей – это классы Java, сопоставленные с объектами в реляционной базе данных. Согласно руководству по Java EE5: "Сущностью называется упрощенный объект области сохранения состояния. Как правило, сущность представляет таблицу в реляционной базе данных, и каждый экземпляр сущности соответствует строке в этой таблице. Блок сохранения состояния состоит из набора сущностных классов, источника данных, поставщика сохранения состояния и собственного имени блока сохранения состояния, как определено в файле persistence.xml.

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

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

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

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

1. Зарегистрируйте сервер MySQL в среде IDE, если он еще не зарегистрирован. Чтобы зарегистрировать сервер MySQL, перейдите к окну Services ("Службы") среды IDE, щелкните правой кнопкой мыши узел Databases ("Базы данных") и выберите Register MySQL Server ("Зарегистрировать сервер MySQL").
   

2. Откроется диалоговое окно, в которое следует ввести параметры своего сервера MySQL, включая имя и пароль пользователя, являющегося администратором. См. раздел "Настройка свойств сервера MySQL" в разделе Подключение к базе данных MySQL.

   
3. Запустите сервер MySQL и подключитесь к нему. См. раздел "Запуск сервера MySQL" в разделе Подключение к базе данных MySQL.
4. Щелкните правой кнопкой мыши узел сервера MySQL и выберите Create Database ("Создать базу данных"). Откроется диалоговое окно создания базы данных MySQL.
   
5. Введите sample в качестве имени новой базы данных. Предоставьте полный доступ корневому пользователю или пользователю по своему выбору.
   
6. Нажмите кнопку "ОК". Откроется диалоговое окно, сообщающее, что именем примера базы данных является sample и спрашивающее, следует ли создать таблицы, объекты и данные для этой базы данных.
   
7. Нажмите кнопку "Да". Среда IDE создаст и заполнит базу данных, а также добавит подключение к ней.
   

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

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

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

Теперь среда IDE создаст веб-службы RESTful. Когда среда IDE выполнит это, загляните в окно Projects ("Проекты"). Созданные сущностные классы находятся в пакете entities. Службы находятся в пакете service. В проекте EE5 классы контроллера JPA будут находиться в пакете controller, а дескриптор развертывания web.xml в Configuration Files ("Файлы настройки").

Внимание! Среда IDE может выдать запрос Resolve Reference Problems ("Разрешить проблемы ссылок") для проекта. В этом случае щелкните правой кнопкой мыши узел проекта CustomerDB и выберите Resolve Reference Problems ("Разрешить проблемы ссылок"). Эта проблема может возникнуть, когда служба является первым приложением Jersey, запущенном на установленном экземпляре WebLogic. В этом случае среда IDE разрешит проблемы ссылок, скопировав библиотеки Jersey на сервер.

Веб-службы RESTful EE6 создают экземпляр EntityManager в каждом классе службы. Это устраняет нужду в классах контроллеров JPA и упрощает код.

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

Целью этого упражнения является тестирование приложения.

1. Щелкните узел проекта правой кнопкой мыши и выберите "Тестировать веб-службы RESTful". Откроется диалоговое окно, запрашивающее, следует ли создать тестовый клиент внутри проекта службы или в другом веб-проекте Java. Это позволяет обойти ограничения безопасности в некоторых обозревателях. Можно использовать любой веб-проект, если он настроен на развертывание в том же домене сервера, что и проект CustomerDB.
   
2. Выберите, где следует создать тестовый клиент, и нажмите кнопку OK. Будет выполнен запуск сервера и развертывание приложения. По завершении развертывания приложение отобразится в обозревателе с ссылками на все веб-службы.

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

   

   Слева расположен набор корневых ресурсов. В этом учебном курсе им присвоены имена customers и discountCodes.

3. Щелкните узел customers. В диалоговом окне обозревателя отображается список параметров для тестирования службы Customers.
   

   Возможна установка следующих параметров:

   • Выберите метод для тестирования. Выберите метод GET или POST и тип MIME из раскрывающегося списка.
   • Начало. Первая отображаемая сущность. Обратите внимание, что нумерация начинается с "0", а не с "1".
   • Максимум. Максимальное число выбираемых сущностей. При установке значения "0" выбираются все сущности.
   • Уровень развертки. Расширенная функция. Некоторые службы возвращают повторяющуюся структуру дерева иерархии. Этот параметр служит для указания глубины отображения таких иерархий в представлении необработанных данных.
   • Запрос. Расширенная функция. Этот параметр служит для поиска документа XML или JSON в соответствии с синтаксисом JPA.
4. Откройте раскрывающийся список методов и выберите метод GET(application/xml). Введите значение "3" в качестве максимального значения. Оставьте значения по умолчанию, определенные для остальных параметров, и нажмите кнопку тестирования. Результат отображается в разделе результатов тестирования
   

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

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

   Обратите внимание, что список результатов состоит из 6 пунктов, хотя в качестве максимального значения отображаемых сущностей установлено значение "3". Откройте вкладку представления необработанных данных для просмотра причины. Каждая сущность соответствует элементу <customer>, и в результате тестирования существует только 3 клиента. Однако на вкладке табличного представления указаны идентификаторы URI, а не сущности. Каждая сущность имеет два идентификатора URI: один является атрибутом родительского элемента <customer>, второй – атрибутом дочернего элемента <discountCode>. Таким образом, несмотря на то, что существует только 3 сущности клиента, в итоге используются 6 идентификаторов URI.

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

Добавление функциональности Google Map

Целью этого упражнения является добавление функциональности Google Map в веб-службы RESTful.

1. Откройте класс CustomerRESTFacade (EE 5) или класс CustomerFacadeREST (EE 6) в редакторе.
2. Добавьте к классу следующий метод:

   @GET
   @Produces("text/html")
   public String getGoogleMap() {
   // Перетащите сюда операцию getGoogleMap
      return "";
   }

3. Подпишитесь на получение ключа карт Google по адресу http://www.google.com/apis/maps/signup.html. Диалоговое окно запроса на ключ карт Google содержит поле для ввода URL-адреса веб-сайта. Введите в это поле адрес http://localhost:8080.
4. Откройте в среде IDE вкладку "Службы" и разверните узел "Веб-службы". Разверните в узле "Веб-службы" узел "Google". В узле "Google" откройте узел службы карт.
   
   
5. Перетащите элемент getGoogleMap в тело метода getGoogleMap, созданного в действии 2, в позицию над строкой return = "";. Откроется диалоговое окно настройки getGoogleMap SAAS. Примите настройки по умолчанию и нажмите кнопку "ОК".

   В среде IDE в метод getGoogleMap класса CustomerResource будет добавлен блок try, как показано в примере кода ниже.

   @GET
   @Produces("text/html")
   public String getGoogleMap() {
   // Перетащите сюда операцию getGoogleMap
           
       try {
                
            String address = "16 Network Circle, Menlo Park";
            java.lang.Integer zoom = 15;
            String iframe = "false";
            RestResponse result = GoogleMapService.getGoogleMap(address, zoom, iframe);
            //TODO - раскомментируйте оператор print ниже для вывода результата.
            //System.out.println("The SaasService returned: "+result.getDataAsString());
       } catch (Exception ex) {
            ex.printStackTrace();
       }
   
       return "";
   
   }
                   

   Кроме того, создаются пакеты org.netbeans.saas и org.netbeans.saas.google, содержащие следующие классы и ресурсы:

   • RestConnection – обертка для HttpUrlConnection
   • RestResponse – обертка для ответа HTTP
   • googlemapservice.properties – файл свойств, где хранится ключ интерфейса API
   • GoogleMapService – обертка службы, содержащая методы обертки, использующие RestConnection для выполнения вызовов к службе Карт Google.
   
6. Замените в блоке try элемента getGoogleMap() закомментированный оператор print на строку return result.getDataAsString();. Теперь метод выглядит следующим образом:

   @GET
   @Produces("text/html")
   public String getGoogleMap() {
   // Перетащите сюда операцию getGoogleMap
           
       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 "";
   }

7. Откройте googlemapservice.properties. Вставьте ключ интерфейса API, полученный от Google в действии 3.
8. Щелкните правой кнопкой мыши узел проекта CustomerDB и выберите пункт "Тестирование веб-служб RESTful". Будет выполнена отмена развертывания и повторное развертывание проекта на сервере, а также откроется диалоговое окно обозревателя с клиентом тестирования.
9. Щелкните элемент customers, расположенный слева. На главной странице будут выведены критерии тестирования для ресурса customers. Оставьте параметры настройки по умолчанию и нажмите кнопку тестирования. Появится таблица с клиентами.
10. Щелкните в таблице элемент customer1. На главной панели отобразится диалоговое окно тестирования для этого клиента. Выберите в раскрывающемся списке пункт text/html в качестве типа MIME. Нажмите кнопку тестирования. В представлении необработанных данных появится карта Google для адреса 16 Network Circle, Menlo Park.
    

11. Карта Google для адреса Menlo Park появится для всех клиентов в базе данных. Для отображения карт Google с реальными адресами клиентов, создайте экземпляр Customer и установите адрес, равный конкатенации переменных адресов для этого экземпляра Customer.

    Для службы EE5 используйте метод getEntity(), чтобы создать экземпляр Customer для каждой сущности в базе данных (изменения выделены жирным шрифтом):

    Служба EE5:

    @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();
         } 
    
         
         return "";
     }

    Для службы EE6 создайте экземпляр Customer, вызвав универсальный метод find() из абстрактного фасадного метода. Универсальный метод find() требует явного приведения типа аргумента к Object и явной установки идентификатора сущности. Следующий код EE6 отображает на карте местоположение клиента с идентификатором номер 1 (изменения выделены жирным шрифтом):

    Служба EE6:

    @GET
    @Produces("text/html")
    public String getGoogleMap() {
        try {
             Customer c = getEntityManager().find(Customer.class, 1);
             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();
         } 
    
         
         return "";
     }

12. Снова протестируем веб-службы RESTful. В случае службы EE5 выберите тип MIME text/html для одного из покупателей. Теперь карта Google для адреса этого клиента отображается в представлении необработанных данных. В случае службы EE6 идентификатор клиента указан как аргумент для метода find(), а средство тестирования по умолчанию отображает представление необработанных данных. Для клиента customer1 отображается следующая карта:
    

    Примечание. Если GoogleMaps не удается найти адрес, отображается вид океана в увеличенном масштабе.

Веб-службы RESTful на платформе Spring

Jersey интегрирована в платформу Spring. При создании веб-приложения на Java с использованием платформы Spring автоматически создается сервлет, поддерживающий REST. Однако Spring 3 не содержит файла aopalliance.jar, необходимого веб-службе RESTful для внедрения объекта EntityManager.

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

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

• Использование NetBeans для создания упрощенных веб-служб RESTful
• Создание клиентов службы RESTful в модулях NetBeans
• Учебная карта по веб-службам
• YouTube: веб-службы RESTful, создание и разработка (часть 1)
• YouTube: NetBeans RESTful: тестирование и запуск ресурсов RESTful (часть 2)

Оставить комментарии и предложения, обратиться за поддержкой и получить информацию о последних достижениях в области функциональных возможностей разработки для Java EE с помощью среды IDE NetBeans можно в списке рассылки .