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

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

Содержание

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

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

Программное обеспечение или ресурс	Требуемая версия
Среда IDE NetBeans	Web & Java EE, версия 6.1
Комплект для разработчика на языке Java (JDK)	версия 6 или версия 5
Веб-сервер или сервер приложений, совместимый с Java EE	Веб-сервер Tomcat 6.0 и/или сервер приложений GlassFish v2 Важно: При использовании Tomcat с данным руководством см. вики-страницу NetBeans по использованию Tomcat с REST.

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

Введение

Веб-службы 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 в среде IDE.

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

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

1. Выберите "File > New Project". В области "Categories" выберите "Web". В области "Projects" выберите "Web Application" и нажмите кнопку "Next".
2. В поле "Project Name" введите CustomerDB.
3. В поле "Server" выберите GlassFish. Перейдите по остальным страницам и нажмите кнопку "Finish".
4. Откройте вкладку "Services". В разделе "Databases" щелкните правой кнопкой мыши "Java DB" и запустите ее.
5. Щелкните правой кнопкой мыши узел CustomerDB и выберите "New > Entity Classes from Database". Либо можно выбрать его из категории "Persistence" в мастере создания файлов (Ctrl-N).
6. На панели "Database Tables" выберите источник данных jdbc/sample в раскрывающемся поле "Data Source".

   Примечание: В Tomcat этот источник данных может не существовать. В таком случае выберите "New Data Source" в раскрывающемся поле "Data Source". Откроется диалоговое окно "Create Data Source". Введите "jdbc/sample" в поле "JNDI Name". В раскрывающемся поле "Database Connection" выберите "jdbc:derby://hostname:1527/sample [app on APP]". Нажмите кнопку "OK". Диалоговое окно закрывается, и выполняется возврат к экрану "Database Tables". См. также Руководство по веб-службам RESTful на Tomcat для среды IDE NetBeans 6.0.

7. В поле "Available Tables" выберите CUSTOMER, а затем нажмите кнопку "Add". Таблица "DISCOUNT_CODE", связанная с таблицей "CUSTOMER", автоматически добавляется к списку "Selected Tables". Экран должен выглядеть следующим образом:
   
   

   Нажмите кнопку "Next".

8. В поле "Package" введите customerdb. Экран должен выглядеть следующим образом:
   
9. Нажмите кнопку "Create Persistence Unit". Появится следующее диалоговое окно:
   

   Нажмите кнопку "Create", а затем кнопку "Finish".

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

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

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

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

   Здесь отображаются все элементы, созданные в среде 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 в редакторе.
2. Добавьте к CustomerResource следующие методы:

   @GET
   @ProduceMime("text/html")
   public String getGoogleMap() {
   // Перетащите сюда операцию "getGoogleMap"
   
      return "";
   }
   
   //Вызывается путем перехода к обозревателю и обращения к любому клиенту (т.е. /customers/1/googleMap).
   /**
    * Returns sub-resource.
    */
   @Path("googleMap/")
   @GET
   @ProduceMime("text/html")
   public String getGoogleMapResource() {
       return getGoogleMap();
   }

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

   К классу CustomerResource добавляется following try block to the getGoogleMap method in t:

   @Path("googleMap/")
   @GET
   @ProduceMime("text/html")
   public String 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 null;
   }

   Также в проекте создаются следующие классы и ресурсы:

   • RestConnection – обертка для "HttpUrlConnection".
   • RestResponse – обертка для ответа HTTP.
   • GoogleMapServiceAuthenticator – класс, получающий значение для "ApiKey" из свойств "googlemapserviceauthenticator.properties".
   • googlemapserviceauthenticator.properties – файл свойств, в котором хранится ключ интерфейса API.
   • GoogleMapService – обертка службы, содержащая методы обертки и использующая RestConnection для вызова службы "Google Map".

6. Замените блок "try" метода "getGoogleMap" следующим кодом:

   @Path("googleMap/")
   @GET
   @ProduceMime("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();
        //TODO - Раскомментируйте оператор "print" ниже для вывода результата.
        //System.out.println("The SaasService returned: "+result.getDataAsString());
        } catch (Exception ex) {
            ex.printStackTrace();
        } 
        return "";
   }

7. Откройте googlemapserviceauthenticator.properties. Set the api_key property equal to the API key you got from Google in Step 3.
8. Откройте вкладку "Services" и запустите сервер приложений.
9. Щелкните правой кнопкой мыши узел проекта "CustomerDB" и выберите "Test RESTful Web Services". Выполняется отмена развертывания и повторное развертывание проекта на сервере, а затем открывается окно обозревателя с тестовым клиентом.
10. Щелкните customers на левой панели. В главном окне открываются критерии тестирования для customers. Примите значения по умолчанию и нажмите кнопку "Test". Откроется таблица клиентов.
11. Выберите клиента из таблицы, например "customer1". Щелкните клиента. Критерии тестирования для этого клиента открываются в главном окне. В раскрывающемся списке выберите тип MIME text/html. Нажмите кнопку "Test". В представлении "Raw View" открывается GoogleMap для этого адреса.

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

    
    

    

12. Для просмотра местоположения всех клиентов на карте URL-адрес можно заменить на http://localhost:8081/CustomerDB/resources/customers/2/googleMap, .../3/googleMap, и т.д. до 25.

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

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

• Создание клиентских заглушек веб-службы RESTful
• Разработка клиентов веб-служб JAX-WS
• Начало работы с веб-службами JAX-WS
• Использование веб-служб StrikeIron в веб-приложениях
• Расширенные возможности взаимодействия веб-служб
• Учебная карта по приложениям на базе EJB и веб-службам
• YouTube: Веб-службы RESTful: сборка и развертывание (Часть 1)
• YouTube: NetBeans: тестирование и вызов ресурсов RESTful (Часть 2)

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