Введение в веб-службы RESTful на Tomcat

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

В руководстве Начало работы с веб-службами RESTful на сервере GlassFish сначала приводится краткий обзор REST, а затем рассматривается поддержка этого архитектурного стиля в среде IDE NetBeans 6.0. В целях простоты усвоения это руководство составлено специально для сервера приложений GlassFish. Для запуска веб-служб RESTful на сервере Tomcat необходимо выполните ряд дополнительных задач по настройке. В этом руководстве используются те же источники, что и в документе Начало работы с веб-службами RESTful на сервере GlassFish, и описана процедура их развертывания на сервере приложений Tomcat.

Содержание

• Введение
• Копирование библиотек на сервер Tomcat
• Создание классов объектов из базы данных
• Добавление к проекту библиотеки Toplink
• Создание веб-служб RESTful из классов объектов
• Настройка файла сохранения состояния
• Тестирование веб-служб RESTful
• Добавление компонента "Google Map"

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

При необходимости сервер Tomcat может быть установлен при помощи дистрибутива "Web and Java EE" среды IDE NetBeans. Либо посетите страницу загрузок Apache Tomcat.

Для работы с этим руководством также требуется подключаемый модуль "RESTful Web Services". В среде IDE перейдите в диспетчер подключаемых модулей в меню "Tools" и проверьте, установлен ли подключаемый модуль "RESTful Web Services", на вкладке "Installed". Если нет, установите его на вкладке "Available Plugins", как показано ниже:

Введение

Веб-службы 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).

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

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

Перед работой с этим руководством следует ознакомиться с руководством Начало работы с веб-службами RESTful на сервере GlassFish, в котором описываются средства создания, реализации и тестирования веб-служб RESTful, предусмотренные в среде IDE. В этом руководстве представлена та же служба, но с дополнительными действиями по настройке, необходимыми для ее выполнения на сервере приложений Tomcat 6.0+.

Копирование библиотек на сервер Tomcat

Для поддержки веб-служб RESTful серверу Tomcat требуются интерфейсы API toplink, derby и javax. Помимо того, что эти библиотеки рекомендуется использовать при работе с данным руководством, они позволят запускать службы RESTful на сервере Tomcat в будущем.

В следующей таблице NB_HOME относится к каталогу установки NetBeans, TOMCAT_HOME к каталогу установки Apache Tomcat 6.x, а GLASSFISH_HOME – к каталогу установки GlassFish v2.

После копирования этих библиотек перезапустите компьютер.

toplink-essentials.jar
                    toplink-essentials-agent.jar

derbynet.jar
                    derbyclient.jar

Создание классов объектов из базы данных

Целью этого упражнения является создание проекта и классов объектов из базы данных.

Создание классов объектов из базы данных:

1. Выберите "File > New Project". В области "Categories" выберите "Web". В области "Projects" выберите "Web Application" и нажмите кнопку "Next".
2. В поле "Project Name" введите CustomerDB-Tomcat.
3. В узле "Server" выберите Apache Tomcat 6.0.x. Нажмите кнопку "Finish".
4. Щелкните правой кнопкой мыши узел CustomerDB-Tomcat и выберите "New > Entity Classes from Database". Откроется экран "Database Tables" мастера "New Entity Classes from Database".
5. На экране "Database Tables" выберите "New Data Source" в раскрывающемся списке "Data Source". Откроется диалоговое окно "Create Data Source".
6. В поле "JNDI Name" введите jdbc/sample. В раскрывающемся списке "Database Connection" выберите jdbc:derby://hostname:1527/sample [app on APP], как показано ниже. Нажмите кнопку "OK". Диалоговое окно закрывается, и выполняется возврат к экрану "Database Tables".
   
7. В поле "Available Tables" выберите CUSTOMER, а затем нажмите кнопку "Add". Таблица DISCOUNT_CODE, связанная с таблицей CUSTOMER, автоматически добавляется к списку "Selected Tables". Экран должен выглядеть следующим образом:
   
8. Нажмите кнопку "Next". Появится экран "Entity Classes".
9. В поле "Package" введите customer.db.tomcat.
10. Нажмите кнопку "Create Persistence Unit". Откроется диалоговое окно "Create Persistence Unit". Примите все значения по умолчанию и нажмите кнопку "Create". Выполняется возврат к экрану "Entity Classes". Нажмите кнопку "Finish".
11. Просмотрите окно "Projects". Экран должен выглядеть следующим образом:
    

Добавление к проекту библиотеки Toplink

Несмотря на то, что файлы Toplink были добавлены в Tomcat (см. Копирование библиотек в Tomcat), по-прежнему необходимо добавить к проекту библиотеку "TopLink Essentials" во избежание исключительных ситуаций при приведении классов. Эту библиотеку необходимо расположить выше остальных библиотек.

1. Щелкните правой кнопкой мыши узел проекта и выберите из контекстного меню "Properties". Откроется диалоговое окно "Project Properties".
2. В представлении "Categories" выберите "Libraries". Откроется вкладка с библиотеками этапа компиляции для проекта.
3. Нажмите кнопку "Add Library". Откроется диалоговое окно "Add Library", в котором представлен список доступных библиотек.
4. Выполните прокрутку до библиотеки "Top Link Essentials". Выберите эту библиотеку и нажмите кнопку "Add Library".
   
5. Теперь необходимо вернуться в диалоговое окно "Project Properties". Библиотека "TopLink Essentials" должна находиться в списке "Compile-time Libraries". Убедитесь, что установлен флажок "Package". Выберите "TopLink Essentials" и переместите ее в верхнюю часть списка библиотек при помощи кнопки "Move Up". Список библиотек этапа компиляции должен выглядеть следующим образом:
   
6. Нажмите кнопку "OK". Библиотека "TopLink Essentials" будет добавлена средой IDE в верхнюю часть списка библиотек проекта. Проверьте наличие библиотеки "TopLink Essentials" в узле проекта "Libraries". Список библиотек должен выглядеть следующим образом:
   
7. Для вступления в силу изменений перезапустите среду IDE. После перезапуска среды IDE перезапустите сервер базы данных Derby ("Tools > Java DB Database > Start Server").

Настройка файла сохранения состояния

В разделе Создание классов объектов из базы данных был создан блок сохранения состояния. Настройка единицы сохранения состояния содержится в файле persistence.xml. В окне "Projects" в узле "Configuration Files" находится файл persistence.xml проекта.

Этот файл сохранения состояния необходимо изменить для использования транзакции другого типа, отмены идентификации источника данных и передачи требуемых свойств поставщику сохранения состояния. Откройте persistence.xml в среде IDE. Откройте вкладку "XML". Измените файл для обеспечения его соответствия следующему фрагменту (добавляемые или изменяемые элементы выделены полужирным шрифтом):

<persistence-unit name="CustomerDB-TomcatPU" transaction-type="RESOURCE_LOCAL">
    <provider>oracle.toplink.essentials.PersistenceProvider</provider>

    <!-- <jta-data-source>jdbc/sample</jta-data-source> -->

    <properties>
      <property name="toplink.jdbc.user" value="app"/>
      <property name="toplink.jdbc.password" value="app"/>
      <property name="toplink.jdbc.url" value="jdbc:derby://localhost:1527/sample"/>
      <property name="toplink.jdbc.driver" value="org.apache.derby.jdbc.ClientDriver"/>
    </properties>
        </persistence-unit>

Создание веб-служб RESTful из классов объектов

Цель этого упражнения состоит в создании веб-служб RESTful из классов объектов, созданных ранее (см. Создание классов объектов из базы данных).

1. Щелкните правой кнопкой мыши пакет, содержащий классы объектов, и выберите "New > RESTful Web Services from Entity Classes". Откроется мастер "New RESTful Web Services from Entity Classes".
   
2. В поле "Available Entity Classes" должны отображаться два класса: "Customer" и "DiscountCode". При выборе "Add All" они перемещаются в список "Selected Entity Classes".
3. Нажмите кнопку "Next". Откроется экран "Generated Classes".
   

   Здесь отображаются все элементы, созданные в среде IDE. Для создания классов ресурсов в среде IDE используется модель "элемент-контейнер". Например, для класса объектов "Customer" в среде IDE создается ресурс контейнера "CustomersResource" и ресурс элемента "CustomerResource". Кроме того, для каждого класса ресурсов в среде IDE создается класс преобразования, используемый для создания представления ресурса из соответствующего экземпляра объекта, например, "CustomersConverter" и "CustomerConverter". Кроме того, для представления взаимосвязей существует дополнительный класс преобразования, называемый ссылочным преобразованием, например, "CustomerRefConverter".

   Примите значения по умолчанию и нажмите кнопку "Finish".

4. Просмотрите окно "Projects". Экран должен выглядеть следующим образом:
   

Узел "RESTful Web Services" в окне "Projects" теперь содержит все веб-службы RESTful в проекте. Значение в квадратных скобках, например, [/customers/], является значением для шаблона URI. По исходному файлу также можно перемещаться путем двойного щелчка этого узла. Также на этом экране отображаются все методы HTTP и методы поиска подресурсов. Как и в предыдущем случае, перемещаться по методам можно путем двойного щелчка узлов.

Теперь, после создания классов объектов и веб-служб RESTful, можно перейти к тестированию приложения. В IDE имеется удобная служебная программа для тестирования веб-служб RESTful. Она будет использоваться в следующем разделе.

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

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

1. Щелкните правой кнопкой мыши узел проекта и выберите "Test RESTful Web Services".

   Выполняется запуск сервера и развертывание приложения. Наконец, обозреватель должен отобразить приложение со ссылкой на каждую из веб-служб:
   

Слева расположен набор корневых ресурсов: customers и discountCodes.

2. Сначала выберите корневой ресурс customers. Щелкните раскрывающийся список "Methods" и выберите GET(application/xml) или GET(application/json). Нажмите кнопку "Test". Результат отображается в разделе "Test Output":
   
   

В разделе "Test Output" расположены 4 вкладки. В окне "Tabular" расположено упрощенное представление со всеми идентификаторами URI в документе результата, к которому можно перейти при помощи ссылок. В окне "Raw" отображаются фактически возвращенные данные. В зависимости от выбранного типа MIME (application/xml или application/json), данные будут представлены в формате XML или JSON соответственно. В окне "Headers" отображается информация заголовка HTTP. Вкладка "HTTP Monitor" содержит фактические запросы HTTP и ответы (переданные и принятые).

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

Добавление компонента "Google Map"

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

1. Откройте в редакторе класс CustomerResource, как показано ниже. В меню "Tools" выберите "Palette". Обратите внимание, что справа от редактора появляется палитра с фрагментами кода:
   
2. Подпишитесь для получения ключа карт Google по адресу http://www.google.com/apis/maps/signup.html. В диалоговом окне с запросом ключа для карт Google имеется поле для URL-адреса веб-сайта. В этом поле введите http://localhost:8080.
3. Из категории "Google" перетащите элемент "Map" в любое местоположение в классе. Откроется окно "Customize GoogleMap". Введите ключ Google Map в поле "apiKey", как показано ниже:
   

   Нажмите кнопку "OK". В среде IDE создается класс GoogleMapResource. Класс CustomerResource обращается к нему с помощью этого метода, который также создается средой IDE:

       /**
        * Возвращает подресурс "GoogleMapResource".
        */
       @Path("googleMap/")
       public GoogleMapResource getGoogleMap() {
           try {
               customer.db.tomcat.Customer entity = getEntity();
               String apiKey = null;
               String address = entity.getAddressline1();
               Integer zoom = null;
               return new GoogleMapResource(apiKey, address, zoom);
           } finally {
               PersistenceService.getInstance().close();
           }
       }

4. Щелкните правой кнопкой мыши узел проекта и снова выберите "Test RESTful Web Services". После открытия обозревателя щелкните googleMap. На экране должно отображаться следующее (с введенным ключом apiKey):
   
5. Нажмите кнопку "Test". На вкладке "Raw View" откроется карта Google:

   Важно:В Firefox 2 тестовый клиент зависает при попытке представления изображения. Выберите URL-адрес http:.../googleMap/ в узле Resource:. Изображение карты появится в обозревателе на новой вкладке.

   
   

Дополнительная информация

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

• Разработка клиентов веб-служб JAX-WS
• Начало работы с веб-службами JAX-WS
• Начало работы с веб-службами RESTful на сервере GlassFish
• Создание клиентских заглушек веб-службы RESTful
• Расширенные возможности взаимодействия веб-служб
• Учебная карта по приложениям на базе EJB и веб-службам

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