Создание SOAP Web-сервиса
Этот урок освещает пошаговое создание сервера SOAP web сервиса с использованием Spring.
Что вы создадите
Вы создадите сервер, который предоставляет данные из различных Европейских стран, используя WSDL SOAP web сервис.
Что вам потребуется
Как проходить этот урок
Как и большинство уроков по Spring, вы можете начать с нуля и выполнять каждый шаг, либо пропустить базовые шаги, которые вам уже знакомы. В любом случае, вы в конечном итоге получите рабочий код.
Чтобы начать с нуля, перейдите в Настройка проекта.
Настройка проекта
Для начала вам необходимо настроить базовый скрипт сборки. Вы можете использовать любую систему сборки, которая вам нравится для сборки проетов Spring, но в этом уроке рассмотрим код для работы с Gradle. Если вы не знакомы с ней, ознакомьтесь с соответсвующим уроком Сборка Java-проекта с использованием Gradle.
Создание структуры каталогов
Создание файла сборки Gradle
Ниже представлен начальный файл сборки Gradle. Если вы используете Spring Tool Suite (STS), то можете импортировать урок прямо из него.
Spring Boot gradle plugin предоставляет множество удобных возможностей:
Добавление Spring-WS зависимости
Созданный вами проект должен включать в ваш файл сборки зависимости spring-ws-core и wsdl4j.
Создание XML схемы для определения домена
Домен web сервиса описан в файле XML схемы(XSD), который Spring-WS будет экспортировать автоматически как WSDL.
Создайте XSD файл с операциями для возвращения name, population, capital и currency:
Генерация доменных классов на основе XML схемы
Следубщим шагом необходимо сгенерировать Java классы из XSD файла. Правильным подходом является их автоматическое создание в процессе сборки с использованием плагина maven или gradle.
Конфигурация плагина для maven:
Сгенерированные классы будут помещены в target/generated-sources/jaxb/ каталог.
То же самое и с gradle:
Т.к. gradle не имеет JAXB плагина(пока), он включает в себя ant задачу, которая делает файл сборки немного сложнее по сравнению с файлом сборки Maven.
В обоих случаях, процесс генерации объектов включен в жизненный цикл сборки, поэтому не требуются отдельные шаги по запуску этого процесса.
Создание репозитория
Для предоставления данных web сервисом, создайте репозиторий. В этом уроке вы создаете простой репозиторий с установленными данными.
Создание точки выхода сервиса
Для создания точки выхода сервиса, вам необходим только POJO с несколькими Spring WS аннотациями для обработки входящих SOAP запросов.
@Endpoint регистрирует класс Spring WS как потенциальный кандидат для обработки входящих SOAP сообщений
@PayloadRoot используется Spring WS для выбора метода обработчика на основе namespace и localPart сообщения
@RequestPayload указывает на то, что входящее сообщение будет сопоставлено параметру request метода
@ResponsePayload создает соответствующее значение возвращаемому значению полезной части ответа.
Конфигурирование бинов web сервиса
Создайте новый класс, связанный с конфигурацией Spring WS бинов:
Создание приложения исполняемым
Несмотря на то, что пакет этого сервиса может быть в составе web-приложения и WAR файлов, более простой подход, продемонстрированный ниже создает отдельное самостоятельное приложение. Вы упаковываете все в единый, исполняемый JAR-файл, который запускается через хорошо знакомый старый main() Java-метод. Попутно, вы используете поддержку Spring для встроенного Tomcat контейнера сервлетов как HTTP среду выполнения вместо развертывания на сторонний экземпляр.
Сборка исполняемого JAR
Вы можете собрать единый исполняемый JAR-файл, который содержит все необходимые зависимости, классы и ресурсы. Это делает его легким в загрузке, версионировании и развертывании сервиса как приложения на протяжении всего периода разработки, на различных средах и так далее.
Затем вы можете запустить JAR-файл:
Запуск приложения
Если вы используете Gradle, вы можете запустить ваш сервис из командной строки:
Как вариант, вы можете запустить ваш сервис напрямую из Gradle примерно так:
Тестирование приложения
Существует несколько способов тестирования SOAP интерфейса. Вы можете использовать что-то типа SoapUI или просто использовать инструменты командной строки, если у вас *nix/Mac система, как показано ниже:
В результате вы должны увидеть следующий ответ:
Поздравляем! Вы только что создали SOAP сервис с использованием Spring Web Services.
SOAP Web-сервис средствами Spring-WS
Когда-то поставили передо мной задачу начать разработку Web-сервисов и дали мне сорцы простейшего проекта без каких-либо объяснений. Проект, конечно же, не запускался. Что такое Spring и как он работает, я тоже представления не имел. Адекватных статей по разработке Web-сервисов средствами Spring ни русскоязычных, ни англоязычных я тоже не смог найти. Пришлось разбираться во всем самому, оказалось все не так страшно.
И вот недавно я решил посмотреть, какие новые возможности добавились в Spring с тех пор, и обновить старые сервисы, что в результате и сподвигло меня на написание данной статьи.
Данная статья является руководством по разработке простейшего Web-сервиса, использующего SOAP-протокол, средствами Spring-WS.
И так, писать будем простейший сервис, принимающий имя пользователя и отправляющий приветствие и текущее время на сервере.
Что же нам потребуется?
Подготовка к работе
Создаем новый проект Web-приложения. В Eclipse это: «File => New => Dynamic Web Project».
Я назвал проект: HelloService.
Далее копируем библиотеки из Spring, XMLBean, wsdl4j, commons-logging в каталог проекта WEB-INF/lib.
При желании можете добавить их к библиотекам сервера, чтобы не таскать их с каждым приложением.
Создание WSDL-схемы
По сути WSDL-схема предназначена для описания сервиса.
Вручную создавать её мы, конечно же, не будем. Схема будет сгенерирована автоматически средствами Spring’а, но об этом позднее.
Определяем входные и выходные данные
Создаем описание входных и выходных данных
В каталоге WEB-INF создаем файл HelloService.xsd. Данный файл нужен будет для генерации WSDL-схемы и создания соответствующих Java-классов.
Текст файла:
Атрибут targetNamespace – используемое пространство имен. Т.е. все созданные объекты будут располагаться в пакете org.example.helloService.
Элементы ServiceRequest и ServiceResponse описывают соответственно входные и выходные данные (запрос/ответ).
Атрибуты minOccurs и maxOccurs определяют количество повторений данного компонента в пределах одного элемента. Если эти параметры не указывать, то по умолчанию они считаются равными 1. Для необязательного компонента необходимо указать minOccurs=0. При неограниченном количестве компонент: maxOccurs=unbounded.
Подробнее о XML-схемах можно прочитать здесь.
Создаем JavaBeans
На основании созданной схемы будем создавать Java классы. Для этого создаем файл build.xml:
Параметр WS_HOME должен указывать на каталог, где располагается XMLBeans.
HelloService.xsd – путь к созданной схеме.
lib\helloservice.jar – создаваемая java-библиотека.
Реализация сервиса
Создаем интерфейс и класс сервиса
Интерфейс сервиса: HelloService.java:
Реализация сервиса: HelloServiceImpl.java:
Данный код, я думаю, не нуждается в комментариях. Единственное, что у людей, не сталкивающихся ранее со Spring’ом, может вызвать вопросы, так это аннотация @ Service. Но об этом же расскажу чуть позже.
Endpoint
Endpoint – класс, который будет отвечать за обработку входящих запросов (своего рода точка входа).
Создаем файл HelloServiceEndpoint.java:
Что же здесь сделано?
Аннотация @Endpoint как раз и определяет, что данный класс будет обрабатывать входящие запросы.
namespaceUri – то же пространство имен, что и указывалось при создании xml-схемы.
Теперь вернемся немного назад и вспомним про аннотацию @ Service. Если не вдаваться в подробности, чтобы не перегружать читателя лишней информацией, то эта аннотацию говорит Spring’у создать соответствующий объект. А аннотация @Autowired служит для инъекции (автоматической подстановки) соответствующего объекта. Конечно же при построении простых приложений в использовании данных аннотаций отсутствует смысл, но я решил все-такие не исключать их в данном примере.
И так, идем далее.
Аннотация @PayloadRoot перед методом определяет, при получении какого запроса будет вызван данный метод. В нашем случае, это «ServiceRequest».
В остальном опять же все должно быть ясно. Обратите внимание, что ServiceRequest, ServiceResponse и т.д. – это как раз те классы, которые были созданы на основе нашей xml-схемы.
Spring-конфигурация сервиса
Вот и близится уже завершение.
Создаем файл service-ws-servlet.xml.
sws:annotation-driven – говорит как раз о том, что в данном проекте используются аннотации.
А context:component-scan указывает на пакет, в котором будет производится поиск аннотаций, при этом поиск производится и в подпакетах.
Два последующих бина всегда будут неизменны. Суть их заключается в приеме и преобразовании запроса из Xml в Java-объект и дальнейшего обратного преобразования.
sws:dynamic-wsdl отвечает за автоматическую генерацию WSDL-документа на основе созданной Xml-схемы.
location указывает на путь к схеме.
locationUri – адрес (относительно контейнера), по которому будет доступна WSDL-схема.
В моем случае WSDL доступен по следующему адресу:
localhost/HelloService/HelloService.wsdl
Дескриптор развертывания
Ну и, наконец, последнее.
В каталоге WEB-INF изменяем или создаем файл web.xml.
Данный файл описывать уже не буду, большинство и так должны знать. Для несложных проектов он по сути не должен изменяться. Стоит отметить только, что имя сервлета(servlet-name) должно соответствовать имени файла Spring-конфигурации сервиса service-ws-servlet.xml.
Ну и далее деплоим приложение на сервер.
На этом создание сервиса завершено. Если ничего не пропустили, то сервис должен функционировать.
Проверка работоспособности
Самым первым признаком корректной работы является созданная WSDL-схема.
Для проверки просто переходим по адресу этой схемы (http://localhost/HelloService/HelloService.wsdl) и смотрим: там должен отобразиться xml-файл. Если ничего не отобразилось или какая ошибка появилась, перечитываем внимательно всю статью и ищем, что сделали не так.
Для дальнейшей проверки нам потребуется soapUI (у меня версия 3.0.1).
Устанавливаем и запускаем его.
Создаем новый проект: File => New soapUI Project. В поле Initial WSDL/WADL вставляем ссылку на WSDL-схему (http://localhost/HelloService/HelloService.wsdl).
В созданном проекте открываем необходимый запрос.
В поле Name вбиваем имя и жмем на кнопку «Send request»
В результате получаем ответ от сервера с приветствием и текущим временем.
Если что-то пошло не так, то опять перечитываем данную статью.
Тестирование API
Введение: Что такое API
В широком смысле слова API (Application Programming Interface) это метод который приложение предоставляет внешним пользователям для коммуникации с ним. Обычно через Интернет.
Это может быть взаимодействие с сервером приложения на смартфоне, между компьютерами или другими устройствами.
API применяются там где невозможна или нежелательна непосредственная интеграция с исходным приложением, то есть практически везде.
Крупные интернет-компании обычно предоставляют (платно или бесплатно) доступ к API своих сервисов.
Где применяют API
Сейчас будет несколько абстрактных примеров просто для понимания сути.
Конкретные примеры работы с API я разбираю в учебнике
Пример №1:
Если Вы хотите разместить на своём сайте яндекс-карты Вам не нужно устанавливать программы от Яндекса, достаточно послать несколько запросов и Яндекс передаст необходимую информацию.
Пример №2:
Предположим, что Вы создали сайт vk2.com. Вы хотите, чтобы вебмастера могли добавить на свои сайты возможность комментировать записи используя учётную запись vk2, но раскрывать или раздавать свой код не хотите.
Чтобы обойти эту проблему Вы выкладываете в публичном доступе правила, по которым вебмастера могут обращаться к vk2, чтобы получить комментарии.
Формат этих сообщений это обычно либо JSON либо XML. О них мы поговорим позже.
Повторим для закрепления сути: Смысл в том, что сайт написанный на любом языке, поддерживающем HTTP запросы, не посылает на сервер никаких PHP/C/Python команд, а общается ним с помощью запросов, описанных в API.
Если вам интересен реальный пример работы с API рекомендую статью Работа с API GitHub
Endpoint
Адрес, на который посылаются сообщения называется Endpoint.
Обычно это URL (например, название сайта) и порт. Если я хочу создать веб сервис на порту 8080 Endpoint будет выглядеть так:
Если моему Web сервису нужно будет отвечать на различные сообщения я создам сразу несколько URL (interfaces) по которым к сервису можно будет обратиться. Например
https://andreyolegovich.ru:8080 /resource1/status
https://andreyolegovich.ru:8080 /resource1/getserviceInfo
https://andreyolegovich.ru:8080 /resource1/putID
http://andreyolegovich.ru:8080 /resource1/eventslist
https://andreyolegovich.ru:8080 /resource2/putID
…
Как видите у моих эндпойнтов (Enpoints) различные окончания. Такое окончание в Endpoint называются Resource, а начало Base URL.
Такое определение Endpoint и Resource используется, например, в SOAP UI для RESTful интерфейсов
Endpoint = Base URL + Resource
Понятие Endpoint может использоваться в более широком смысле. Можно сказать, что какой-то определённый роутер или компьютер является Endpoint. Например, в понятии Endpoint Management под Endpoint имеют в виду конечное устройство. Обычно это понятно из контекста.
Также следует обратить внимание на то, что понятие Endpoint выходит за рамки RESTful и может использовать как в SOAP так и в других протоколах.
Термин Resource также связан с RESTful, но в более широком смысле может означать что-то другое.
На программистском сленге Endpoint иногда называют ручкой.
Спецификация
После того все эти интерфейсы созданы, их необходимо описать. Нужен документ из которого будет понятно
Этот документ должен быть доступен программистам с обеих сторон, иначе они просто не смогут договориться и реализовать работающий Web сервис.
HTTP методы
Вернёмся к первому пункту списка, а именно к тому, что такое методы.
В протоколе HTTP предусмотрено несколько способов отправить запрос на один и тот же Endpoint.
Про их свойства можно почитать здесь.
Когда мы знаем какие методы с какими Enpoint можно использовать составить запросы не составит труда.
GET http://andreyolegovich.ru:8080 /resource1/status
GET http://andreyolegovich.ru:8080 /resource1/getserviceInfo
PUT http://andreyolegovich.ru:8080 /resource1/putID
GET http://andreyolegovich.ru:8080 /resource1/eventslist
POST http://andreyolegovich.ru:8080 /resource1/eventslist
PUT http://andreyolegovich.ru:8080 /resource2/putID
…
Таким образом простейший запрос состоит из метода и Enpoint
Request = Method + Endpoint
Пример API
Чтобы узнать количество велосипедистов в городе нужно отправить GET запрос на https://topbicycle.ru:/bicyclists/$город
GET https://topbicycle.ru /bicyclists/helsinki
Получив такой запрос сайт вернёт число велосипедистов в Хельсинки.
Попробуйте вставить эту строку в браузер.
Это очень простые уроки для самых начинающих. Буду рад любым отзывам и предложениям в комментариях.
Тестирование API без документации
Если Вам по какой-то причине предстоит проделать эту неблагодарную работу, определетесь, насколько всё плохо. Какая у Вас есть информация об объекте тестирования.
Известно ли какие порты для Вас открыты? Знаете ли Вы нужные endpoints?
Сканирование портов
Перебор запросов
Если Вам известен нужный порт и соответствующий endopoint переберите все возможные HTTP методы. Начните с наиболее очевидных:
В худшем случае, когда ни порт ни endpoints неизвестны Вам, скорее всего придётся перебирать все открытые порты и генерировать endpoints, которые подходят по смыслу.
Разработчики обычно не особо заморачиваются и закладывают минимально-необходиму информацию. Так что включите воображение и попробуйте придумать endpoints опираясь на бизнес логику и принятые в Вашей компании стандарты.
Если ни endpoints ни бизнес логика Вам неизвестны, то у меня есть подозрение, что Вы тестируете API с не самыми хорошими намерениями.
Инструменты для тестирования
Существует множество инструментов для тестирования. Здесь Вы можете познакомиться с одними из самых популярных: Python и SOAP UI.
О работе с REST API на Python вы можете прочитать в статье «REST API с Python»
SOAP and HTTP Endpoints
The SoapAndHttpEndpoints sample demonstrates how to implement an RPC-based service and expose it in the SOAP format and the «Plain Old XML» (POX) format using the WCF Web Programming model. See the Basic HTTP Service sample for more details about the HTTP binding for the service. This sample focuses on the details that pertain to exposing the same service over SOAP and HTTP using different bindings.
Demonstrates
Exposing an RPC service over SOAP and HTTP using WCF.
Discussion
This sample consists of two components: a Web Application project (Service) that contains a WCF service and a console application (Client) that invokes service operations using SOAP and HTTP bindings.
The WCF service exposes 2 operations – GetData and PutData – that echo the string that was passed as input. The service operations are annotated with WebGetAttribute and WebInvokeAttribute. These attributes control the HTTP projection of these operations. In addition, they are annotated with OperationContractAttribute, which enables them to be exposed over SOAP bindings. The service’s PutData method throws a WebFaultException, which gets sent back over HTTP using the HTTP status code and gets sent back over SOAP as a SOAP fault.
The Web.config file configures the WCF service with 3 endpoints:
/service.svc/mex endpoint that exposes the service metadata for access by SOAP-based clients.
/service.svc/http endpoint that enables clients to access the service using the HTTP binding.
/service.svc/soap endpoint that allows the clients to access the service using the SOAP over HTTP binding.
/service.svc/http/help that HTTP-based clients can use to access the service.
The client project demonstrates accessing the service using a SOAP proxy (generated through Add Service Reference) and accessing the service using WebClient.
The sample consists of a Web-hosted service and a console application. As the console application runs, the client makes requests to the service and writes the pertinent information from the responses to the console window.
To run the sample
Open the solution for the SOAP and HTTP Endpoints Sample.
Press Ctrl+Shift+B to build the solution.
If it is not already open, press CTRL+W, S to open the Solution Explorer window.
From the Solution Explorer window, right-click the Service project and place the cursor over the Debug context menu option so that the Start New Instance context menu appears. Click Start New Instance. This launches the ASP.NET development server, which hosts the service.
From the Solution Explorer windows, right-click the Client project and place the cursor over the Debug context menu option so that the Start New Instance context menu appears. Click Start New Instance.
The client console window appears and provides the URI of the running service and the URI of the HTML help page for the running service. At any point in time you can view the HTML help page by typing the URI of the help page in a browser.
As the sample runs, the client writes the status of the current activity.
Press any key to terminate the client console application.
Press SHIFT+F5 to stop debugging the service.
Практическое руководство. Предоставление контрактов SOAP- и веб-клиентам
по умолчанию Windows Communication Foundation (WCF) делает конечные точки доступными только для клиентов SOAP. В процедуре создания базовой веб-службы HTTP WCFконечная точка становится доступной для клиентов, не относящихся к протоколу SOAP. Иногда может потребоваться сделать один и тот же контракт доступным обоими способами: в качестве сетевой конечной точки и в качестве конечной точки SOAP. В данном разделе приводится пример того, как это сделать.
Определение контракта службы
Определите контракт службы с помощью интерфейса, помеченного ServiceContractAttribute WebInvokeAttribute атрибутом, и WebGetAttribute атрибутов, как показано в следующем коде:
По умолчанию атрибут WebInvokeAttribute сопоставляет с операцией вызовы POST. Однако можно указать метод для сопоставления с операцией, задав параметр «method=». В методе WebGetAttribute отсутствует параметр «method=», при этом метод сопоставляет с операцией службы только вызовы GET.
Реализуйте контракт службы, как показано в следующем коде:
Размещение службы
Создайте ServiceHost объект, как показано в следующем коде:
Добавьте ServiceEndpoint с помощью BasicHttpBinding для КОНЕЧНОЙ точки SOAP, как показано в следующем коде:
Добавьте ServiceEndpoint с помощью WebHttpBinding для конечной точки, отличной от SOAP, и добавьте в WebHttpBehavior конечную точку, как показано в следующем коде:
Вызовите Open() в ServiceHost экземпляре, чтобы открыть узел службы, как показано в следующем коде:
Вызов операций службы, сопоставленных с операцией GET, в Internet Explorer
Вызов операций службы в сетевой конечной точке в коде
Создайте канал и вызовите службу, как показано в следующем коде.
Вызов операций службы в конечной точке SOAP
Создайте канал и вызовите службу, как показано в следующем коде.
Закрытие узла службы
Закройте ведущее приложение службы, как показано в следующем коде.
Пример
Ниже приведен полный листинг кода для этого раздела: