Главная » Spring » Создание примеров XML-сообщений Spring

0

Говоря простым языком, наша служба будет принимать комбина- цию из пяти карт и возвращать ее оценку при игре в покер (напри- мер, фул-хаус, флеш и т. д.). Сообщение, передаваемое веб-службе, можно представить так:

<EvaluateHandRequest

xmlns="http://www.springinaction.com/poker/schemas">

<card>

<suit>HEARTS</suit>

<face>TEN</face>

</card>

<card>

<suit>SPADES</suit>

<face>KING</face>

</card>

<card>

<suit>HEARTS</suit>

<face>KING</face>

</card>

<card>

<suit>DIAMONDS</suit>

<face>TEN</face>

</card>

<card>

<suit>CLUBS</suit>

<face>TEN</face>

</card>

</EvaluateHandRequest>

Выглядит достаточно просто, не находите? Сообщение содер- жит пять элементов <card>, в каждом из которых присутствуют элементы <suit> и <face>. Сообщение достаточно полно описывает комбинацию карт. Все элементы <card> находятся внутри элемента

<EvaluateHandRequest>, который определяет тип сообщения, отправляе- мого службе.

Сообщение, возвращаемое в ответ на это сообщение, выглядит еще проще:

<EvaluateHandResponse

xmlns="http://www.springinaction.com/poker/schemas">

<handName>Full    House</handName>

</EvaluateHandResponse>

Элемент <EvaluateHandResponse>, определяющий тип сообщения, со- держит единственный элемент <handName>, хранящий значение ком- бинации карт.

Эти примеры сообщений будут служить основой определения нашей службы. Кто-то может не поверить в это, но, определив при- меры сообщений, мы преодолели самый сложный этап на пути опре- деления службы. Без шуток.

Определение формата представления данных

Теперь можно приступать к созданию определения службы. Од- нако прежде разделим определение службы на две части.

# Определение формата представления данных – описывает формат сообщений, получаемых и отправляемых службой. В данном примере под этим подразумевается определение схемы сообщений <EvaluateHandRequest> и <EvaluateHandResponse>.

# Определение перечня операций – описывает операции, выпол-

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

Обе эти части определения обычно (но не всегда) располагаются в едином WSDL-файле. Как правило, в WSDL-файле содержится встроенная схема на языке XML Schema, определяющая формат представления данных. Остальная часть WSDL-файла определяет перечень поддерживаемых операций в виде одного или более эле- ментов <wsdl:operation>  внутри элемента <wsdl:binding>.

Пусть вас не пугает все, что было сказано в предыдущем абзаце. Как я обещал, создание определения службы будет достаточно про- стым делом, поэтому от вас не потребуется знать все тонкости соз- дания WSDL-файлов. Главное – помнить, что определение службы делится на две основные части.

Формат представления данных определяется с помощью языка XML Schema (XSD). Схема XSD позволяет точно определить, что должно содержаться в сообщении. Мы можем определить не толь- ко элементы, встречающиеся в сообщениях, но и типы сообщений, а также ограничения на данные, которые могут передаваться в этих сообщениях.

XSD-файл легко можно создать вручную, но это слишком боль- шой объем работы, по сравнению с тем, что я хотел бы сделать. По- этому я воспользуюсь специализированным инструментом, который исследует один или более XML-файлов и на основе их содержимого производит файл схемы на языке XML Schema, с помощью которого будет проверяться допустимость XML-файлов сообщений.

Существует множество различных инструментов, позволяю- щих создавать XSD-файлы, но я предпочитаю использовать Trang. Trang – это инструмент командной строки (его можно получить по адресу: www.thaiopensource.com/relaxng/trang.html), принимаю- щий XML-файл на входе и производящий XSD-файл на выходе (рис. 15.2). Инструмент Trang написан на языке Java и потому мо- жет использоваться везде, где установлена виртуальная машина Java (JVM). Как можно предположить из URL, инструмент Trang по- зволяет генерировать схемы на языке RELAX NG (альтернативный

Рис. 15.2. Trang – это инструмент, производящий XSD-файлы на основе примеров XML-файлов

язык описания структуры XML-документа), но его также можно ис- пользовать для создания файлов на языке XML Schema. Для нужд фреймворка Spring-WS инструмент Trang будет использоваться для создания файлов на языке XML Schema.

Загрузив и распаковав дистрибутив Trang, в каталоге можно обна- ружить файл trang.jar. Это выполняемый JAR-файл, поэтому, чтобы запустить инструмент Trang, достаточно выполнить команду:

%   java  -jar  trang.jar  EvaluateHandRequest.xml

➥  EvaluateHandResponse.xml  PokerTypes.xsd

При запуске инструмента Trang я передал ему три аргумента ко- мандной строки. Первые два – файлы с примерами XML-сообщений, созданные выше. Поскольку инструменту Trang было передано оба файла, полученный в результате XSD-файл можно будет использо- вать для проверки сообщений обоих типов. Последний аргумент – имя XSD-файла, который должен получиться в результате.

При запуске с этими аргументами Trang сгенерирует определение формата представления данных для нашей службы и сохранит его в файле PokerTypes.xsd (листинг 15.1).

Листинг 15.1. Содержимое файла PokerTypes.xsd, определяющее формат представления данных для веб-службы

<?xml  version="1.0"  encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace=

"http://www.springinaction.com/poker/schemas" xmlns:schemas=

"http://www.springinaction.com/poker/schemas">

<xs:element  name="EvaluateHandRequest">

<xs:complexType>

<xs:sequence>

<xs:element maxOccurs="unbounded" ref="schemas:card"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element  name="card">

<xs:complexType>

<xs:sequence>

<xs:element  ref="schemas:suit"/>

<xs:element   ref="schemas:face"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element  name="suit"  type="xs:NCName"/>

<xs:element  name="face"  type="xs:NCName"/>

<xs:element name="EvaluateHandResponse">

<xs:complexType>

<xs:sequence>

<xs:element   ref="schemas:handName"/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="handName" type="xs:string"/>

</xs:schema>

Инструмент Trang избавляет нас от массы проблем, генерируя XSD-описание для наших сообщений. Но не избавляет от необходи- мости вручную проверять получившуюся схему. Генерируя описание XSD, инструмент Trang делает некоторые предположения о том, ка- кие данные будут передаваться в XML-сообщениях. В большинстве своем эти предположения дают вполне приемлемые результаты. Но нередко бывает необходимо вручную подправить сгенерированный XSD-файл.

Например, инструмент Trang предполагает, что значения элемен- тов <suit> и <face> должны определяться как имена, не содержащие двоеточий1 (xs:NCName). В действительности же нам требуется, чтобы

1   Имена без двоеточий – это имена, которые не содержат уточняющего пре- фикса пространства имен. То есть они не содержат символа двоеточия (:).

значениями этих элементов были простые строки (xs:string). По- этому исправим определения элементов <suit> и <face>, как показано ниже:

<xs:element name="suit" type="xs:string"/>

<xs:element   name="face"   type="xs:string"/>

Нам также известно, что элемент <suit> может иметь только че- тыре значения, поэтому можно наложить дополнительные ограни- чения:

<xs:element  name="suit"  type="schemas:Suit"  />

<xs:simpleType  name="Suit">

<xsd:restriction  base="xs:string">

<xsd:enumeration value="SPADES"  />

<xsd:enumeration  value="CLUBS"  />

<xsd:enumeration value="HEARTS" />

<xsd:enumeration  value="DIAMONDS"  />

</xsd:restriction>

</xs:simpleType>

Аналогично элемент <face> может иметь только 13 значений, по- этому определим эти ограничения в XSD-файле:

<xs:element name="face" type="schemas:Face" />

<xs:simpleType name="Face">

<xsd:restriction  base="xs:string">

<xsd:enumeration value="ACE" />

<xsd:enumeration  value="TWO"  />

<xsd:enumeration  value="THREE"  />

<xsd:enumeration  value="FOUR"  />

<xsd:enumeration value="FIVE" />

<xsd:enumeration value="SIX" />

<xsd:enumeration  value="SEVEN"  />

<xsd:enumeration value="EIGHT" />

<xsd:enumeration value="NINE" />

<xsd:enumeration value="TEN" />

<xsd:enumeration value="JACK" />

<xsd:enumeration value="QUEEN" />

<xsd:enumeration value="KING" />

</xsd:restriction>

</xs:simpleType>

Обратите также внимание: инструмент Trang ошибочно предпола- гает, что элемент <EvaluateHandRequest> может содержать неограничен- ное количество элементов <card> (maxOccurs="unbounded"). Однако при игре в покер в одних руках может содержаться только точно пять карт. Это ограничение также необходимо включить в определение элемента <EvaluateHandRequest>:

<xs:element  name="EvaluateHandRequest">

<xs:complexType>

<xs:sequence>

<xs:element  minOccurs="5"  maxOccurs="5" ref="schemas:card"/>

</xs:sequence>

</xs:complexType>

</xs:element>

Теперь определение элемента <EvaluateHandResponse> достаточно полное. Можно было бы также ограничить допустимые значения, возвращаемые в элементе <handName>, но в этом нет необходимости. Поэтому оставим определение данного элемента без изменений.

Мы закончили определение формата представления данных для службы оценки комбинации карт при игре в покер, но как быть с определением перечня операций? Разве нам не потребуется создать некоторый WSDL-файл, полностью определяющий веб- службу?

Да, WSDL-определение совершенно необходимо – в конце кон- цов, WSDL – это стандартный способ определения веб-служб. WSDL-файл можно было бы создать вручную, но в этом занятии мало приятного. И снова я обещал, что мы не будем сталкиваться со сложностями. Но должен просить вас подождать немного, прежде чем я покажу, где нам потребуется определение перечня операций. Создание WSDL-файла будет продемонстрировано в разделе 15.4.6, когда будет рассказываться о связывании компонента, генерирую- щего WSDL-определение.

Но прежде нам необходимо создать конечную точку службы. Оп- ределение службы описывает лишь сообщения, посылаемые службе и получаемые от нее, но не порядок их обработки. Посмотрим далее, как создать конечные точки обработки сообщений в Spring-WS, по- лучаемых от клиента веб-службы.

Источник:   Уоллс К., Spring в действии. – М.: ДМК Пресс, 2013. – 752 с.: ил.

По теме:

  • Комментарии