Это пример главы, взятой из книги Advanced JAX-WS Web Services, отредактированной Алессио Солдано .
Восходящий подход к созданию конечной точки веб-службы был представлен в первой главе. Это позволяет очень быстро представить существующие компоненты в качестве конечных точек веб-службы: в большинстве случаев превращение классов в конечные точки заключается в простом добавлении нескольких аннотаций в коде.
Однако при разработке сервиса с уже определенным контрактом гораздо проще (и эффективнее) использовать нисходящий подход, поскольку инструмент wsdl-to-java может генерировать аннотированный код, соответствующий WSDL. Это предпочтительное решение в нескольких сценариях, таких как следующие:
- Создание службы, соответствующей XML-схеме и WSDL, которые были разработаны вручную;
- Предоставление сервиса, который соответствует контракту, указанному третьей стороной (например, поставщиком, который вызывает сервис, используя уже определенный набор сообщений);
- Замена реализации существующей веб-службы при сохранении совместимости со старыми клиентами (контракт не должен изменяться).
В следующих разделах приведен пример разработки конечной точки нисходящей веб-службы, а также некоторые подробности об ограничениях, о которых должен знать разработчик при кодировании, независимо от выбранного подхода.
Создание веб-службы с использованием нисходящего подхода
Чтобы настроить полный проект, который включает конечную точку веб-службы и клиент JAX-WS, мы будем использовать два проекта Maven. Первым будет стандартный проект webapp-javaee7, который будет содержать конечную точку веб-службы. Второй будет просто быстрый проект Maven, который выполнит тестовый сценарий для веб-службы.
Давайте начнем создавать серверный проект как обычно с:
1
|
mvn -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=webapp-javaee7 -DarchetypeVersion= 0.4 -SNAPSHOT -DarchetypeRepository=https: //nexus.codehaus.org/content/repositories/snapshots -DgroupId=com.itbuzzpress.chapter2.wsdemo -DartifactId=ws-demo2 -Dversion=1.0 -Dpackage=com.itbuzzpress.chapter2.wsdemo -Darchetype.interactive=false --batch-mode --update-snapshots archetype:generate |
Следующим шагом будет создание интерфейса веб-службы и заглушки из контракта WSDL. Этапы аналогичны тем, которые используются для создания клиента для одного контракта. Разница лишь в том, что скрипт wsconsume выведет сгенерированные исходные файлы в наш проект Maven:
1
|
$ wsconsume.bat -k CustomerService.wsdl -o ws-demo-wsdl\src\main\java |
В дополнение к сгенерированным классам, которые мы обсуждали в начале главы, нам необходимо предоставить реализацию конечной точки службы, которая содержит функциональные возможности веб-службы:
1
2
3
4
5
6
7
8
9
|
@WebService (endpointInterface= "org.jboss.test.ws.jaxws.samples.webresult.Customer" ) public class CustomerImpl implements Customer { public CustomerRecord locateCustomer(String firstName, String lastName, USAddress address) { CustomerRecord cr = new CustomerRecord(); cr.setFirstName(firstName); cr.setLastName(lastName); return cr; } } |
Класс реализации конечной точки реализует интерфейс конечной точки и ссылается на него через аннотацию @WebService . Наш класс WebService ничего не делает, просто создайте объект CustomerRecord, используя параметры, полученные в качестве входных данных. В реальном примере вы могли бы собрать CustomerRecord, например, с помощью уровня сохраняемости.
Как только класс реализации будет включен в проект, проект необходимо упаковать и развернуть в целевом контейнере, который предоставит конечную точку службы с тем же контрактом, который использовался инструментом.
Можно также сослаться на локальный файл WSDL в атрибуте @WebService wsdlLocation в интерфейсе службы и включить этот файл в развертывание. Это сделало бы точный предоставленный документ опубликованным.
Если вы развертываете веб-службу на сервере приложений WildFly, то с помощью инструмента управления, такого как консоль администратора, вы можете проверить, доступна ли конечная точка. Выберите вкладку «Верхняя среда выполнения» и щелкните ссылку «Веб-службы», расположенную в левой подсистеме слева:
Требования к конечной точке JAX-WS
Независимо от подхода, выбранного для разработки конечной точки JAX-WS, фактическая реализация должна удовлетворять некоторым требованиям:
- Реализующий класс должен быть аннотирован либо аннотацией j avax.jws.WebService, либо javax.jws.WebServiceProvider .
- Реализующий класс может явно ссылаться на интерфейс конечной точки службы через элемент endpointInterface аннотации @WebService, но это не требуется. Если endpointInterface не указан в @WebService , интерфейс конечной точки службы неявно определяется для реализующего класса.
- Бизнес-методы реализующего класса должны быть открытыми и не должны объявляться как статические или окончательные.
- Аннотация javax.jws.WebMethod должна использоваться в бизнес-методах, которые будут доступны клиентам веб-служб; если ни один метод не аннотирован @WebMethod , все бизнес-методы будут доступны.
- Бизнес-методы, предоставляемые клиентам веб-служб, должны иметь JAXB-совместимые параметры и типы возвращаемых данных.
- Реализующий класс не должен быть объявлен как final и не должен быть абстрактным.
- Реализующий класс должен иметь открытый конструктор по умолчанию и не должен определять метод finalize.
- Реализующий класс может использовать аннотации javax.annotation.PostConstruct или javax.annotation.PreDestroy для своих методов для обратных вызовов событий жизненного цикла.
Требования для сборки и запуска клиента JAX-WS
Клиент JAX-WS может быть частью любого проекта Java и не обязательно должен быть частью архива JAR / WAR, развернутого в контейнере JavaEE. Например, клиент может просто содержаться в быстром запуске проекта Maven следующим образом:
1
|
mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DgroupId=com.itbuzzpress.chapter2.wsdemo -DartifactId=client-demo-wsdl -Dversion= 1.0 -Dpackage=com.itbuzzpress.chapter2.wsdemo -Dversion= 1.0 -Darchetype.interactive= false --batch-mode |
Поскольку ваш клиент должен ссылаться на интерфейс конечной точки и заглушки, вы должны предоставить им либо копирование их из проекта сервера, либо их генерацию заново с помощью wsconsume:
1
|
$ wsconsume.bat -k CustomerService.wsdl -o client-demo-wsdl\src\main\java |
Теперь включите минимальное приложение Client Test, которое является частью тестового примера JUnit:
01
02
03
04
05
06
07
08
09
10
|
public class AppTest extends TestCase { public void testApp() { CustomerService service = new CustomerService(); Customer port = service.getCustomerPort(); CustomerRecord record = port.locateCustomer( "John" , "Li" , new USAddress()); System.out.println( "Customer record is " +record); assertNotNull(record); } } |
Компиляция и запуск теста
Для успешного запуска клиентского приложения WS необходимо правильно настроить загрузчик классов, чтобы включить в него нужные библиотеки реализации JAX-WS (и необходимые переходные зависимости, если таковые имеются). В зависимости от среды, в которой предполагается запускать клиент, это может означать добавление некоторых jar-файлов в путь к классам или добавление некоторых зависимостей артефактов в дерево зависимостей Maven, правильную настройку IDE и т. Д.
Поскольку Maven используется для создания приложения, содержащего клиент, вы можете настроить ваш pom.xml следующим образом, чтобы он включал зависимость от JBossWS:
1
2
3
4
5
6
|
< dependency > < groupId >org.jboss.ws.cxf</ groupId > < artifactId >jbossws-cxf-client</ artifactId > < version >4.2.3.Final</ version > < scope >provided</ scope > </ dependency > |
Теперь вы можете выполнить тестовый сценарий, который вызовет API JAX-WS для обслуживания вызова клиента с использованием JBossWS.
1
|
mvn clean package test |
Сосредоточьтесь на реализации JAX-WS, используемой клиентом
Реализация JAX-WS, которая будет использоваться для запуска клиента JAX-WS, выбирается во время выполнения путем поиска ресурсов META-INF / services / javax.xml.ws.spi.Provider через загрузчик классов приложения. Каждая реализация JAX-WS имеет библиотеку (jar), включающую этот файл ресурсов, который внутренне ссылается на соответствующий класс, реализующий поставщик SPI JAX-WS.
На сервере приложений WildFly 8.0.0.Final реализация JAX-WS содержится в META-INF / services / javax.xml.ws.spi.Provider файла jbossws-cxf-factories-4.2.3.Final :
1
|
org.jboss.wsf.stack.cxf.client.ProviderImpl |
Поэтому чрезвычайно важно контролировать, какие артефакты или библиотеки JAR включены в путь к классам, из которого создается загрузчик классов приложения. Если найдено несколько реализаций, порядок имеет значение, поэтому будет использоваться первая реализация в classpath.
Самый безопасный способ избежать любой проблемы с classpath (и, следовательно, загрузить другую реализацию JAX-WS) — это установить системное свойство java.endorsed.dirs для включения jbossws-cxf-factories.jar; если вы этого не сделаете, убедитесь, что вы не включаете перед вашим classpath другие ресурсы META-INF / services / javax.xml.ws.spi.Provider, которые будут запускать другую реализацию JAX-WS.
Наконец, если клиент JAX-WS предназначен для работы на WildFly как часть приложения JavaEE, для обслуживания клиента будет автоматически выбрана реализация JBossWS JAX-WS.
Этот отрывок взят из книги « Расширенные веб-службы JAX-WS », в которой вы познакомитесь с концепциями архитектуры веб-служб на основе SOAP и получите практические советы по созданию и развертыванию веб-служб на предприятии.
Начиная с основ и лучших практик по настройке среды разработки, эта книга ясно и кратко излагает внутренние детали JAX-WS.
Вы также узнаете об основных наборах инструментов, доступных для создания, компиляции и тестирования веб-служб SOAP, и о том, как решать распространенные проблемы, такие как отладка данных и защита их содержимого.
Что вы узнаете из этой книги:
- Сделайте первые шаги с помощью веб-сервисов SOAP. Установка инструментов, необходимых для разработки и тестирования приложений.
- Разработка веб-сервисов с использованием нисходящего и восходящего подходов.
- Использование архетипов Maven для ускорения создания веб-сервисов.
- Знакомство с деталями типов JAX-WS: отображение Java на XML и XML на Java
- Разработка SOAP Web-сервисов на WildFly 8 и Tomcat. Запуск собственного Apache CXF на WildFly.
- Защита веб-сервисов. Применение политик аутентификации к вашим сервисам. Шифрование сообщения.