Технология создания веб-сервисов на базе стандарта JAX-WS & JAXB Малышкин Фёдор ( [email_address] ) 9 ноября 2007

Введение Веб-сервис – это метод коммуникации с использованием огромного количества протоколов и данными в виде структурированного XML. Название пошло от основного протокола передачи, использовавшегося на заре создания технологии – HTTP. Сейчас в качестве протоколов передачи кроме HTTP, могут использоваться JMS ( протокол передачи сообщений Java), SMTP , TCP… Даже данные могут передаваться не в виде XML. Так что понятие «веб-сервис» имеет очень расплывчатое значение на сегодняшний день и включает в себя огромное количество понятий. Но разговор будет идти о стандарте описания веб-сервиса – о WSDL …

Веб-сервис – это метод коммуникации с использованием огромного количества протоколов и данными в виде структурированного XML.

Название пошло от основного протокола передачи, использовавшегося на заре создания технологии – HTTP.

Сейчас в качестве протоколов передачи кроме HTTP, могут использоваться JMS ( протокол передачи сообщений Java), SMTP , TCP…

Даже данные могут передаваться не в виде XML.

Так что понятие «веб-сервис» имеет очень расплывчатое значение на сегодняшний день и включает в себя огромное количество понятий.

Но разговор будет идти о стандарте описания веб-сервиса – о WSDL …

WSDL WSDL – Web Service Description Language. WSDL является XML словарём, который позволяет описать веб-сервис в языке независимом от платформы и от реализации. Данная лекция описывает стандарт WSDL 1.1 , который доступен по адресу [TODO].

WSDL – Web Service Description Language.

WSDL является XML словарём, который позволяет описать веб-сервис в языке независимом от платформы и от реализации.

Данная лекция описывает стандарт WSDL 1.1 , который доступен по адресу [TODO].

Логическая структура WSDL <wsdl:definitions ....> <!– Импорт определений из других источников --> <wsdl:import ..../> <!– Определение типов используемых только в этом WSDL --> <wsdl:types ..../> <!– Определение сообщений используемых веб-сервисом --> <wsdl:message .../> <!– Определение интерфейсов и операций --> <wsdl:portType .../> <!– Привязка интерфейсов и операций к конкретному протоколу --> <wsdl:binding ..../> <!– Определение сервиса как коллекции интерфейсов и определение адреса сервиса --> <wsdl:service ..../> </wsdl:definitions>

<wsdl:definitions ....>

<!– Импорт определений из других источников -->

<wsdl:import ..../>

<!– Определение типов используемых только в этом WSDL -->

<wsdl:types ..../>

<!– Определение сообщений используемых веб-сервисом -->

<wsdl:message .../>

<!– Определение интерфейсов и операций -->

<wsdl:portType .../>

<!– Привязка интерфейсов и операций к конкретному протоколу -->

<wsdl:binding ..../>

<!– Определение сервиса как коллекции интерфейсов и определение адреса сервиса -->

<wsdl:service ..../>

</wsdl:definitions>

Элементы WSDL import – позволяет частям веб-сервиса быть распределёнными между несколькими файлами и быть скомпонованными в различной конфигурации в зависимости от потребностей авторов веб-сервиса. Использование данной техники распространено в крупных проектах, многие веб-сервисы имеют общие типы данных и отличаются только в деталях реализации или привязки к протоколу.

import – позволяет частям веб-сервиса быть распределёнными между несколькими файлами и быть скомпонованными в различной конфигурации в зависимости от потребностей авторов веб-сервиса.

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

Элементы WSDL types – определяет типы используемые веб-сервисами. <types> <xs:complexType name=&quot;requestHeaderType&quot;> <xs:all> <xs:element name=&quot;sessionId&quot; type=&quot;xs:string&quot;> </xs:all> </xs:complexType> <xs:complexType name=&quot;responseHeaderType&quot;> <xs:all> <xs:element name=&quot;sessionId&quot; type=&quot;xs:string&quot;> </xs:element> </xs:all> </xs:complexType> … ..

types – определяет типы используемые веб-сервисами.

<types>

<xs:complexType name=&quot;requestHeaderType&quot;>

<xs:all>

<xs:element name=&quot;sessionId&quot; type=&quot;xs:string&quot;>

</xs:all>

</xs:complexType>

<xs:complexType name=&quot;responseHeaderType&quot;>

<xs:all>

<xs:element name=&quot;sessionId&quot; type=&quot;xs:string&quot;>

</xs:element>

</xs:all>

</xs:complexType>

… ..

Элементы WSDL types – определяет типы используемые веб-сервисами.

types – определяет типы используемые веб-сервисами.

Элементы WSDL message - описывает данные, которые путешествуют между веб-сервисом и клиентом в терминах, описанных в элементе Types . <message name=&quot;startSessionRequest&quot;> <part name=&quot;request&quot; element=&quot;tns:startSessionRequest&quot;/> </message> <message name=&quot;startSessionResponse&quot;> <part name=&quot;response&quot; element=&quot;tns:startSessionResponse&quot;/> </message> <message name=&quot;getRegionImageRequest&quot;> <part name=&quot;request&quot; element=&quot;tns:getRegionImageRequest&quot;/> </message>…

message - описывает данные, которые путешествуют между веб-сервисом и клиентом в терминах, описанных в элементе Types .

<message name=&quot;startSessionRequest&quot;>

<part name=&quot;request&quot; element=&quot;tns:startSessionRequest&quot;/>

</message>

<message name=&quot;startSessionResponse&quot;>

<part name=&quot;response&quot; element=&quot;tns:startSessionResponse&quot;/>

</message>

<message name=&quot;getRegionImageRequest&quot;>

<part name=&quot;request&quot; element=&quot;tns:getRegionImageRequest&quot;/>

</message>…

Элементы WSDL portType – определяет опреации, которые веб-сервис обеспечивает. <portType name=&quot;GPSMonitorScreenProjectionEndpoint&quot;> <operation name=&quot;startSession&quot;> <input message=&quot;tns:startSessionRequest&quot;/> <output message=&quot;tns:startSessionResponse&quot;/> </operation> <operation name=&quot;addRoute&quot;> <input message=&quot;tns:addRouteRequest&quot;/> <output message=&quot;tns:addRouteResponse&quot;/> <fault name=&quot;fault&quot; message=&quot;tns:addRouteFault&quot;/> </operation> …

portType – определяет опреации, которые веб-сервис обеспечивает.

<portType name=&quot;GPSMonitorScreenProjectionEndpoint&quot;>

<operation name=&quot;startSession&quot;>

<input message=&quot;tns:startSessionRequest&quot;/>

<output message=&quot;tns:startSessionResponse&quot;/>

</operation>

<operation name=&quot;addRoute&quot;>

<input message=&quot;tns:addRouteRequest&quot;/>

<output message=&quot;tns:addRouteResponse&quot;/>

<fault name=&quot;fault&quot; message=&quot;tns:addRouteFault&quot;/>

</operation>

…

Элементы WSDL binding – определяет, как операции и сообщения, описанные в message и portType , привязываются к конкретному протоколу. <binding name=&quot;GPSMonitorScreenProjectionEndpointBinding&quot; type=&quot;tns:GPSMonitorScreenProjectionEndpoint&quot;> <soap:binding style=&quot;document&quot; transport=&quot;http://schemas.xmlsoap.org/soap/http&quot;/> <operation name=&quot;startSession&quot;> <soap:operation/> <input><soap:body use=&quot;literal&quot;/></input> <output><soap:body use=&quot;literal&quot;/></output> </operation> <operation name=&quot;addRoute&quot;><soap:operation/> …

binding – определяет, как операции и сообщения, описанные в message и portType , привязываются к конкретному протоколу.

<binding name=&quot;GPSMonitorScreenProjectionEndpointBinding&quot; type=&quot;tns:GPSMonitorScreenProjectionEndpoint&quot;>

<soap:binding style=&quot;document&quot; transport=&quot;http://schemas.xmlsoap.org/soap/http&quot;/>

<operation name=&quot;startSession&quot;>

<soap:operation/>

<input><soap:body use=&quot;literal&quot;/></input>

<output><soap:body use=&quot;literal&quot;/></output>

</operation>

<operation name=&quot;addRoute&quot;><soap:operation/>

…

Элементы WSDL service – группирует ранее описанные порты и этим определяет сервис. <service name=&quot;GPSMonitorScreenProjectionService&quot;> <port name=&quot;GPSMonitorScreenProjectionEndpointPort&quot; binding=&quot;tns:GPSMonitorScreenProjectionEndpointBinding&quot;> <soap:address location=&quot;http://mg-sv01/&quot;/> </port> </service>

service – группирует ранее описанные порты и этим определяет сервис.

<service name=&quot;GPSMonitorScreenProjectionService&quot;>

<port name=&quot;GPSMonitorScreenProjectionEndpointPort&quot; binding=&quot;tns:GPSMonitorScreenProjectionEndpointBinding&quot;>

<soap:address location=&quot;http://mg-sv01/&quot;/>

</port>

</service>

Разработка «обычных» веб-сервисов Класс Java: @WebService public class UsualWS { @WebMethod public String method01(String data) { // парсинг XML // работа над данными String result = результат работы return result ; } }

Класс Java:

@WebService

public class UsualWS {

@WebMethod

public String method01(String data) {

// парсинг XML

// работа над данными

String result = результат работы

return result ;

}

}

Разработка «обычных» веб-сервисов Генерация с помощью WSGEN необходимых артефактов и WSDL Развёртывание И вызов через клиента или другое средство. Например через XMLSpy:

Генерация с помощью WSGEN необходимых артефактов и WSDL

Развёртывание

И вызов через клиента или другое средство. Например через XMLSpy:

Потери «обычных» веб-сервисов «Обычные» веб-сервисами отличаются от «нормальных» только одним – отсутствием информации о структуре передаваемого XML. Информация о том, что передаётся и в каком виде, должна быть у пользователя веб-сервиса ЗАРАНЕЕ. Использовать веб-сервис без этого не предоставляется возможным.

«Обычные» веб-сервисами отличаются от «нормальных» только одним – отсутствием информации о структуре передаваемого XML.

Информация о том, что передаётся и в каком виде, должна быть у пользователя веб-сервиса ЗАРАНЕЕ. Использовать веб-сервис без этого не предоставляется возможным.

Пример «стандартного» веб-сервиса Загружаем WSDL «нормального» веб-сервиса в XMLSpy и пробуем вызвать.

Загружаем WSDL «нормального» веб-сервиса в XMLSpy и пробуем вызвать.

Преимущества «стандартных» веб-сервисов Доступ к информации о структуре XML на стадии анализа веб-сервиса. Чёткое описание веб-сервиса на уровне интерфейсов взаимодействия. Возможность генерации клиента другим программистом независимо от автора. Совместимость клиента и сервиса (изменении сервиса в рамках допустимого). Возможность генерации специальных класса для указанных типов, облегчающих работу с XML . Устранение необходимости работы экранирования строк, на наличие служебных символов.

Доступ к информации о структуре XML на стадии анализа веб-сервиса.

Чёткое описание веб-сервиса на уровне интерфейсов взаимодействия.

Возможность генерации клиента другим программистом независимо от автора.

Совместимость клиента и сервиса (изменении сервиса в рамках допустимого).

Возможность генерации специальных класса для указанных типов, облегчающих работу с XML .

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

Пример сгенерированного клиента для «стандартного» веб-сервиса @WebMethod @WebResult(name = &quot;addRouteResponse&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;response&quot;) public AddRouteResponseType addRoute(@WebParam(name = &quot;addRouteRequest&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;request&quot;) AddRouteRequestType request) throws AddRouteFault; @WebMethod @WebResult(name = &quot;getScaleResponse&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;response&quot;) public ScaleResponseType getScale(@WebParam ( name = &quot;getScaleRequest&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;request&quot;) GetScaleRequest request) throws GetScaleFault;

@WebMethod

@WebResult(name = &quot;addRouteResponse&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;response&quot;)

public AddRouteResponseType addRoute(@WebParam(name = &quot;addRouteRequest&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;request&quot;)

AddRouteRequestType request)

throws AddRouteFault;

@WebMethod

@WebResult(name = &quot;getScaleResponse&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;response&quot;)

public ScaleResponseType getScale(@WebParam ( name = &quot;getScaleRequest&quot;, targetNamespace = &quot;http://gpsmonitor.net.magnetosoft.ru/&quot;, partName = &quot;request&quot;)

GetScaleRequest request)

throws GetScaleFault;

Пример сгенерированного клиента для «стандартного» веб-сервиса Каждый метод имеет в качестве параметров и возвращаемого результат сгенерированные классы, обрамлённые JAXB аннотациями. При вызове метода классы с наполненными данными преобразуются в XML , а результат из XML разбирается в те же сгенерированные классы. Как результат - необходимость работы с XML , переносящимся между веб-сервисами, отпадает полностью.

Каждый метод имеет в качестве параметров и возвращаемого результат сгенерированные классы, обрамлённые JAXB аннотациями.

При вызове метода классы с наполненными данными преобразуются в XML , а результат из XML разбирается в те же сгенерированные классы.

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

Создание « стандартного » веб-сервиса. Вариант 1. Создание WSDL Генерация артефактов с помощью WSIMPORT Создание реализации сгенерированного интерфейса сервиса P.S.: Данный вариант детально не рассматривается, так как требует детального знания языка описания XML – « XML Schema » . Именно на его основе сделаны модули « Search », « Catalogue » платформы MAGNET .

Создание WSDL

Генерация артефактов с помощью WSIMPORT

Создание реализации сгенерированного интерфейса сервиса

P.S.: Данный вариант детально не рассматривается, так как требует детального знания языка описания XML – « XML Schema » . Именно на его основе сделаны модули « Search », « Catalogue » платформы MAGNET .

Создание « стандартного » веб-сервиса. Вариант 2. Создание классов носителей-данных для обмена. Классы носители-данных для обмена являются обычными JavaBean’ ами, с аннотациями JAXB , которые определяют в какой XML они превратятся. package edu.sefer.home.ws; import java.math.BigDecimal; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class XmlResult { @XmlElement int result; @XmlElement BigDecimal resultBD; }

Создание классов носителей-данных для обмена. Классы носители-данных для обмена являются обычными JavaBean’ ами, с аннотациями JAXB , которые определяют в какой XML они превратятся.

package edu.sefer.home.ws;

import java.math.BigDecimal;

import javax.xml.bind.annotation.XmlElement;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement

public class XmlResult {

@XmlElement

int result;

@XmlElement

BigDecimal resultBD;

}

Создание « стандартного » веб-сервиса. Вариант 2. package edu.sefer.home.ws; import java.util.Date; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class XmlData { @XmlElement String inputString; @XmlElement Date inputDate; @XmlElement int inputInt; }

package edu.sefer.home.ws;

import java.util.Date;

import javax.xml.bind.annotation.XmlElement;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement

public class XmlData {

@XmlElement

String inputString;

@XmlElement

Date inputDate;

@XmlElement

int inputInt;

}

Создание « стандартного » веб-сервиса. Вариант 2. Создания класса веб-сервиса, подобно обычному подходу, но с входящими и выходящими параметрами в виде классов носителей-данных. package edu.sefer.home.ws; import javax.jws.WebMethod; import javax.jws.WebService; @WebService public class UsualWS { @WebMethod public XmlResult method01(XmlData data) { return null; } }

Создания класса веб-сервиса, подобно обычному подходу, но с входящими и выходящими параметрами в виде классов носителей-данных.

package edu.sefer.home.ws;

import javax.jws.WebMethod;

import javax.jws.WebService;

@WebService

public class UsualWS {

@WebMethod

public XmlResult method01(XmlData data) {

return null;

}

}

Создание « стандартного » веб-сервиса. Вариант 2. Генерация артефактов с использованием WSGEN , подобно обычному подходу. <wsgen verbose=&quot;false&quot; debug=&quot;true&quot; keep=&quot;true&quot; destdir=&quot;${project.build.outputDirectory}&quot; resourcedestdir=&quot;${basedir}/target/wsdl&quot; sourcedestdir=&quot;${project.build.sourceDirectory}&quot; sei=&quot;edu.sefer.home.ws.UsualWS&quot; genwsdl=&quot;true&quot;> <classpath> <path refid=&quot;jwdp.classpath&quot;/> <pathelement location=&quot;${project.build.directory}/classes&quot;/> </classpath> </wsgen>

Генерация артефактов с использованием WSGEN , подобно обычному подходу.

<wsgen verbose=&quot;false&quot; debug=&quot;true&quot; keep=&quot;true&quot; destdir=&quot;${project.build.outputDirectory}&quot; resourcedestdir=&quot;${basedir}/target/wsdl&quot; sourcedestdir=&quot;${project.build.sourceDirectory}&quot; sei=&quot;edu.sefer.home.ws.UsualWS&quot; genwsdl=&quot;true&quot;>

<classpath>

<path refid=&quot;jwdp.classpath&quot;/>

<pathelement location=&quot;${project.build.directory}/classes&quot;/>

</classpath>

</wsgen>

Создание « стандартного » веб-сервиса. Вариант 2. Развёртывание и вызов…

Развёртывание и вызов…

Создание « стандартного » веб-сервиса. Вариант 3. Генерация или создание WSDL схемы вручную. Использование интерфейса « javax.xml.ws.Provider » на серверной стороне Использование интерфейса « javax.xml.ws.Dispatch » на клиентской стороне Использование типа « xsd:anyType » для описания ЛЮБОГО XML, если его структура не зафиксирована. P.S.: Данный вариант детально не рассматривается, так как требует детального знания языка описания XML – « XML Schema » и деталей работы соответствующих интерфейсов. Но именно на его основе сделан модуль « EntityManager » платформы MAGNET .

Генерация или создание WSDL схемы вручную.

Использование интерфейса « javax.xml.ws.Provider » на серверной стороне

Использование интерфейса « javax.xml.ws.Dispatch » на клиентской стороне

Использование типа « xsd:anyType » для описания ЛЮБОГО XML, если его структура не зафиксирована.

P.S.: Данный вариант детально не рассматривается, так как требует детального знания языка описания XML – « XML Schema » и деталей работы соответствующих интерфейсов. Но именно на его основе сделан модуль « EntityManager » платформы MAGNET .

Выводы Варианты 1 и 2 наиболее удобны, если интерфейсы взаимодействия уже оговорены и устоялись. Вариант же 3 позволяет передавать динамически компонуемый XML максимально быстро и использовать его максимально эффективно и гибко. Хотя надо так же заметить, что при использовании некоторых подходов, передавать динамический XML можно и в вариантах 1 и 2. Но надо заметить, что дополнительная нагрузка (на обработку сообщений на уровне самой библиотеки) при этом возрастает многократно.

Варианты 1 и 2 наиболее удобны, если интерфейсы взаимодействия уже оговорены и устоялись.

Вариант же 3 позволяет передавать динамически компонуемый XML максимально быстро и использовать его максимально эффективно и гибко.

Хотя надо так же заметить, что при использовании некоторых подходов, передавать динамический XML можно и в вариантах 1 и 2. Но надо заметить, что дополнительная нагрузка (на обработку сообщений на уровне самой библиотеки) при этом возрастает многократно.

Вопросы? ?

?