Веб сервис wsdl. Описание Web Services на языке WSDL
Страница 2 из 3
Описание с помощью WSDL
SOAP работает очень хорошо, если о Web-службе все известно. Однако это не всегда так. Средством описания интерфейса для доступа к Web-службе является язык WSDL (Web Services Description Language - язык описания Web-служб). Этот стандарт совместно разработан компаниями IBM, Microsoft и webMethods. У каждой из этих трех компаний был собственный подход к разработке стандарта для описания Web-служб: IBM создала NASSL, Microsoft разработала SCL, а компания webMethods придумала WIDL.
Результатом их сотрудничества стала версия 1.1 языка WSDL, По поводу W3C следует отметить, что так же как и с SOAP, консорциум W3C на основе версии 1.1 разработал версию WSDL 1.2, которая теперь является рекомендацией W3C. WSDL-описание Web-службы содержит всю необходимую для использования этой службы информацию, включая доступные методы и их параметры. Эта информация содержится в следующих пяти элементах:
- поддерживаемые протоколы. - сообщения Web-службы (запрос, ответ). Все доступные методы. - URI службы. - используемые типы данных.
Вся эта информация хранится в корневом элементе WSDL-описания
WSDL-описание Web-службы
Да уж... без стаканА не разберёшся, а ведь это один из самых простеньких(!) WSDL файлов. К сожалению, один из недостатков SOAP-расширения для РНР 5 связан с тем, что в отличие от других реализаций SOAP, оно не позволяет создавать WSDL-описания автоматически (во всяком случае, пока что). Наверняка этот недостаток исправят в будущих версиях РНР.
Кстати!
Для автоматического создания WSDL-описания вы можете использовать альтернативные реализации протокола SOAP в РНР:
Поиск в справочнике с помощью UDDI
Теперь, после того как мы знаем, как получать информацию о Web-службе и как ее запрашивать, нужно научиться находить такую службу. Для этой цели существует нечто похожее на "Желтые страницы", а именно - реестры UBR (Universal Business Registries - универсальные бизнес-реестры) - справочники Web-служб.
Существует несколько таких реестров, среди которых реестры компаний IBM, Microsoft, NTT-Com и SAP. Эти реестры синхронизируют свои данные, поэтому можно пользоваться любым из них. Текущей версией стандарта UDDI является версия UDDI 3.0, хотя большинство реализаций используют версию 2. Среди разработчиков этого стандарта такие компании-гиганты, как HP, Intel, Microsoft и Sun.
Для взаимодействия с UBR существует два типа API-интерфейсов: Inquiry API и Publish API . Интерфейс Inquiry API (Запрос) предназначен для запроса служб в реестрах UBR, а интерфейс Publish API (Публикация) позволяет разработчикам регистрировать свои службы . Похоже, что заполнение содержимого реестров спамом - это только вопрос времени:)
Кстати!
Существуют тестовые реестры, предназначенные для тестирования регистрации служб перед их размещением в "настоящих" реестрах.
Так выглядит запрос Web-службы:
В примере выше видно, что UDDI-запрос инкапсулирован в SOAP-сообщение, поэтому выглядит он довольно знакомым. Ответом на запрос является также SOAP-документ, показанный ниже:
Установка
Установить SOAP-расширение для PHP5 довольно легко. В Windows этот модуль находится в подкаталоге ext каталога установки РНР. Для его использования необходимо в файл php.ini добавить следующую строку: extension=php_soap.dll Для работы этому модулю требуется, которая включена в РНР 5 по умолчанию, по крайней мере, в Windows-версии.
Когда-то поставили передо мной задачу начать разработку Web-сервисов и дали мне сорцы простейшего проекта без каких-либо объяснений. Проект, конечно же, не запускался. Что такое Spring и как он работает, я тоже представления не имел. Адекватных статей по разработке Web-сервисов средствами Spring ни русскоязычных, ни англоязычных я тоже не смог найти. Пришлось разбираться во всем самому, оказалось все не так страшно.
И вот недавно я решил посмотреть, какие новые возможности добавились в Spring с тех пор, и обновить старые сервисы, что в результате и сподвигло меня на написание данной статьи.
Данная статья является руководством по разработке простейшего Web-сервиса, использующего SOAP -протокол, средствами Spring-WS.
И так, писать будем простейший сервис, принимающий имя пользователя и отправляющий приветствие и текущее время на сервере.
Что же нам потребуется?
- IDE. Я использую Eclipse .
Подготовка к работе
Создаем новый проект Web-приложения. В Eclipse это: «File => New => Dynamic Web Project».Я назвал проект: HelloService.
Далее копируем библиотеки из Spring, XMLBean, wsdl4j, commons-logging в каталог проекта WEB-INF/lib.
При желании можете добавить их к библиотекам сервера, чтобы не таскать их с каждым приложением.
Создание WSDL-схемы
По сути WSDL-схема предназначена для описания сервиса.Вручную создавать её мы, конечно же, не будем. Схема будет сгенерирована автоматически средствами Spring"а, но об этом позднее.
Определяем входные и выходные данные
Входные данные:- String имя.
- String приветствие;
- Time текущее время.
Создаем описание входных и выходных данных
В каталоге 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-библиотека.
Далее запускаем Ant-build (надеюсь, вы его уже установили).
В Eclipse можно запустить так: ПКМ по файлу build.xml=> Run As => Ant Build.
Если через командную строку:
ant -buildfile build.xml
Ну и ждем завершения построения. После чего, можем проверить каталог проекта WEB-INF\lib на наличие соответствующей библиотеки (helloservice.jar).
Реализация сервиса
Создаем интерфейс и класс сервиса
Интерфейс сервиса: HelloService.java:package org.example; import java.util.Calendar; public interface HelloService { public String getHello(String name) throws Exception; public Calendar getCurrentTime(); }
Реализация сервиса: HelloServiceImpl.java:
package org.example; import java.util.Calendar; import org.springframework.stereotype.Service; @Service public class HelloServiceImpl implements HelloService { public String getHello(String name) throws Exception { return "Hello, " + name + "!"; } public Calendar getCurrentTime() { return Calendar.getInstance(); } }
Данный код, я думаю, не нуждается в комментариях. Единственное, что у людей, не сталкивающихся ранее со Spring"ом, может вызвать вопросы, так это аннотация @ Service. Но об этом же расскажу чуть позже.
Endpoint
Endpoint – класс, который будет отвечать за обработку входящих запросов (своего рода точка входа).Создаем файл HelloServiceEndpoint.java:
package org.example;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ws.server.endpoint.annotation.Endpoint;
import org.springframework.ws.server.endpoint.annotation.PayloadRoot;
import org.example.helloService.ServiceRequestDocument;
import org.example.helloService.ServiceRequestDocument.ServiceRequest;
import org.example.helloService.ServiceResponseDocument;
import org.example.helloService.ServiceResponseDocument.ServiceResponse;
@Endpoint
public class HelloServiceEndpoint{
private static final String namespaceUri = "http://www.example.org/HelloService";
private HelloService helloService;
@Autowired
public void HelloService (HelloService helloService) {
this.helloService = helloService;
}
@PayloadRoot(localPart = "ServiceRequest", namespace = namespaceUri)
public ServiceResponseDocument getService(ServiceRequestDocument request) throws Exception {
ServiceRequestDocument reqDoc = request;
ServiceRequest req = reqDoc.getServiceRequest();
ServiceResponseDocument respDoc = ServiceResponseDocument.Factory.newInstance();
ServiceResponse resp = respDoc.addNewServiceResponse();
String userName = req.getName();
String helloMessage = testNewService.getHello(userName);
Calendar currentTime = testNewService.getCurrentTime();
resp.setHello(helloMessage);
resp.setCurrentTime(currentTime);
return respDoc;
}
}
Что же здесь сделано?
Аннотация @Endpoint
как раз и определяет, что данный класс будет обрабатывать входящие запросы.
namespaceUri
– то же пространство имен, что и указывалось при создании xml-схемы.
Теперь вернемся немного назад и вспомним про аннотацию @ Service . Если не вдаваться в подробности, чтобы не перегружать читателя лишней информацией, то эта аннотацию говорит Spring"у создать соответствующий объект. А аннотация @Autowired служит для инъекции (автоматической подстановки) соответствующего объекта. Конечно же при построении простых приложений в использовании данных аннотаций отсутствует смысл, но я решил все-такие не исключать их в данном примере.
В остальном опять же все должно быть ясно. Обратите внимание, что 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»
В результате получаем ответ от сервера с приветствием и текущим временем.
Если что-то пошло не так, то опять перечитываем данную статью.
Что дальше?
Ну а дальше предстоит написание клиента для данного Web-сервиса. Но это уже материал для другой статьи, которая возможно будет написана позже, если данный материал кого-то заинтересует.В этой статье я расскажу о том, что такое WSDL-файл, зачем он нужен и как с ним работать.
Карта статьи
Что такое WSDL
WSDL — это язык описания веб-сервиса, имеющий структуру XML. Основное назначение WSDL-файла — это интерфейс доступа к функциям сервиса, возвращаемым типам данных; путь к серверу, обрабатывающему запросы и т.д.
Путь к wsdl-файлу обычно имеет вид http://host/services/wsdl/gbdar-v2-2.wsdl
Существует множество инструментов, библиотек, предназначенных для чтения WSDL-файла.
SoapUi
Одним из таких инструментов является soapUi (). Установив дистрибутив, предназначенный для вашей платформы, вы сможете создать новый проект командой File/New SoapUi project. В диалоге создания нового проекта оставляем включенной галочку Create sample requests
Выполнение запросов
В новом проекте будут автоматически созданы шаблоны запросов для сервиса, описание которого содержится в wsdl-файле. Слева в дереве Вы увидите перечень функций, содержащихся в WSDL-файле. Я раскрою функцию Replication. Внутри нее присутствует запрос Request1, дважды щелкнув по которому, мы увидим диалог с шаблоном запроса, вместо параметров по умолчанию будут проставлены знаки вопроса. Чтобы функция корректно выполнилась, необходимо заполнить все параметры, не помеченные тегом Optional, после чего нажать зеленый треугольник в верхнем левом углу диалога.
Если все параметры указаны верно, справа появится ответ сервиса на запрос.
SoapUi предоставляет возможность просмотра параметров WSDL-файла, для этого необходимо дважды щелкнуть по наименованию интерфейса (помечен зеленой иконкой в дереве WSDL-файла, у меня — gdbar-v2-2SOAP). В диалоговом окне вы можете найти:
- Вкладка OverView — описание общих параметров WSDL, список функций и связанных с ними действий сервера
- Вкладка Service Endpoints — путь к серверу и прочие параметры
- WSDL Content — дерево навигации по файлу
- WS-I Compliance — здесь можно создать WS-I отчет по интерфейсу
Генерация документации
SoapUi позволяет нам генерировать документацию по функциям WSDL. Для этого щелкните правой кнопкой по интерфейсу и вызовите команду Generate Documentation. В результате получим подробный мануал в html-формате.
На этом все, подписывайтесь на новые записи, оставляйте комментарии, вносите предложения по улучшению статьи.
WSDL (Web Services Description Language ) версии 1.1 был опубликован 15 марта 2001 года. WSDL - это формат, базирующийся на XML и использующийся для описания сетевых cервисов, при помощи сообщений, содержащих информация о том как осуществлять доступ к конкретному веб-сервису. WSDL расширяем, что позволяет описывать услуги (сервисы) и их сообщения независимо от того, какие форматы сообщений или сетевые протоколы используются для транспорта, однако, чаще всего используется WSDL 1.1 вместе с SOAP 1.1, HTTP GET/POST и MIME. Поскольку WSDL был разработан совместно с SOAP, в его разработке участвовали все те же фирмы Microsoft, Ariba и IBM. Если рассматривать документ WSDL интуитивно, то можно сказать, что он позволяет ответить на 4 вопроса :
1) что вы делаете? Ответ на этот вопрос дается в форме пригодной как для восприятия человеком так и форме воспринимаемой машиной. Ответ для чел-ка в тегах: <name />, <documentation />, для машины - <message />, <pointType >
2) на каком языке вы разговариваете? (какие типы вы используете?)Ответ в теге: <types />
3) как я буду с вами общаться? (как клиент будет обращаться к веб-службе?):HTTP или SMTP. Ответ находится в <binding />
4) где мне вас найти? (где я могу найти эту веб-службу или какой у нее URL?). Ответ находится: <service />
Структура:
Каждый документ WSDL можно разбить на три логические части:
1. определение типов данных - определение вида отправляемых и получаемых сервисом XML сообщений
2. абстрактные операции - список операций, которые могут быть выполнены с сообщениями
3. связывание сервисов - способ, которым сообщение будет доставлено
Документы WSDL можно создавать вручную, однако строгая формализация языка WSDL позволяет автоматизировать процесс написания WSDL -документов. Многие интсрументальные средства создания Web-служб содержат утилиты, которые автоматичеки создают WSDL -файлы, описывающие готовые Web-службы. Например средство создания Web-служб Apache Axis содержит в своем составе класс Java2WSDL , создающий WSDL -файл по классу или интерфейсу Java, описывающему Web-службу. Пакет IBM WSTK, в состав которого входит Axis , содержит утилиту java2wsdl , создающую и запускающую объект из этого класса. Она работает из командной строки.
Элементы WSDL-документа
Опишем наиболее часто употребляемые теги WSDL:
Тег
1)target Name space – это пространство имен нашей веб-службы
2)xmlns – стандартное пространство имен документа WSDL
3)xmlns: SOAP_ENC – пространство имен используемое для описания кодировки SOAP
4)xmlns: impl и intf – пространство имен реализации и определения нашей веб-службы
· Документ для определения веб-службы
· Документ для реализации веб-службы
Для простоты, как правило, используют 1 файл, который содержит всю информацию
Элемент
Для описания вызова RPC необходимо создать входной сообщение и выходное сообщение.
В рамках этого элемента можно указать параметры метода с помощью элемента
Элемент
Операции могут иметь входные сообщения, а также сообщения об ошибках.
Элемент
Элемент
Элемент import . Очень часто элемент service выделяется в свой wsdl документ из соображений практичности.
Для того, чтобы позволить собрать из нескольких wsdl документов один используется элемент import. Он позволяет включать один wsdl документ в другой.
Элемент types позволяет указать типы передаваемых данных если они не являются стандартными.
WSDL поддерживает 4 режима операций:
· операции типа one-way или односторонние операции. Сообщение посылается конечной точке службы. В этом случае операция описывается только одним входным сообщением.
· Request-Response – режим запрос-ответ. Этот режим операции является наиболее общим. В этом режиме описание операции содержит входное и выходное сообщение и необязательное сообщение об ошибке.
· Операция типа требование-ответ. В этом режиме конечной точкой является клиент другой конечной точки. Формат операции похож на режим запрос-ответ, но выходные данные перечисляются перед входными данными.
· Операция уведомление. Этот режим – еще одна версия примитива односторонней передачи, в которой конечная точка посылает сообщение а не получает его. Операция содержит только выходное сообщение.
Заголовок топика – это действительно вопрос, т.к. я сам не знаю, что это и впервые попробую поработать с этим в рамках настоящей статьи. Единственное, что могу гарантировать, что код, представленный ниже, будет работать, однако мои фразы будут лишь предположениями и догадками о том, как я сам все это понимаю. Итак, поехали…
Введение
Начать надо с того, для чего создавалась концепция веб-сервисов. К моменту появления этого понятия в мире уже существовали технологии, позволяющие приложениям взаимодействовать на расстоянии, где одна программа могла вызвать какой-нибудь метод в другой программе, которая при этом могла быть запущена на компьютере, расположенном в другом городе или даже стране. Все этого сокращенно называется RPC (Remote Procedure Calling – удаленный вызов процедур). В качестве примеров можно привести технологии CORBA, а для Java – RMI (Remote Method Invoking – удаленный вызов методов). И все вроде в них хорошо, особенно в CORBA, т.к. с ней можно работать на любом языке программирования, но чего-то все же не хватало. Полагаю, что минусом CORBA является то, что она работает через какие-то свои сетевые протоколы вместо простого HTTP, который пролезет через любой firewall. Идея веб-сервиса заключалась в создании такого RPC, который будет засовываться в HTTP пакеты. Так началась разработка стандарта. Какие у этого стандарта базовые понятия:- SOAP . Прежде чем вызвать удаленную процедуру, нужно этот вызов описать в XML файле формата SOAP. SOAP – это просто одна из многочисленных XML разметок, которая используется в веб-сервисах. Все, что мы хотим куда-то отправить через HTTP, сначала превращается в XML описание SOAP, потом засовывается в HTTP пакет и посылается на другой компьютер в сети по TCP/IP.
- WSDL . Есть веб-сервис, т.е. программа, методы которой можно удаленно вызывать. Но стандарт требует, чтобы к этой программе прилагалось описание, в котором сказано, что «да, вы не ошиблись – это действительно веб-сервис и можно у него вызвать такие-то такие-то методы». Такое описание представляется еще одним файлом XML, который имеет другой формат, а именно WSDL. Т.е. WSDL – это просто XML файл описания веб-сервиса и больше ничего.
Общий подход
В веб-сервисах всегда есть клиент и сервер. Сервер – это и есть наш веб-сервис и иногда его называют endpoint (типа как, конечная точка, куда доходят SOAP сообщения от клиента). Нам нужно сделать следующее:- Описать интерфейс нашего веб-сервиса
- Реализовать этот интерфейс
- Запустить наш веб-сервис
- Написать клиента и удаленно вызвать нужный метод веб-сервиса