Soap технология. Simple Object Access Protocol (SOAP) - общее описание. Что такое SOAP
SOAP (Simple Object Access Protocol)
является стандартизированным протоколом передачи сообщений между клиентом и сервером. Обычно он используется совместно с HTTP(S), но может работать и с другими протоколами прикладного уровня (например, SMTP и FTP).
Тестирование SOAP с точки зрения техник тестирования ничем принципиально не отличается от работы с другими API, но для его проведения требуются предварительная подготовка (в плане теории протокола) и специальные инструменты для тестирования. В данной статье я хотела бы сформулировать небольшой чек-лист необходимых знаний и навыков, который будет одинаково полезен как тестировщику SOAP (зачастую не представляющему, «за что хвататься» после постановки задачи), так и менеджеру, вынужденному оценивать знания тестировщиков и разрабатывать планы по обучению.
Теоретическая база
Тот факт, что SOAP является протоколом, имеет большое значение для тестирования: нужно изучить сам протокол, «первичные» стандарты и протоколы, на которых он базируется, а также (по мере необходимости) существующие расширения.
XML
XML – язык разметки, схожий с HTML. Любое сообщение, отправляемое/получаемое через SOAP, – это XML-документ, в котором данные удобно структурированы и легко читаемы, например:
Не забудь написать статью!
Более подробно про XML можно узнать на w3schools или codenet (по-русски) . Обязательно обратите внимание на описание namespaces (метод разрешения конфликтов при описании элементов в XML) – в SOAP их использование необходимо.
XSD
При работе всегда удобно иметь стандартизированное описание возможных XML-документов и проверять их на корректность заполнения. Для этого существует XML Schema Definition (или сокращенно XSD). Две главные фичи XSD для тестировщика – это описание типов данных и наложение ограничений на возможные значения. Например, элемент из предыдущего примера можно сделать необязательным для заполнения и ограничить его размер 255 символами с помощью XSD:
...
...
Расширения SOAP
В работе вам также могут встретиться различные «расширения» SOAP – стандарты типа WS-*
. Одним из самых распространенных является WS-Security позволяющий работать с шифрованием и электронными подписями. Нередко вместе с ним применяется WS-Policy, с помощью которого можно управлять правами на использование вашего сервиса.
Пример использования WS-Security:
Все эти расширения – достаточно сложные конструкции, используемые далеко не в каждом SOAP-сервисе; их подробное изучение на начальном этапе освоения тестирования SOAP вряд ли будет актуально.
Инструменты
Как вы уже поняли, SOAP – дело серьезное, для работы с ним нужно знать теорию и многочисленные стандарты. На практике такая сложность привела бы к весьма ощутимым трудозатратам (например, нужно было бы каждый раз смотреть схему в блокнотике и слать запросы curl-ом). Поэтому были созданы инструменты, облегчающие работу с SOAP.
Редакторы XML / XSD
Хороший тестировщик начинает тестирование еще на стадии написания документации, поэтому для проверки схем удобно использовать специальные редакторы. Два самых известных – Oxygen (кроссплатформенный) и Altova (только для Windows); оба они являются платными. Это очень мощные программы, которыми активно пользуются аналитики при описании сервисов.
В моей практике полезными оказались три фичи редакторов: визуализация XSD, генерация XML на основе XSD и валидация XML по XSD.
1. Визуализация XSD нужна для наглядного представления схемы, позволяющего быстро вычленить обязательные элементы и атрибуты, а также существующие ограничения. Например, для запроса CheckTextRequest обязательным является элемент text, а необязательными – все три атрибута (при этом у атрибута options установлено значение по умолчанию – ноль).
Визуализация необходима в том случае, когда типов и ограничений в схеме много. Если вам нужна только она, и вы не хотите платить за специальные редакторы, то можно рассмотреть бесплатные альтернативы (например, JDeveloper).
2. Генерация XML на основе XSD полезна тогда, когда вы хотите увидеть корректный пример сообщения. Я пользуюсь ей для того, чтобы быстро поэкспериментировать с возможным заполнением сообщения и проверить нюансы работы ограничений.
3. После использования фичи из пункта 2 полезно провести валидацию XML по XSD – то есть проверить сообщение на корректность. Вместе фичи 2 и 3 позволяют отлавливать хитрые дефекты в XSD еще тогда, когда сам сервис находится в разработке.
Инструмент тестирования – SoapUI
Тестирование SOAP практически всегда подразумевает использование SoapUI . Прочитать про использование этого инструмента можно в разных источниках ( , ), но эффективнее всего будет ознакомиться с официальной документацией . Я выделяю 8 условных уровней владения SoapUI:
Уровень 1 – умею отправлять запросы
Научитесь создавать проект на основе WSDL. SoapUI может сгенерировать все необходимые запросы для вас; вам останется лишь проверить правильность их заполнения и нажать кнопочку «Send». После выработки навыков создания корректных запросов вы должны овладеть искусством формирования некорректных запросов, вызывающих появление ошибок.
Уровень 2 – умею делать Test Suites и Test Cases
Начните делать мини-автотесты. Тест-комплекты и тест-кейсы позволяют создавать сценарии тестирования API, подготавливать данные для запросов и автоматически проверять полученный ответ на соответствие ожидаемому. На первых порах их можно использовать просто как коллекции запросов. Например, если вы завели дефект и хотите быстро проверить его после фикса, можно выделить отдельный тест-комплект конкретно под запросы-дефекты.
Уровень 3 – умею писать Assertions
После освоения тест-кейсов вам будет полезно научиться делать их автоматически проверяемыми. После этого вам уже не нужно будет искать «глазами» информацию об ответе: при наличии автоматической проверки кейсы будут помечаться зеленым (если проверка пройдена) или красным (если не пройдена). SoapUI предоставляет большой набор возможных проверок (assertions), но самые удобные и простые – это Contains и Not Contains. С их помощью можно проверить факт наличия конкретного текста в полученном ответе. Эти проверки также поддерживают поиск с помощью регулярных выражений.
Уровень 4 – использую XPath и/или XQuery в Assertions
Для тех, кто немного знаком с UI с помощью Selenium, язык XPath – знакомая вещь. Грубо говоря, XPath позволяет искать элементы в XML-документе. XQuery – похожая технология, которая может использовать XPath внутри себя; этот язык гораздо мощнее, он напоминает SQL. Оба эти языка можно использовать в Assertions. Проверки с их помощью получаются более прицельными и стабильными, поэтому ваши кейсы будут пользоваться большим доверием.
Уровень 5 – умею писать сложные тесты с помощью специальных шагов
В тест-кейсах может содержаться не только один запрос, но и несколько (к примеру, когда вы хотите эмулировать стандартный сценарий работы пользователя «создать сущность» → «экспортировать сущность»). Между запросами могут находиться другие специальные шаги, например:
- Properties и Property Transfer (помогают переиспользовать данные и передавать их между запросами);
- JDBC Request (используется для получения данных из базы данных);
- Conditional Goto (позволяет сделать разветвления или циклы в тест-кейсе);
- Run TestCase (помогает вынести какие-то типовые запросы в отдельные тест-кейсы и вызывать их там, где нужно).
Уровень 6 – использую скрипты на Groovy
SoapUI позволяет писать скрипты на Groovy в различных местах. Простейший случай – это генерация данных в самом запросе с помощью вставок ${=}. Я постоянно пользуюсь такими вставками:
- ${=new Date().format(«yyyy-MM-dd’T’HH:mm:ss»)} – для вставки текущей даты и времени в необходимом формате;
- ${=java.util.UUID.randomUUID()} – для вставки корректно сформированного случайного GUID.
Полноценные скрипты можно использовать в качестве шагов в кейсах и проверках. В какой-то момент вы обнаружите, что сразу несколько специальных шагов из пятого уровня можно заменить одним скриптом.
Уровень 7 – использую MockServices
SoapUI на основе WSDL может генерировать Mock-объекты . Mock-объект – это простейшая симуляция сервиса. С помощью «моков» можно начать писать и отлаживать тест-кейсы еще до того, как сервис реально будет доступен для тестирования. Также их можно использовать в качестве «заглушек» для временно недоступных сервисов.
Уровень 8 – бог SoapUI
Вы знаете разницу между платной и бесплатной версиями SoapUI и используете SoapUI API в коде. Вы используете плагины и запускаете выполнение кейсов через командную строку и/или CI. Ваши тест-кейсы просты и легко поддерживаются. В общем, вы «съели собаку» на этом инструменте. Я бы с радостью пообщалась с тем, кто освоил SoapUI на таком уровне. Если вы являетесь таковым – отпишитесь в комментариях!
Тестирование с помощью языков программирования
Приведу пример того, как выглядит запрос к YandexSpeller API, выполненный с помощью groovy-wslite:
import wslite.soap.*
def client = new SOAPClient("http://speller.yandex.net/services/spellservice?WSDL")
def response = client.send(SOAPAction: "http://speller.yandex.net/services/spellservice/checkText") {
body {
CheckTextRequest("lang": "ru", "xmlns":"http://speller.yandex.net/services/spellservice") {
text("ошипка")
}
}
}
assert "ошибка" == response.CheckTextResponse.SpellResult.error.s.text()
assert "1" == [email protected]()
Насколько я знаю, высокоуровневых фреймворков (по типу Rest-assured) для тестирования SOAP пока не существует, но недавно появился интересный инструмент – karate . С его помощью можно описывать кейсы для тестирования SOAP и REST в виде сценариев по типу Cucumber / Gherkin . Для многих тестировщиков обращение к karate будет идеальным решением, ведь такие сценарии по сложности написания и поддержки кейсов будут лежать где-то посередине между использованием SoapUI и написанием собственного фреймворка для тестирования SOAP.
Заключение
Вряд ли вам когда-либо захочется тестировать SOAP просто так, для себя (как могло бы получиться с REST-ом). Это тяжеловесный протокол, который используется в серьезных корпоративных решениях. Но его тяжеловесность одновременно является подарком тестировщику: все используемые технологии стандартизированы, имеются качественные инструменты для работы. От тестировщика требуется лишь желание их изучить и использовать.
Давайте соберем воедино тот самый чек-лист необходимых навыков для тестировщика. Итак, если вы только начинаете тестировать SOAP сервисы, вам нужно знать и уметь использовать:
- WSDL.
- SOAP.
- Редакторы XML / XSD (на уровне визуализации XSD).
- SoapUI на уровне 1.
Как видите, основной упор приходится на изучение стандартов, в SoapUI достаточно просто уметь выполнять запросы. По мере погружения в тестирование SOAP перед вам будут возникать задачи, которые потребуют уже более серьезных навыков и знаний, но не стоит пытаться изучить всё и сразу. Гораздо важнее последовательность в повышении уровня сложности выполняемых задач. Следуя этой рекомендации, в один прекрасный момент вы поймете, что стали хорошим специалистом в этой области!
- Tutorial
Всем привет!
Так случилось, что в последнее время я стал заниматься разработкой веб-сервисов. Но сегодня топик не обо мне, а о том, как нам написать свой XML Web Service основанный на протоколе SOAP 1.2.
Я надеюсь, что после прочтения топика вы сможете самостоятельно:
- написать свою собственную серверную реализацию веб-приложения;
- написать свою собственную клиентскую реализацию веб-приложения;
- написать свое собственное описание веб-сервиса (WSDL);
- отправлять клиентом массивы однотипных данных на сервер.
1 Постановка задачи
1.1 Границы
В начале предлагаю разобраться с тем результатом, которого мы достигнем в конце топика. Как было объявлено выше, мы будем писать сервис по отправке sms-сообщений, а если еще точнее, то к нам будут поступать сообщения из разных источников по протоколу SOAP. После чего, мы рассматрим в каком виде они приходят на сервер. Сам процесс постановки сообщений в очередь для их дальнейшей отправки провайдеру, к сожалению, выходит за рамки данного поста по многим причинам.
1.2 Какими данными будем меняться?
Отлично, с границами мы определились! Следующий шаг, который необходимо сделать – решить какими данными мы будем обмениваться между сервером и клиентом. На эту тему предлагаю долго не мудрить и сразу для себя ответить на главные вопросы:- Какой минимум данных надо посылать на сервер, чтобы отправить sms-сообщение абоненту?
- Какой минимум данных надо посылать с сервера, чтобы удовлетворить потребности клиента?
- номер мобильного телефона, а также
- текст sms-сообщения.
- дату отправки sms-сообщения.
- Тип сообщения.
И все же, я что-то забыл! Если еще немного порефлексировать, то стоит отметить, что клиент за раз может отправить на сервер как одно sms-сообщение, так и некоторое их количество. Другими словами, в одном пакете данных может быть от одного до бесконечности сообщений.
В результате мы получаем, что для отправки sms-сообщения нам необходимы следующие данные:
- номер мобильного телефона,
- текст sms-сообщения,
- время отправки sms-сообщения абоненту,
- тип сообщения.
На первый вопрос мы ответили, теперь необходимо ответить на второй вопрос. И пожалуй, я позволю себе немного с халтурить. Поэтому, с сервера мы будем присылать только булевы данные, значение которых имеет следующий смысл:
- TRUE – пакет успешно дошел до сервера, прошел аутентификацию и встал в очередь для отправки sms-провайдеру
- FALSE – во всех остальных случаях
На этом мы закончили описание постановки задачи! И наконец-то приступим к самому интересному – будем разбираться что за диковинный зверь этот SOAP!
2 С чем есть SOAP?
Вообще, изначально я не планировал ничего писать о том, что такое SOAP и хотел ограничиться ссылками на сайт w3.org с нужными спецификациями, а также ссылками на Wikipedia. Но в самом конце решил написать коротенькую справочку об этом протоколе.И начну я свое повествование с того, что данный протокол обмена данными относится к подмножеству протоколов основанных на так называемой парадигме RPC (Remote Procedure Call, удалённый вызов процедур) антиподом которой является REST (Representational State Transfer, передача репрезентативного состояния). Более подробно об этом можно прочесть в Wikipedia, ссылки на статьи находятся в самом конце топика. Из этих статей нам надо уяснить следующее: «Подход RPC позволяет использовать небольшое количество сетевых ресурсов с большим количеством методов и сложным протоколом. При подходе REST количество методов и сложность протокола строго ограничены, из-за чего количество отдельных ресурсов может быть большим». Т.е., применительно к нам это означает, что на сайте в случае RPC подхода будет всегда один вход (ссылка) на сервис и какую процедуру вызывать для обработки поступающих данных мы передаем вместе с данными, в то время как при REST подходе на нашем сайте есть много входов (ссылок), каждая из которых принимает и обрабатывает только определенные данные. Если кто-то из читающих знает, как еще проще объяснить различие в данных подходах, то обязательно пишите в комментариях!
Следующее, что нам надо узнать про SOAP – данный протокол в качестве транспорта использует тот самый XML, что с одной стороны очень хорошо, т.к. сразу же в наш арсенал попадает вся мощь стека технологий основанных на данном языке разметки, а именно XML-Schema – язык описания структуры XML-документа (спасибо Wikipedia!), который позволяет производит автоматическую валидацию поступающих на сервер данных от клиентов.
И так, теперь мы знаем, что SOAP – протокол используемый для реализации удаленного вызова процедур и в качестве транспорта он использует XML! Если почитать статью на Wikipedia, то оттуда можно узнать еще и о том, что он может использоваться поверх любого протокола прикладного уровня, а не только в паре с HTTP (к сожалению, в данном топике мы будем рассматривать только SOAP поверх HTTP). И знаете, что мне во всем этом больше всего нравится? Если нет никаких догадок, то я дам подсказку – SOAP!… Всеравно не появилось догадок?… Вы точно прочли статью на Wikipedia?… В общем, не буду вас дальше мучить. Поэтому, сразу перейду к ответу: «SOAP (от англ. Simple Object Access Protocol - простой протокол доступа к объектам; вплоть до спецификации 1.2 )». Самое примечательное в этой строчке выделено курсивом! Я не знаю какие выводы сделали вы из всего этого, но мне видится следующее – поскольку данный протокол ну никак нельзя назвать «простым» (и видимо с этим согласны даже в w3), то с версии 1.2 он вообще перестал как-то расшифровываться! И стал называться SOAP, просто SOAP и точка.
Ну да ладно, прошу меня извинить, занесло немного в сторону. Как я писал ранее, в качестве транспорта используется XML, а пакеты, которые курсируют между клиентом и сервером называются SOAP-конвертами. Если рассматривать обобщенную структуру конверта, то он вам покажется очень знакомым, т.к. напоминает структуру HTML-страницы. В нем есть основной раздел – Envelop
, который включает разделы Header
и Body
, либо Fault
. В Body
передаются данные и он является обязательным разделом конверта, в то время как Header
является опциональным. В Header
может передаваться авторизация, либо какие-либо иные данные, которые на прямую не относятся к входным данным процедур веб-сервиса. Про Fault
особо рассказывать нечего, кроме того, что он приходит в клиент с сервера в случае возникновения каких-либо ошибок.
На этом мой обзорный рассказ про протокол SOAP заканчивается (более детально сами конверты и их структуру мы рассмотрим когда наши клиент и сервер наконец-то научатся запускать их друг в друга) и начинается новый – про компаньона SOAP под названием WSDL (Web Services Description Language). Да-да, это та самая штука, которая отпугивает большинство из нас от самой попытки взять и реализовать свое API на данном протоколе. В результате чего, мы обычно изобретаем свой велосипед с JSON в качестве транспорта. И так, что такое WSDL? WSDL – язык описания веб-сервисов и доступа к ним, основанный на языке XML (с) Wikipedia. Если из этого определения вам не становится понятным весь сакральный смысл данной технологии, то я попытаюсь описать его своими словами!
WSDL предназначен для того, чтобы наши клиенты могли нормально общаться с сервером. Для этого в файле с расширением «*.wsdl» описывается следующая информация:
- Какие пространства имен использовались,
- Какие схемы данных использовались,
- Какие типы сообщений веб-сервис ждет от клиентов,
- Какие данные принадлежат каким процедурам веб-сервиса,
- Какие процедуры содержит веб-сервис,
- Каким образом клиент должен вызывать процедуры веб-сервиса,
- На какой адрес должны отправляться вызовы клиента.
3 Введение в XML-Schema
Теперь мы много чего знаем о то, что такое SOAP, что находится у него внутри и имеем обзорное представление о том, какой стек технологий его окружает. Поскольку, прежде всего SOAP представляет собой способ взаимодействия между клиентом и сервером, и в качестве транспорта для него используется язык разметки XML, то в данном разделе мы немного разберемся каким образом происходит автоматическая валидация данных посредством XML-схем.Основная задачи схемы – описать структуру данных которые мы собираемся обрабатывать. Все данные в XML-схемах делятся на простые (скалярные) и коплексные (структуры) типы. К простым типам относятся такие типы как:
- строка,
- число,
- булево значение,
- дата.
Предлагаю далеко не ходить и написать XML-схему для нашего sms-сообщения! Ниже представлено xml-описание sms-сообщения:
Схема нашего комплексного типа будет выглядеть следующим образом:
Эта запись читается следующим образом: у нас есть переменная «message
» типа «Message
» и есть комплексный тип с именем «Message
», который состоит из последовательного набора элементов «phone
» типа string
, «text
» типа string
, «date
» типа dateTime
, «type
» типа decimal
. Эти типы простые и уже определены в описании схемы. Поздравляю! Мы только что написали нашу первую XML-схему!
Думаю, что значение элементов «element » и «complexType » вам стало все более-менее понятно, поэтому не будем на них больше заострять внимание и переключимся сразу же на элемент-композитор «sequence ». Когда мы используем элемент-композитор «sequence » мы сообщаем о том, что элементы включенные в него должны всегда располагаться в указанной в схеме последовательности, а также все из них являются обязательными. Но не стоит отчаиваться! В XML-схемах есть еще два элемента-композитора: «choice » и «all ». Композитор «choice » сообщает о том, что должен быть какой-то один из перечисленных в нем элементов, а композитор «all » – любая комбинация перечисленных элементов.
Как вы помните, то в первом разделе топика мы договорились о том, что в пакете может передаваться от одного до бесконечности sms-сообщений. Поэтому предлагаю разобраться как такие данные декларируются в XML-схеме. Общая структура пакета может выглядеть следующим образом:
Схема для такого комплексного типа будет выглядеть так:
В первом блоке идет знакомое нам декларирование комплексного типа «Message
». Если вы заметили, то в каждом простом типе, входящем в «Message
», были добавлены новые уточняющие атрибуты «minOccurs
» и «maxOccurs
». Как не трудно догадаться из названия, первый (minOccurs
) сообщает о том, что в данной последовательности должно быть минимум по одному элементу типа «phone
», «text
», «date
» и «type
», в то время как следующий (maxOccurs
) атрибут нам декларирует, что таких элементов в нашей последовательности максимум по-одному. В результате, когда мы пишем свои схемы для каких-либо данных, нам предоставляется широчайший выбор по их настройке!
Второй блок схемы декларирует элемент «messageList » типа «MessageList ». Видно, что «MessageList » представляет собой комплексный тип, который включает минимум один элемент «message », но максимальное число таких элементов не ограничено!
4 Пишем свой WSDL
Вы помните о том, что WSDL и есть наш веб-сервис? Надеюсь, что помните! Как мы его напишем, так на нем наш маленький веб-сервис и поплывет. Поэтому, предлагаю не халтурить.Вообще, для того, чтобы у нас все работало правильно нам надо передавать клиенту WSDL-файл с правильным MIME-типом. Для этого необходимо настроить ваш веб-сервер соответствующим образом, а именно – установить для файлов с расширением «*.wsdl» MIME-тип равный следующей строке:
Application/wsdl+xml
Но на практике, я обычно отправлял посредством PHP HTTP-заголовок«text/xml
»:
Header("Content-Type: text/xml; charset=utf-8");
и все прекрасно работало!
Хочу сразу предупредить, наш простенький веб-сервис будет иметь довольно внушительное описание, поэтому не пугайтесь, т.к. большая часть текста является обязательной водой и написав ее один раз можно постоянно копировать от одного веб-сервиса к другому!
Поскольку WSDL – это XML, то в самой первой строке необходимо прямо об этом и написать. Корневой элемент файла всегда должен называться «definitions »:
Обычно, WSDL состоит из 4-5 основных блоков. Самый первый блок – определение веб-сервиса или другими словами – точки входа.
Здесь написано, что у нас есть сервис, который называется – «SmsService
». В принципе, все имена в WSDL-файле могут быть вами изменены на какие только пожелаете, т.к. они не играют абсолютно никакой роли.
После этого мы объявляем о том, что в нашем веб-сервисе «SmsService » есть точка входа («port»), которая называется «SmsServicePort ». Именно в эту точку входа и будут отправляться все запросы от клиентов к серверу. И указываем в элементе «address » ссылку на файл-обработчик, который будет принимать запросы.
После того, как мы определили веб-сервис и указали для него точку входа – необходимо привязать к нему поддерживаемые процедуры:
Для этого перечисляется какие операции и в каком виде у будут вызываться. Т.е. для порта «SmsServicePort
» определена привязка под именем «SmsServiceBinding
», которая имеет тип вызова «rpc
» и в качестве протокола передачи (транспорта) используется HTTP. Т.о., мы здесь указали, что будем осуществлять RPC вызов поверх HTTP. После этого мы описываем какие процедуры (operation
) поддерживаются в веб-сервисе. Мы будем поддерживать всего одну процедуру – «sendSms
». Через эту процедуру будут отправляться на сервер наши замечательные сообщения! После того, как была объявлена процедура, необходимо указать в каком виде будут передаваться данные. В данном случае указано, что будут использоваться стандартные SOAP-конверты.
После этого нам необходимо привязать процедуру к сообщениям:
Для этого мы указываем, что наша привязка («binding») имеет тип «SmsServicePortType
» и в элементе «portType
» с одноименным типу именем указываем привязку процедур к сообщениям. И так, входящее сообщение (от клиента к серверу) будет называться «sendSmsRequest
», а исходящее (от сервера к клиенту) «sendSmsResponse
». Как и все имена в WSDL, имена входящих и исходящих сообщения – произвольные.
Теперь нам необходимо описать сами сообщения, т.е. входящие и исходящие:
Для этого мы добавляем элементы «message
» с именами «sendSmsRequest
» и «sendSmsResponse
» соответственно. В них мы указываем, что на вход должен прийти конверт, структура которого соответствует типу данных «Request
». После чего с сервера возвращается конверт содержащий тип данных – «Response
».
Теперь надо сделать самую малость – добавить описание данных типов в наш WSDL-файл! И как вы думаете, как описываются в WSDL входящие и исходящие данные? Думаю, что вы уже все давно поняли и сказали сами себе, что при помощи XML-схем! И вы будете абсолютно правы!
Можно нас поздравить! Наш первый WSDL был написан! И мы еще на один шаг приблизились к достижению поставленной цели.
Далее мы разберемся с тем, что нам предоставляет PHP для разработки собственных распределенных приложений.
5 Наш первый SOAP-сервер
Ранее я писал, что для создания SOAP-сервера на PHP мы будем использовать встроенный класс SoapServer. Для того, чтобы все дальнейшие действия происходили также как и у меня, вам понадобиться немного подкрутить свой PHP. Если быть еще точнее, то необходимо убедиться, что у вас установлено расширение «php-soap». Как его поставить на ваш веб-сервере лучше всего прочитать на официальном сайте PHP (см. список литературы).После того, как все было установлено и настроено нам необходимо будет создать в корневой папке вашего хостинга файл «smsservice.php » со следующим содержанием:
setClass("SoapSmsGateWay");
//Запускаем сервер
$server->handle();
То, что находится выше строчки с функцией «ini_set», надеюсь, что объяснять не надо. Т.к. там определяется какие HTTP-заголовки мы будем отправлять с сервера клиенту и настраивается окружение. В строчке с «ini_set» мы отключаем кеширование WSDL-файла для того, чтобы наши изменения в нем сразу же вступали в действие на клиенте.
Теперь мы подошли к серверу! Как видим, весь SOAP-сервер занимает всего лишь три строки! В первой строке мы создаем новый экземпляр объекта SoapServer и передаем ему в конструктор адрес нашего WSDL-описания веб-сервиса. Теперь мы знаем, что он будет располагаться в корне хостинга в файле с говорящим именем «smsservice.wsdl.php ». Во второй строке мы сообщаем SOAP-серверу какой класс необходимо дергать для того, чтобы обработать поступивший с клиента конверт и вернуть конверт с ответом. Как вы могли догадаться, именно в этом классе будет описан наш единственный метод sendSms . В третьей строке мы запускаем сервер! Все, наш сервер готов! С чем я нас всех и поздравляю!
Теперь нам необходимо создать WSDL-файл. Для этого можно либо просто скопировать его содержимое из предыдущего раздела, либо позволить себе вольности и немного его «шаблонизировать»:
";
?>
На этом этапе получившийся сервер нас должен устроить полностью, т.к. поступающие к нему конверты мы можем логировать и потом спокойно анализировать приходящие данные. Для того, чтобы мы могли что-либо получать на сервер, нам необходим клиент. Поэтому давайте им и займемся!
6 SOAP-клиент на подходе
Прежде всего нам надо создать файл, в котором будем писать клиент. Как обычно, мы его создадим в корне хоста и назовем «client.php », а внутри напишем следующее: messageList = new MessageList();
$req->messageList->message = new Message();
$req->messageList->message->phone = "79871234567";
$req->messageList->message->text = "Тестовое сообщение 1";
$req->messageList->message->date = "2013-07-21T15:00:00.26";
$req->messageList->message->type = 15;
$client = new SoapClient("http://{$_SERVER["HTTP_HOST"]}/smsservice.wsdl.php",
array("soap_version" => SOAP_1_2));
var_dump($client->sendSms($req));
Опишем наши объекты. Когда мы писали WSDL в нем для входящего на сервер конверта описывались три сущности: Request
, MessageList
и Message
. Соответственно классы Request
, MessageList
и Message
являются отражениями этих сущностей в нашем PHP-скрипте.
После того, как мы определили объекты, нам необходимо создать объект ($req
), который будем отправлять на сервер. После чего идут две самые заветные для нас строки! Наш SOAP-клиент! Верите или нет, но этого достаточно для того, чтобы на наш сервер начали сыпаться сообщения от клиента, а также для того, чтобы наш сервер успешно их принимал и обрабатывал! В первой из них мы создаем экземпляр класса SoapClient и передаем в его конструктор адрес расположения WSDL-файла, а в параметрах явно указываем, что работать мы будем по протоколу SOAP версии 1.2. В следующей строке мы вызываем метод sendSms
объекта $client
и сразу же выводим в браузере результат.
Давайте запусти и посмотрим что-же у нас наконец-то получилось!
Мне с сервера вернулся следующий объект:
Object(stdClass)
public "status" => boolean true
И это замечательно, т.к. теперь мы точно знаем о том, что наш сервер работает и не просто работает, но еще и может возвращать на клиент какие-то значения!
Теперь посмотрим на лог, который мы предусмотрительно ведем на серверной стороне! В первой его части мы видим необработанные данные, которые поступили на сервер:
Это и есть конверт. Теперь вы знаете как он выглядит! Но постоянно на него любоваться нам вряд ли будет интересно, поэтому давайте десереализуем объект из лог-файла и посмотрим все ли у нас хорошо:
Object(stdClass)
public "messageList" =>
object(stdClass)
public "message" =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 1" (length=37)
public "date" => string "2013-07-21T15:00:00.26" (length=22)
public "type" => string "15" (length=2)
Как видим, объект десериализовался правильно, с чем я нас всех хочу поздравить! Далее нас ждет что-то более интересно! А именно – мы будем отправлять клиентом на сервер не одно sms-сообщение, а целую пачку (если быть точнее, то целых три)!
7 Отправляем сложные объекты
Давайте подумаем над тем, как же нам передать целую пачку сообщений на сервер в одном пакете? Наверно, самым простым способом будет организация массива внутри элемента messageList! Давайте это сделаем: // создаем объект для отправки на сервер
$req = new Request();
$req->messageList = new MessageList();
$msg1 = new Message();
$msg1->phone = "79871234567";
$msg1->text = "Тестовое сообщение 1";
$msg1->date = "2013-07-21T15:00:00.26";
$msg1->type = 15;
$msg2 = new Message();
$msg2->phone = "79871234567";
$msg2->text = "Тестовое сообщение 2";
$msg2->date = "2014-08-22T16:01:10";
$msg2->type = 16;
$msg3 = new Message();
$msg3->phone = "79871234567";
$msg3->text = "Тестовое сообщение 3";
$msg3->date = "2014-08-22T16:01:10";
$msg3->type = 17;
$req->messageList->message = $msg1;
$req->messageList->message = $msg2;
$req->messageList->message = $msg3;
В наших логах числится, что пришел следующий пакет от клиента:
Что за ерунда, скажете вы? И будете правы в некотором смысле, т.к. только что мы узнали о том, что какой объект ушел от клиента, то абсолютно в том же виде он пришел к нам на сервер в виде конверта. Правда, sms-сообщения сериализовались в XML не так, как нам было необходимо – они должны были быть обернуты в элементы message
, а не в Struct
. Теперь посмотрим в каком виде приходит такой объект в метод sendSms
:
Object(stdClass)
public "messageList" =>
object(stdClass)
public "message" =>
object(stdClass)
public "Struct" =>
array (size=3)
0 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 1" (length=37)
public "date" => string "2013-07-21T15:00:00.26" (length=22)
public "type" => string "15" (length=2)
1 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 2" (length=37)
public "date" => string "2014-08-22T16:01:10" (length=19)
public "type" => string "16" (length=2)
2 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 3" (length=37)
public "date" => string "2014-08-22T16:01:10" (length=19)
public "type" => string "17" (length=2)
Что нам дает это знание? Только то, что выбранный нами путь не является верным и мы не получили ответа на вопрос – «Как нам на сервере получить правильную структуру данных?». Но я предлагаю не отчаиваться и попробовать привести наш массив к типу объект
:
$req->messageList->message = (object)$req->messageList->message;
В этом случае, нам придет уже другой конверт:
Пришедший в метод sendSms
объект имеет следующую структуру:
Object(stdClass)
public "messageList" =>
object(stdClass)
public "message" =>
object(stdClass)
public "BOGUS" =>
array (size=3)
0 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 1" (length=37)
public "date" => string "2013-07-21T15:00:00.26" (length=22)
public "type" => string "15" (length=2)
1 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 2" (length=37)
public "date" => string "2014-08-22T16:01:10" (length=19)
public "type" => string "16" (length=2)
2 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 3" (length=37)
public "date" => string "2014-08-22T16:01:10" (length=19)
public "type" => string "17" (length=2)
Как по мне, то «от перемены мест слагаемых – сумма не меняется» (с). Что BOGUS
, что Struct
– цель нами до сих пор не достигнута! А для ее достижения нам необходимо сделать так, чтобы вместо этих непонятных названий отображалось наше родное message
. Но как этого добиться, автору пока не известно. Поэтому единственное, что мы можем сделать – избавить от лишнего контейнера. Другими словами, мы сейчас сделаем так, чтобы вместо message
стал BOGUS
! Для этого изменим объект следующим образом:
// создаем объект для отправки на сервер
$req = new Request();
$msg1 = new Message();
$msg1->phone = "79871234567";
$msg1->text = "Тестовое сообщение 1";
$msg1->date = "2013-07-21T15:00:00.26";
$msg1->type = 15;
$msg2 = new Message();
$msg2->phone = "79871234567";
$msg2->text = "Тестовое сообщение 2";
$msg2->date = "2014-08-22T16:01:10";
$msg2->type = 16;
$msg3 = new Message();
$msg3->phone = "79871234567";
$msg3->text = "Тестовое сообщение 3";
$msg3->date = "2014-08-22T16:01:10";
$msg3->type = 17;
$req->messageList = $msg1;
$req->messageList = $msg2;
$req->messageList = $msg3;
$req->messageList = (object)$req->messageList;
Вдруг нам повезет и из схемы подтянется правильное название? Для этого посмотрим на пришедший конверт:
Да, чуда не произошло! BOGUS
– не победим! Пришедший в sendSms
объект в этом случае будет выглядеть следующим образом:
Object(stdClass)
public "messageList" =>
object(stdClass)
public "BOGUS" =>
array (size=3)
0 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 1" (length=37)
public "date" => string "2013-07-21T15:00:00.26" (length=22)
public "type" => string "15" (length=2)
1 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 2" (length=37)
public "date" => string "2014-08-22T16:01:10" (length=19)
public "type" => string "16" (length=2)
2 =>
object(stdClass)
public "phone" => string "79871234567" (length=11)
public "text" => string "Тестовое сообщение 3" (length=37)
public "date" => string "2014-08-22T16:01:10" (length=19)
public "type" => string "17" (length=2)
Как говорится – «Почти»! На этой (немного печальной) ноте предлагаю потихонечку закругляться и сделать некоторые для себя выводы.
8 Заключение
Наконец-то мы добрались сюда! Давайте определимся с тем, что вы теперь умеете делать:- вам по силам написать необходимый для вашего веб-сервиса WSDL-файл;
- вы без всяких проблем можете написать свой собственный клиент способный общаться с сервером по протоколу SOAP;
- вы можете написать свой собственный сервер общающийся с окружающим миром по SOAP;
- вы можете отправлять массивы однотипных объектов на сервер со своего клиента (с некоторыми ограничениями).
- нативный класс SoapClient не умеет правильно сериализовывать однотипные структуры данных в XML;
- при сериализации массива в XML он создает лишний элемент с именем Struct ;
- при сериализации объекта в XML он создает лишний элемент с именем BOGUS ;
- BOGUS меньшее зло чем Struct из-за того, что конверт получается компактнее (не добавляются лишние namespace"ы в XML заголовке конверта);
- к сожалению, класс SoapServer автоматически не валидирует данные конверта нашей XML-схемой (возможно, и другие сервера этого не делают).
Что такое SOAP?
SOAP расшифровывается как Simple Object Access Protocol (Простой Протокол Доступа к Объектам). Надеюсь по прочтении статьи вам останется только недоумевать: "Что за странное название?"
SOAP в теперешней его форме – это метод удаленного вызова (RPC, Remote procedure Call) по сети. (Да, он также используется для передачи документов в виде XML, но мы это пока опустим).
Давайте разбираться. Представьте, что у вас есть сервис, который возвращает биржевую котировку (stock quote) для заданного тикера (stock symbol). Он посылает данные на сайт Nasdaq и формирует на основе возвращенного HTML нужный результат. Дальше, чтобы позволить другим разработчикам использовать его внутри своих приложений, вы делаете из этого сервиса компонент, который через Интернет находит информацию о котировках. Работает он отлично, пока в один прекрасный день Nasdaq не меняет разметку своих страниц. Вам приходится пересмотреть всю логику работы компонента и разослать обновления всем разработчикам, использующим его. А им в свою очередь необходимо разослать обновления всем своим пользователям. Если это происходит на более-менее постоянной основе, вы можете нажить немало врагов среди коллег-разработчиков. А с программистами, как известно, шутки плохи. Вы же не хотите завтра доставать фотографию любимого кота из офисного шредера, правда?
Что же делать? Посмотрим... все, что вам нужно, это предоставить одну функцию, которая будет принимать на вход тикер (типа string) и возвращать биржевую котировку (типа float или double). Так не проще ли было бы просто позволить вашим разработчикам каким-то образом вызвать эту функцию через Интернет? Отлично! Тоже мне новость, есть же COM и Corba, и Java, которые этим занимаются уже годами... что правда – то правда, но эти методы не без изъяна. Удаленная настройка COM не тривиальна. Кроме того, нужно открыть столько портов в брандмауэре, что на системного администратора пива не напасешься. Да, и придется забыть о пользователях всех операционных систем кроме Windows. Но ведь позьзователи Linux тоже иногда интересуются биржей.
Хотя, похоже, что не все потеряно для пользователей Linux, если они используют DCOM, больше здесь: http://www.idevresource.com/com/library/res/articles/comonlinux.asp.
На счет Corba и Java я много сказать не могу, так что в качестве упражнения предлагаю читателям найти минусы в этих подходах.
SOAP – это стандарт, который позволяет вам описать такой удаленный вызов и вид, в котором будет возвращаться результат. Таким образом вам нужно разместить вашу функцию в приложении, доступном по сети и получать вызовы в виде SOAP пакетов. После этого вы валидируете входные данные, запускаете вашу функцию и возвращаете результат в новом SOAP пакете. Весь процесс может работать через HTTP, так что вам не придется открывать кучу портов в брандмауэре. Правда просто?
О чем эта статья
Это первая из серии статей о SOAP, которые мы пишем в Agni Software. В этой статье я постараюсь дать вам представление о том, что такое SOAP и как написать приложение, общающееся с SOAP сервером.Soap и XML
Если вам SOAP пока еще кажется простым, добавим XML. Теперь вместо имени функции и параметров мы получаем довольно сложный XML-конверт, как будто созданный для того, чтобы сбить вас с толку. Но не спешите пугаться. Дальше – больше, и вам нужно увидеть всю картину, чтобы оценить всю сложность SOAP.Если вы не знаете, что такое XML, для начала прочтите мою статью об XML здесь: http://www.agnisoft.com/white_papers/xml_delphi.asp.
Все SOAP пакеты имеют XML формат. Что это значит? Посмотрим. Взгляните на эту функцию (Pascal):
function GetStockQuote(Symbol: string) : double;
Выглядит отлично, но проблема в том, что это – Pascal. Какая польза от этого простого определения для Java-разработчика? Или для кого-то, кто работает с VB? Нам нужно что-то, что будет понятно всем, даже VB-программистам. Так дайте им XML, содержащий одну и ту же инфрмацию (параметры, значения биржевых котировок и т.д.). Вы создаете SOAP пакет, который по сути является вызовом вашей функции, обернутый в XML, чтобы любое приложения на любой платформе могло его понять. Теперь посмотрим, как выглядит наш SOAP вызов:
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
Информативно, правда? SOAP упрощается на глазах. Ладно, шутки в сторону. Теперь я постараюсь объяснить вам, как разобраться в этом SOAP вызове.
Расшифровка тегов
Первый тег, который бросается в глаза – этоСледующий тег –
Следующий тег в списке –
Лирическое отступление на счет пространств имен: Пространство имен дает возможность квалифицировать XML тег. Нельзя, к примеру, иметь две переменные с одинаковым именем в одной процедуре, но если они в двух разных процедурах, проблем не возникает. Таким образом процедура – это пространство имен, так как все имена в ней уникальны. Точно так же XML теги имеют свою область видимости внутри пространств имен, так что имея пространство имен и имя тега, можно однозначно его идентифицировать. Мы определим пространство имен как URI, чтобы отличать наш NS1 от подражателей. В приведенном выше примере NS1 – это алиас, указывающий на urn:xmethods-quotes.
Обратите внимание также на атрибут encodingStyle – этот атрибут определяет каким образом сериализуется SOAP вызов.
Внутри тега
xsi:type="xsd:string"
Приблизительно так в XML и определяются типы. (Обратите внимание на то, как хитро я использовал слово "приблизительно", делая обобщение о технологии, которая может измениться как только статья будет опубликована). Что конкретно это означает: тип, определенный в пространстве имен xsi, который, как вы заметили, определен в теге
Внутри тега
Ну и в конце, как порядочные люди, мы закрыли все теги.
Вот и разобрались с SOAP пакетом, определяющим вызов к SOAP серверу. А SOAP сервер с помощью XML парсеров, красной кнопки и космической станции "МИР" декодирует этот вызов и определяет, что вам нужна биржевая котировка. Он тут же находит нужную котировку и возвращает вам ее в таком виде:
Большинство коммерческих серверов вернуло бы гораздо больше информации, например, в какой валюте и за какую цену была куплена последняя акция. Да и цена акции, пожалуй, была бы поточнее.
Таким образом мы знаем, чего ожидает SOAP сервер и что он вернет. Так КАК же отправить эту информацию? Использовать можно любой транспорт. Самым освещенным является HTTP. Я не стану вдаваться в подробности HTTP, для тех, кто не знает – это то, что использует ваш браузер, чтобы общаться с сайтами, на которые вы заходите.
Нужный HTTP запрос будт выглядеть приблизительно так:
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Length: nnnn
SOAPAction: "Some-URI"
The soap request packet here... Единственное, что еще стоит отметить – это заголовок SOAPAction. Этот заголовок указывает на цель запроса и является обязательным. Каждый SOAP сервер может иметь неограниченное количество функций и может использовать заголовок SOAPAction чтобы определить какую функцию вызывают. Брандмауэры и мультиплексоры также могут фильтровать контент на основании этого заголовка.
SOAP ответ от HTTP сервера будет выглядеть следующим образом:
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
Soap Response packet here...
Почему HTTP? Во-первых, сетевым администраторам не придется открывать уйму отдельных портов для SOAP вызовов... веб-сервер может спокойно обрабатывать вызовы, т.к. 80-й порт обычно открыт для всех для приема входящих запросов. Еще одним преимуществом является расширяемость веб-серверов с помощью CGI, ISAPI и других нативных модулей. Эта расширяемость позволяет написать модуль, обрабатывающий SOAP запросы не задевая другого веб-контента.
Вот и все
Надеюсь, эта статья помогла пролить немного света на SOAP. Если вы еще здесь и хотите почитать больше на эту тему, посетите сайт авторов: http://www.agnisoft.com/soap
Simple Object Access Protocol (SOAP) - это протокол на базе языка XML, который определяет правила передачи сообщений по Internet между различными прикладными системами. В основном он используется для удаленного вызова процедур. Изначально протокол SOAP разрабатывался с тем расчетом, что он будет функционировать «над» HTTP (дабы упростить интеграцию SOAP в Web-приложения), однако теперь могут быть задействованы и иные транспортные протоколы, например SMTP.
Предположим, что вы создаете в Internet службу доступа к приложениям; потребители взаимодействуют с этой службой, передавая ей информацию. Ваши серверы обрабатывают данные и возвращают результаты потребителям. Как лучше всего поддерживать обмен данными с системой?
Вы могли бы создать настраиваемое клиент-серверное приложение и потребовать, чтобы потребители использовали для доступа к вашей службе специальную клиентскую программу. Но если вы намерены всерьез найти себя в Internet-бизнесе, вам придется создать клиент, работающий на всех возможных клиентских платформах - Windows, Macintosh, Unix, Linux и т. д. Другими словами, потребуется написать множество различных клиентов.
А как вы отнесетесь к использованию Web? Такое решение, естественно, вполне приемлемо, но жестко завязано на реализации браузера, и вам опять-таки придется создавать инфраструктуру, чтобы посылать и получать входящую и исходящую информацию, а также форматировать и упаковывать данные для подобного обмена. Для реализации сложных приложений можно выбрать Java или ActiveX, но тогда некоторые пользователи откажутся от ваших услуг из-за явно завышенных требований к полосе пропускания и неадекватной защиты.
Все, что требуется, - это простой протокол, который упрощает упаковку данных приложения и передает их по Web, используя адаптируемый к содержанию информации язык XML. Тем самым он гарантирует, что и отправитель и получатель смогут легко интерпретировать содержимое любого сообщения. При этом благодаря использованию в качестве транспорта Web-протокола HTTP можно будет отказаться от необходимости снижать уровень защиты межсетевых экранов.
Достаточно подробно описанный Simple Object Access Protocol (SOAP) представляет собой простой «связующий» протокол, с помощью которого узлы могут удаленно вызывать объекты приложения и возвращать результаты. SOAP предлагает минимальный набор условий, позволяющий приложению передавать сообщения: клиент может посылать сообщение для того, чтобы вызывать программный объект, а сервер может возвращать результаты этого вызова.
SOAP довольно прост: сообщения представляют собой документы XML, содержащие команды SOAP. Хотя теоретически SOAP может быть привязан к любому транспортному протоколу для приложений, как правило, он используется вместе с HTTP.
Кеннард Скрибнер, один из авторов книги Understanding SOAP: The Authoritative Solution (Macmillan USA, 2000), говорит, что SOAP работает за счет преобразования информации, необходимой для вызова метода (например, сюда относятся значения аргументов и идентификаторы транзакций) в формат XML.
Данные инкапсулируются в HTTP или в какой-то другой транспортный протокол и передаются адресату, в качестве которого обычно выступает сервер. Этот сервер выделяет данные SOAP из пакета, выполняет требуемую обработку и возвращает результаты в виде ответа SOAP.
Скрибнер отметил, что SOAP действует как протокол удаленного вызова процедур, во многом так же, как протокол Remote Method Invocation в Java или General Inter-ORB Protocol в CORBA.
По словам Скрибнера, поскольку HTTP и XML используются практически повсюду, SOAP, по-видимому, можно назвать самым масштабируемым из созданных на сегодняшний день протоколов удаленного вызова процедур. SOAP не рассчитан на то, чтобы действовать как полная объектная архитектура.
SOAP не заменяет собой протокол Remote Method Invocation в Java, Distributed Component Object Model и CORBA; он предлагает правила, которые могут использоваться любой из этих моделей. SOAP не является полным решением. Он не поддерживает активацию объектов или защиту. По словам Скрибнера, разработчики SOAP «уверены в том, что пользователи самостоятельно добавят этот код», надстраивая его над SOAP, вместо того чтобы делать его составной частью самого протокола.
На рисунке приводится пример, взятый из спецификации SOAP 1.1, в котором хост запрашивает у службы котировок стоимость определенной акции. Запрос SOAP встраивается в HTTP POST, а в теле запроса указывается тип запроса и параметр - символ акции. Ответ также предоставляет собой объект XML, инкапсулированный в ответ HTTP с единственным возвращаемым значением (34,5 в данном случае).
Особенности SOAP
С помощью SOAP разработчики могут создавать Web-службы настолько же оперативно, насколько быстро будут написаны сообщения SOAP для вызовов программ для существующих приложений, а затем добавить эти приложения в простые Web-страницы. Но, кроме того, у разработчиков есть возможности использовать вызовы SOAP в выделенных приложениях и создавать приложения, которые можно переносить на Web-страницы других людей, и тем самым избежать трудоемкого и дорогостоящего процесса разработки.
По мнению Марка Стивера, еще одного автора книги Understanding SOAP, именно эту цель преследует Microsoft в своей перспективной платформе.Net. «Здесь SOAP выступает во всем своем блеске. Он дает разработчикам действительно прекрасные возможности для создания приложений, избавляя их от мучений по поводу вероятной несовместимости», - утверждает он.
Пример SOAP
Следующий пример иллюстрирует запрос SOAP, называемый GetLastTradePrice, который позволяет клиенту послать запрос о последних котировках определенных акций.
POST/StockQuote HTTP/1.1
Host:
www.stockquoteserver.com
Content-Type:
text/xml; charset="utf-8"
Content-Length:
nnnn
SOAPAction:
"Some-URI"
В первых пяти строчках (часть заголовка HTTP) указывается тип сообщения (POST), хост, тип и длина информационного наполнения, а заголовок SOAPAction определяет цель запроса SOAP. Само сообщение SOAP представляет собой документ XML, где сначала идет конверт SOAP, затем элемент XML, который указывает пространство имен SOAP и атрибуты, если таковые имеются. Конверт SOAP может включать в себя заголовок (но не в данном случае), за которым следует тело SOAP. В нашем примере в теле содержится запрос GetLastTradePrice и символ акций, для которых запрашиваются последние котировки. Ответ на этот запрос может выглядеть следующим образом.
HTTP/1.1 200 OK
Content-Type:
text/xml; charset="utf-8"
Content-Length:
nnnn
И опять-таки первые три строки - это часть заголовка HTTP; само сообщение SOAP состоит из конверта, который содержит ответ на исходный запрос, помеченный GetLastTradePriceResponse, и включает в себя возвращаемое значение, в нашем случае 34,5.
Brett McLaughlin Перевод Илья Чекменев
SOAP - это простой протокол доступа к объектам (Simple Object Access Protocol). Если вы никогда прежде о нем не слышали, то должно быть вы живете в какой-нибудь глуши, вдали от цивилизации. Он стал последним писком моды в web программировании, и неотъемлемой частью web сервисов, которые с таким фанатизмом используются в web разработках последнего поколения. Если вы слышали о.NET, детище Microsoft, или peer-to-peer "революции", то вы слышали о технологиях, которые основаны на использовании SOAP (даже если вы не знаете что это такое). Существует не одна, а две реализации SOAP, от Apache и от Microsoft, которой посвящены тысячи страниц на их сайте технической поддержки MSDN (http://msdn.microsoft.com/).
В этой статье я расскажу вам что такое SOAP и почему он является такой важной частью в процессе развития парадигмы web программирования. Это поможет вам опустить фундаментальные основы и сразу приступить непосредственно к работе с инструментарием SOAP. Затем я дам беглый обзор существующих SOAP проектов и углубляюсь в реализацию от Apache. Эта статья не претендует на воссоздание полной картины SOAP, в моей книге "Java & XML, 2-я редакция " восполнено множество пробелов. Ответы на многие из вопросов, возникших после прочтения этой статьи вы найдете в книге.
Вступление
Для начала нужно разобраться в том, что же такое SOAP. Вы можете прочитать полное (и весьма длинное) заключение W3C по адресу http://www.w3.org/TR/SOAP . Затем, разобравшись и отбросив всю шелуху, вы поймете что SOAP это всего лишь протокол. Это простой протокол (для его использования, нет необходимости в написании нового), основанный на идее, что в некоторый момент в распределенной архитектуре возникает необходимость обмена информацией. Кроме того, для систем, в которых существует вероятность перегрузок и затруднений при обработке процессов, этот протокол весьма выгоден тем, что он легковесен и требует минимального количества ресурсов. Наконец, он позволяет осуществлять все операции через HTTP, что дает возможность обойти стороной такие хитрые штуки как firewall и уберечься от прослушивания при помощи сокетов немыслимого числа портов. Главное чтобы вы осознали это, а все остальное - детали.
Разумеется, вы хотели бы знать эти детали, и я не обойду их вниманием. В спецификации SOAP существует три базовых компонента: конверт SOAP (SOAP envelope), набор правил шифровки и средства взаимодействия между запросом и ответом. Давайте думать о сообщении SOAP как об обычном письме. Вы еще помните эти древние штуки в конвертах с почтовой маркой и адресом, записанном на лицевой стороне? Такая аналогия поможет более наглядно представить себе концепцию SOAP как "конверт". Рисунок 12-1 изображает SOAP процессы в форме этой аналогии.
Рисунок 12-1. Процесс сообщений SOAP
Запомните эту картинку и давайте рассмотрим три компонента спецификации SOAP. Я коротко расскажу о каждом из них, приводя примеры, наиболее полно представляющие эту концепцию. Эти три ключевые компонента делают SOAP столь важным и значимым. Обработка ошибок, поддержка различных шифровок, сериализация параметров, и тот факт, что SOAP работает через HTTP в большинстве случаев делают его привлекательнее прочих решений для распределенных протоколов. SOAP обеспечивает высокую степень взаимодействия с другими приложениями, которые я рассмотрел более подробно в своей книге. А сейчас я хочу сосредоточиться на основных элементах SOAP.
Конверт
Конверт SOAP аналогичен конверту обычного письма. Он содержит информацию о письме, которое будет шифровано в основном разделе SOAP, включая данные о получателе и отправителе, а также информация о самом сообщении. Например, заголовок конверта SOAP может указывать на то, как должно обрабатываться сообщение. Прежде чем приложение начнет обработку сообщения, оно анализирует информацию о сообщении, включая информацию о том, сможет ли оно вообще обработать это сообщение. В отличие от ситуации со стандартными XML-RPC вызовами (припоминаете? XML-RPC сообщения, шифровка и прочее, все объединяется в единый XML фрагмент), с SOAP текущая обработка происходит для того, чтобы узнать что-то о сообщении. Типичное SOAP сообщение может также включать стиль шифровки, которая поможет получателю в обработке сообщения. Пример 12-1 демонстрирует конверт SOAP, который завершается указанием кодировки.
Пример 12-1: Конверт SOAP
Как вы видите, шифровка задана внутри конверта, что позволяет приложению определить (используя значение атрибута encodingStyle ), сможет ли оно прочитать входящее сообщение, расположенное в элементе Body . Убедитесь в правильности пространства имен (namespace) конверта SOAP, или серверы SOAP, которые получат ваше сообщение, выдадут сообщение об ошибке из-за несоответствия версий, и вы не сможете взаимодействовать с ними.
Шифровка
Второй важный элемент SOAP - это возможность шифровки пользовательских типов данных. В RPC (и XML-RPC) шифровка может выполняться лишь для заранее определенных типов данных, которые поддерживаются в скачанном вами XML-RPC инструментарии. Шифровка других типов данных требует от вас самостоятельной модификации RPC сервера и клиента. С SOAP схема XML может быть довольно легко использована для указания новых типов данных (при помощи структуры complexType , рассмотренной во 2-й главе моей книги), и эти новые типы могут быть представлены в XML как часть основного раздела SOAP. Благодаря интеграции со схемой XML, вы можете шифровать любой тип данных в SOAP сообщении, логически описав его в схеме XML.
Вызов
Лучший способ понять как работает вызов SOAP - это сравнить его с чем-нибудь, что вам знакомо, например с XML-RPC. Если вы помните, XML-RPC вызов выглядит подобно фрагменту кода, представленному в Примере 12-2 .
Пример 12-2. Вызов в XML-RPC
// Указание используемого обработчика (парсера) XML XmlRpc.setDriver("org.apache.xerces.parsers.SAXParser"); // Указание сервера, к которому выполняется подключение XmlRpcClient client = new XmlRpcClient("http://rpc.middleearth.com"); // Создание параметров Vector params = new Vector(); params.addElement(flightNumber); params.addElement(numSeats); params.addElement(creditCardType); params.addElement(creditCardNum); // Запрос Boolean boughtTickets = (Boolean)client.execute("ticketCounter.buyTickets", params); // Обработка ответаЯ создал простейшую программу для заказа авиабилетов. Теперь взгляните на Пример 12-3 , который демонстрирует вызов в SOAP.
Пример 12-3. Вызов в SOAP
// Создание параметров Vector params = new Vector(); params.addElement(new Parameter("flightNumber", Integer.class, flightNumber, null)); params.addElement(new Parameter("numSeats", Integer.class, numSeats, null)); params.addElement(new Parameter("creditCardType", String.class, creditCardType, null)); params.addElement(new Parameter("creditCardNumber", Long.class, creditCardNum, null)); // Создание объекта Call Call call = new Call(); call.setTargetObjectURI("urn:xmltoday-airline-tickets"); call.setMethodName("buyTickets"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); call.setParams(params); // Вызов Response res = call.invoke(new URL("http://rpc.middleearth.com"), ""); // Обработка ответаКак вы видите, собственно вызов, представленный объектом Call , резидентен в памяти. Он позволяет вам задать цель вызова, метод вызова, стиль шифровки, параметры, и многие другие параметры, не представленное в этом примере. Это более гибкий механизм, чем метод XML-RPC, позволяющий вам явно задавать набор различных параметров, которые косвенно определяются в XML-RPC. Далее в этой статье вы узнаете больше о процессе вызова, в том числе вы узнаете как SOAP обрабатывает неверные запросы, иерархию ошибок и, разумеется, возвращаемые результаты вызова.
После такого краткого введения вы уже знаете достаточно, чтобы заинтересоваться этой забавной штукой. А теперь позвольте мне представить вам реализацию SOAP, которую я собираюсь использовать. Я объясню причины по которым остановил свой выбор именно на ней и рассмотрю некоторые примеры кода.
Настройка
Теперь, когда вы познакомились с основами концепции, настало время для самой интересной части: программирования. Для этого вам потребуется удобный проект или продукт, найти который проще чем может показаться на первый взгляд. Если вам нужен Java проект, предоставляющий возможности SOAP, то его не надо долго искать. Существует две группы продуктов: коммерческие и бесплатные. Как и в своей книге, я буду избегать упоминания коммерческих продуктов. Это вовсе не потому что они плохи (даже наоборот, некоторые из них прекрасны), а потому что я хотел бы чтобы любой читатель мог попробовать любой из приведенных примеров. Это связано с доступностью, которой многие коммерческие продукты не обладают. Вы должны заплатить за их использование, или временно использовать их в течении ограниченного периода времени после скачивания.
Таким образом мы плавно подошли к проектам с открытым источником (open source). Из этой области я могу назвать лишь один продукт: Apache SOAP. Он расположен по адресу http://xml.apache.org/soap и предоставляет инструментарий SOAP для Java. На момент написания книги вышла версия 2.2, которую вы можете скачать с web сайта Apache. Именно эту версию я и буду использовать в примерах для этой статьи.
Другие альтернативы
Прежде чем перейти к инсталляции и настройке Apache SOAP я отвечу на несколько вопросов, которые могли закрасться в ваш разум. По-моему я достаточно ясно объяснил причины по которым не использую коммерческие продукты. Тем не менее, вы можете подумать о некоторых других проектах с открытым источником или родственных им, которые вам хотелось бы использовать, и вы удивлены что я их никак не прокомментировал.
Как насчет IBM SOAP4J?
Первым в списке альтернатив значится реализация от IBM: SOAP4J. Работа IBM легла в основу проекта Apache SOAP, также как IBM XML4J переросла в то, что теперь известно как проект XML парсера Apache Xerces. Предполагается что реализация от IBM будет переработана, объединившись с Apache SOAP. Примерно то же случилось с IBM"овским XML4J: теперь он лишь обеспечивает пакетирование в Xerces. Это только лишь подчеркивает тенденции - крупные производители зачастую поддерживают и используют OpenSource проекты, в данном случае оба проекта (Apache и IBM) используют одну и ту же кодовую базу.
Разве Microsoft вне игры?
Разумеется нет. Microsoft и его реализация SOAP, равно как и все направление.NET (более подробно рассмотренное в моей книге), весьма значительны. В действительности я хотел уделить большую часть времени детальному рассмотрению реализации SOAP от Microsoft, но она поддерживает только COM объекты иже с ними и не поддерживает Java. Ввиду этих причин подобное описание не могло войти в статью про Java и XML. Тем не менее, Microsoft (несмотря на все претензии, которые мы, как разработчики, имеем к этой компании) проделала важную работу в сфере web сервисов, и вы совершите ошибку если без раздумий ее отвергнете, руководствуясь лишь голыми эмоциями. Если у вас есть необходимость работать с COM или компонентами Visual Basic, я настоятельно рекомендую вам попробовать использовать инструментарий Microsoft SOAP, доступный по адресу http://msdn.microsoft.com/library/default.asp?url=/nhp/Default.asp?contentid=28000523 наряду с множеством других ресурсов SOAP.
Что такое Axis?
Те из вас, кто следит за деятельностью Apache, должно быть слышали об Apache Axis. Axis это инструментарий SOAP следующего поколения, разрабатываемый также под эгидой Apache XML. За SOAP (спецификацией, а не специфической реализацией), стремительно и радикально развивающейся в последнее время, следить весьма трудно. Попытаться создать версию SOAP, полностью соответствующую текущим требованиям, изменяющимся в ходе развития, также довольно сложно. В результате, текущая версия Apache SOAP предлагает некое решение, ограниченное его конструкцией. Решив что не стоит пытаться полностью перепроектировать существующий инструмент, разработчики Apache приступили к созданию проекта на базе нового кода. Так родился Axis. Название SOAP также претерпело изменение, сначала из SOAP превратившись в XP, а затем в XMLP. Затем из имени нового SOAP было исключено название спецификации и родилось название "Axis". Но сейчас похоже что W3C вновь возвращается к названию спецификации SOAP (версии 1.2 или 2.0), так что все еще может поменяться и путаницы будет еще больше!
Думайте об IBM SOAP4J как об архитектуре?1 инструментария SOAP. А об Apache SOAP (рассматриваемой в этой статье), как об архитектуре?2. А Axis представляет собой архитектуру?3, архитектуру нового поколения. Этот проект использует SAX, тогда как Apache SOAP базируется на DOM. Кроме того, Axis, в отличие от Apache SOAP, предоставляет более дружественный подход при взаимодействии с пользователем. После перечисления этих достоинств вы наверное придете в недоумение, почему я не выбрал в качестве предмета изучения Axis. Просто это было бы несколько преждевременно. В настоящее время готовится к выходу лишь версия 0.51 Axis. Это еще не бета, и даже не альфа версия. Я с удовольствием мог бы расписывать новые возможности Axis, но у вас не было бы никаких шансов убедить ваше руководство в возможности использования программного обеспечения с открытым источником версии ниже альфы для нужд вашей сверх важной системы. Поэтому я решил сфокусироваться на чем-то, что вы реально можете использовать уже сегодня - Apache SOAP. Я думаю что к моменту выхода финальной версии Apache Axis, я обновлю этот материал в следующем издании своей книги. А до тех пор давайте сосредоточимся на решении, которое уже доступно.
Установка
Возможны две формы установки SOAP. Первая - это запуск клиента SOAP, используя SOAP API для связи с сервером, который может принимать сообщения SOAP. Второй способ - запуск сервера SOAP, который может получать сообщения от клиента SOAP. В этом разделе я описал обе процедуры.
Клиент
Для использования клиента SOAP вам необходимо сначала скачать Apache SOAP, доступный на http://xml.apache.org/dist/soap . Я скачал версию 2.2 в бинарном формате (из подкаталога version-2.2 ). Затем вы должны разархивировать содержимое архива в директорию на вашем компьютере. В моем случае это была директория javaxml2 (c:\javaxml2 на моем компьютере с Windows, /javaxml2 на моем компьютере с Mac OS X). В результате файлы разархивировались в /javaxml2/soap-2_2 . Вам также потребуется скачать пакет JavaMail, доступный на сервере Sun http://java.sun.com/products/javamail/ . Он потребуется для поддержки протокола передачи SMTP, используемого в Apache SOAP. Затем скачайте Java Beans Activation Framework (JAF), также доступный на сервере Sun http://java.sun.com/products/beans/glasgow/jaf.html . Исходя из предположения что у вас уже установлен и готов к использованию Xerces или другой XML парсер.
Примечание: Убедитесь в том, что ваш XML парсер JAXP-совместимый и корректно использует пространство имен. Скорее всего ваш парсер удовлетворяет этим требованиям.Если у вас возникли проблемы, лучше вернуться к использованию Xerces.
Примечание: Используйте последние версии Xerces. Версия 1.4 и выше подойдет. Существует ряд ошибок при работе с SOAP и Xerces 1.3(.1), поэтому я советую не использовать такое сочетание.
Разархивируйте JavaMail и JAF пакеты, а затем включите их jar файлы в ваш classpath, а также библиотеку soap.jar . Каждый из этих jar файлов должен находиться либо в корневом каталоге соответствующей программы, или в подкаталоге /lib . По завершении ваша переменная classpath должна выглядеть примерно следующим образом:
$ echo $CLASSPATH /javaxml2/soap-2_2/lib/soap.jar:/javaxml2/lib/xerces.jar: /javaxml2/javamail-1.2/mail.jar:/javaxml2/jaf-1.0.1/activation.jarДля Windows она будет выглядеть так:
c:\>echo %CLASSPATH% c:\javaxml2\soap-2_2\lib\soap.jar;c:\javaxml2\lib\xerces.jar; c:\javaxml2\javamail-1.2\mail.jar;c:\javaxml2\jaf-1.0.1\activation.jarИ, наконец, добавьте директорию javaxml2/soap-2_2/ в ваш classpath для запуска примеров SOAP. Я описал настройку для нескольких примеров, приведенных в этой главе.
Сервер
Чтобы создать SOAP-совместимый набор серверных компонент вам для начала потребуется движок сервлета. Как и в предыдущих главах, в качестве примера для этой главы я использовал Apache Tomcat (доступный на http://jakarta.apache.org/). Вам потребуется добавить все необходимое клиенту в classpath сервера. Самый простой способ сделать это - сбросить soap.jar , activation.jar и mail.jar , а также ваш парсер, в каталог библиотек вашего движка сервлетов. Для Tomcat это каталог /lib, в котором содержатся библиотеки для автоматической загрузки. Если вы хотите обеспечить поддержку скриптов (которые не обсуждаются в этой главе, но есть в примерах Apache SOAP), вам нужно поместить bsf.jar (доступный на http://oss.software.ibm.com/developerworks/projects/bsf) и js.jar (доступный на http://www.mozilla.org/rhino/) в тот же каталог.
Примечание: Если вы используете Xerces c Tomcat, вам нужно будет повторить фокус, который я описывал в главе 10. Переименуйте parser.jar в z_parser.jar , а jaxp.jar в z_jaxp.jar , чтобы убедиться в том, что xerces.jar и включенная версия JAXP загружается перед каким-либо другим парсером или реализацией JAXP.
Затем перезагрузите ваш движок сервлетов, после чего вы будете готовы к написанию серверных компонент SOAP.
Сервлет маршрутизатора и клиент администратора
Помимо основных операций, Apache SOAP включает сервлет маршрутизатора, а также клиент администратора. Даже если вы не собираетесь их использовать, я рекомендую вам установить их, чтобы протестировать правильность установки SOAP. Этот процесс зависит от того, какой движок сервлетов вы используете, поэтому я ограничусь описанием процесса установки для Tomcat. Инструкции по установке для некоторых других движков сервлетов вы найдете на http://xml.apache.org/soap/docs/index.html .
Установка под Tomcat очень проста: просто возьмите файл soap.war из директории soap-2_2/webapps и сбросьте его в директорию $TOMCAT_HOME/webapps - и все! Чтобы проверить установку укажите в броузере адрес http://localhost:8080/soap/servlet/rpcrouter . Вы должны получить ответ, наподобие указанного на рис.12-2 .
Рисунок 12-2. Сервлет RPC маршрутизатора
Несмотря на то что сообщение похоже на сообщение об ошибке, оно свидетельствует о том что все работает правильно. Вы должны получить такой же отклик, указав в броузере адрес клиента администратора: http://localhost:8080/soap/servlet/messagerouter .
В завершение тестирования сервера и клиента, убедитесь в том, что вы полностью следовали всем инструкциям. Затем запустите следующий класс Java, как это показано ниже, для поддержки URL вашего сервлета для сервлета маршрутизатора RPC:
C:\>java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter list Deployed Services:Вы должны получить пустой список сервисов, как это показано выше. Если вы получите какие-либо сообщения, ознакомьтесь с длинным перечнем возможных ошибок, доступным на http://xml.apache.org/soap/docs/trouble/index.html . Это наиболее полный перечень проблем, с которыми вы могли столкнуться. Если вы получили пустой список, это значит что настройка завершена и вы готовы начать рассмотрение примеров, приведенных в этой главе.
Приступим
Существует три основных этапа в написании любых систем на базе SOAP. Перечислив, я коротко остановлюсь на каждой из них:
- Выбор между SOAP-RPC и SOAP сообщениями;
- Написание или получение доступа к SOAP сервису;
- Написание или получение доступа к SOAP клиенту.
Первым этапом является выбор, будете ли вы использовать SOAP для RPC вызовов (при которых удаленная процедура выполняется на сервере), или сообщения (когда клиент просто посылает фрагменты информации серверу). Я подробно рассматриваю эти процессы далее. После того как вы приняли это решение, вам потребуется получить доступ или создать собственный сервис. Разумеется, поскольку все мы - профессионалы в Java, в этой главе рассказывается о том как создать свой собственный. И, наконец, вам нужно написать клиента для этого сервиса, вот и все дела!
RPC или Messaging?
Ваша первая задача не имеет отношения к программированию и носит скорее дизайнерский характер. Вам нужно выбрать, будете ли вы использовать сервис RPC или сообщения. Будем считать что с RPC вы близко познакомились (например, прочитав одну из глав моей книги). Клиент выполняет удаленную процедуру на сервере, а затем получает отклик. При таком сценарии, SOAP выступает в роли XML-RPC системы с расширенными возможностями, обеспечивающей лучшую обработку ошибок и передачу сложных типов данных по сети. Вы уже знакомы с этой концепцией, и, поскольку в SOAP проще писать именно RPC системы, я начну с них. В этой статье описывается создание RPC сервиса, RPC клиента, и запуск системы в действие.
Другой стиль работы SOAP основан на обмене сообщениями. Вместо выполнения удаленных процедур, он используется только для обмена информацией. Как вы можете догадаться, это мощный инструмент, не требующий знания клиентом отдельных методов какого-либо сервера. Он также делает моделирование удаленных систем более изолированным, позволяя использовать пакеты данных (пакеты в фигуральном смысле, а не в сетевом) для передачи другим системам. При этом другим системам не обязательно знать об операциях, которые совершались с этими данными. Такой стиль сложнее чем RPC программирование, поэтому я не буду риводить его здесь. Вы найдете его в моей книге, наряду с другими деталями бизнес-бизнес взаимодействия. А для начала познакомьтесь с SOAP-RPC программированием.
Как и большинство дизайнерских проблем, принятие этого решения зависит только от вас. Проанализируйте ваше приложение и постарайтесь определить для чего вам нужно использовать SOAP. Если у вас есть сервер и набор клиентов, которые выполняют специфические бизнес функции по запросу, то вам более подходит RPC. В сложных системах, в которых обмен данными - нечто более чем просто выполнение специфических бизнес функций по запросу, гораздо предпочтительней использование сообщений SOAP.
RPC сервис
Теперь, когда с формальностями покончено, настало время действовать. Как вы знаете, в RPC вам потребуются классы, методы которых будут выполняться удаленно.
Фрагменты кода
Я начну с рассмотрения фрагментов кода для сервера. Эти фрагменты представляют собой классы с методами, выполняемыми для RPC клиентов . В качестве примеров я использовал код из своей книги. Вместо того, чтобы использовать простые классы, я выбрал более сложный пример чтобы как можно наглядней продемонстрировать возможности SOAP. Итак, в качестве примера я использовал класс CD. Сначала определяем элемент map для каждого нестандартного типа параметров. Для атрибута encodingStyle , по крайней мере в Apache SOAP 2.2. вы должны указать значение http://schemas.xmlsoap.org/soap/encoding/ . На данный момент это единственная поддерживаемая кодировка. Вам нужно указать пространство имен для типа, определяемого пользователем, а затем имя класса с префиксом пространства имен для этого типа. В нашем случае для этих целей я использовал выдуманное пространство имен и простой префикс "x ". Затем, используя атрибут javaType , задал реальное имя Java класса (для этого случая - javaxml2.CD ). И, наконец, куралесил с атрибутами java2XMLClassName и xml2JavaClassName . С их помощью задается класс, конвертируемый из Java в XML и наоборот. Я использовал потрясающе удобный класс BeanSerializer, также входящий в комплект поставки Apache SOAP. Если ваш пользовательский параметр в формате JavaBean, этот сериализатор и десериализатор избавит вас от необходимости писать свой собственный. Вам нужен класс с конструктором по умолчанию (вспомните, для класса CD я задал простой, без каких-либо параметров, конструктор), и публикация всех данных этого класса при помощи методов setXXX и getXXX . Поскольку класс CD прекрасно удовлетворяет всем этим требованиям, BeanSerializer работает идеально.
Примечание: То, что класс CD соответствует требованиям BeanSerializer . не имеет большого значения. Большинство классов легко приводятся к этому формату. Поэтому я советую избегать написания собственных сериализаторов и десериализаторов. Это лишняя головная боль (ничего сложного, но слишком кропотливо) и рекомендую вам сэкономить силы и использовать в своих пользовательских параметрах конвертацию бинов. Во многих случаях преобразования бинов требуют лишь наличия в вашем классе конструктора по умолчанию (без параметров).
Теперь повторно воссоздадим jar файл и переразместим наш сервис:
(gandalf)/javaxml2/Ch12$ java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter xml/CDCatalogDD.xmlВнимание: Если вы оставите запущенным свой движок сервлета и в это же время переразмещаете сервис, вам потребуется перезапустить движок сервлета, чтобы активировать новые классы для сервиса SOAP и переразместить сервис.
Теперь осталось модифицировать клиент для использования новых классов и методов. Пример 12-10 содержит модифицированную версию клиентского класса CDAdder . Изменения, внесенные в предыдущую версию, выделены.
Пример 12-10: Обновленный класс CDAdder
package javaxml2; import java.net.URL; import java.util.Vector; import org.apache.soap.Constants; import org.apache.soap.Fault; import org.apache.soap.SOAPException; import org.apache.soap.encoding.SOAPMappingRegistry; import org.apache.soap.encoding.soapenc.BeanSerializer; import org.apache.soap.rpc.Call; import org.apache.soap.rpc.Parameter; import org.apache.soap.rpc.Response; import org.apache.soap.util.xml.QName; public class CDAdder { public void add(URL url, String title, String artist, String label) throws SOAPException { System.out.println("Добавление CD с названием "" + title + "" исполнителя "" + artist + "" студии " + label); CD cd = new CD(title, artist, label); // Создание объекта вызова Call Call call = new Call(); call.setSOAPMappingRegistry(registry); call.setTargetObjectURI("urn:cd-catalog"); call.setMethodName("addCD"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); // Установка параметров Vector params = new Vector(); params.addElement(new Parameter("cd", CD.class, cd, null)); call.setParams(params); // Обработка Invoke вызова Response response; response = call.invoke(url, ""); if (!response.generatedFault()) { System.out.println("Добавление CD успешно завершено."); } else { Fault fault = response.getFault(); System.out.println(Ошибка: " + fault.getFaultString()); } } public static void main(String args) { if (args.length != 4) { System.out.println("Шаблон: java javaxml2.CDAdder " + "\"[Заголовок CD]\" \"[Имя исполнителя]\" \"[Студия CD]\""); return; } try { // URL SOAP сервера, к которому осуществляется подключение URL url = new URL(args); // Get values for new CD String title = args; String artist = args; String label = args; // Add the CD CDAdder adder = new CDAdder(); adder.add(url, title, artist, label); } catch (Exception e) { e.printStackTrace(); } } }Единственное по-настоящему интересное изменение связано с отображением класса CD :
// Отображение этого типа, чтобы его можно было использовать с SOAP SOAPMappingRegistry registry = new SOAPMappingRegistry(); BeanSerializer serializer = new BeanSerializer(); registry.mapTypes(Constants.NS_URI_SOAP_ENC, new QName("urn:cd-catalog-demo", "cd"), CD.class, serializer, serializer);Вот каким образом пользовательский параметр может быть кодирован и передан по сети. Я уже рассказывал каким образом класс BeanSerializer может быть использован для обработки параметров в формате JavaBean, например таких как класс CD . Для их указания серверу я использовал дискриптор размещения, несмотря на это теперь мне нужно сообщить клиенту, что нужно использовать этот сериализатор и десериализатор. Эту функцию и выполняет класс SOAPMappingRegistry . Метод mapTypes() берет зашифрованную строку (и вновь для этого лучше использовать константу NS_URI_SOAP_ENC ), и информацию о типе параметра, для которого должна использоваться специальная сериализация. Сначала указывается QName. Вот почему в дискрипторе размещения было использовано странное пространство имен. Вам нужно указать здесь тот же URN, а также локальное имя элемента (для этого примера "CD"), затем Java объект Class класса, который будет сериализован (CD.class ) и, наконец, экземпляр класса для сериализации и десериализации. Для этого примера в обоих случаях будет фигурировать экземпляр BeanSerializer . После того как все эти настройки будут внесены в реестр, сообщите об этом объекту Call при помощи метода setSOAPMapping-Registry() .
Вы можете запустить этот класс, как было показано раньше, добавив CD, и все должно работать как положено:
C:\javaxml2\build>java javaxml2.CDAdder http://localhost:8080/soap/servlet/rpcrouter "Tony Rice" "Manzanita" "Sugar Hill" Добавление CD с заголовком "Tony Rice" исполнителя "Manzanita" студии Sugar Hill Успешное добавление CD.Я оставил модификацию класса CDLister для вас. Все производится по тому же шаблону. Чтобы проверить себя можете обратиться к файлам с примерами к моей книге, которые уже содержат эти обновленные классы.
Примечание: Вы можете решить что, поскольку класс CDLister напрямую не взаимодействует с объектом CD (возвращаемое методом list() значение имеет тип Hashtable ), то вам не нужно вносить каких-либо изменений. Тем не менее, возвращаемый класс Hashtable содержит экземпляры объекта CD . Если SOAP не знает как десериализовать их, клиент выдаст сообщение об ошибке. В этом случае для решения проблемы вы должны указать в объекте Call экземпляр SOAPMappingRegistry .
Эффективная обработка ошибок
Теперь, когда вы познакомились с пользовательскими объектами, сделали RPC вызовы и прочее, позвольте мне рассказать о менее увлекательной теме: обработке ошибок. При любой сетевой транзакции может произойти множество сбоев. Не запускается сервис, ошибка в работе сервера, не удается найти объект, отсутствуют классы и множество прочих проблем. До сих пор я просто использовал метод fault.getString() для генерации сообщений об ошибках. Но этот метод не всегда может оказаться полезным. Чтобы увидеть его в действии, снимите комментарий в конструкторе CDCatalog :
public CDCatalog() { //catalog = new Hashtable(); // Создание каталога addCD(new CD("Nickel Creek", "Nickel Creek", "Sugar Hill")); addCD(new CD("Let it Fall", "Sean Watkins", "Sugar Hill")); addCD(new CD("Aerial Boundaries", "Michael Hedges", "Windham Hill")); addCD(new CD("Taproot", "Michael Hedges", "Windham Hill")); }Перекомпилируйте его, перезапустите движок сервлета и переразместите его. В результате этого возникнет исключительная ситуация NullPointerException при попытке конструктора класса добавить CD в неинициализированный Hashtable . При запуске клиента появится сообщение об ошибке, но оно будет не очень информативным:
(gandalf)/javaxml2/build$ java javaxml2.CDLister http://localhost:8080/soap/servlet/rpcrouter Просмотр текущего каталога CD. Ошибка: Не удается разрешить целевой объект(Unable to resolve target object): nullЭто совсем не та информация, которая может помочь при обнаружении и исправлении ошибки. Тем не менее фреймуорк исправно справляется с обработкой ошибок. Вы помните DOMFaultListener , который вы задавали как значение элемента faultListener ? Настал его час вступить в игру. Возвращаемый в случае ошибки объект Fault содержит DOM (объектную модель документа) org.w3c.dom.Element с детальной информацией об ошибке. Сначала добавьте в исходный код выражение для импортирования java.util.Iterator :
import java.net.URL; import java.util.Enumeration; import java.util.Hashtable; import java.util.Iterator; import java.util.Vector; import org.apache.soap.Constants; import org.apache.soap.Fault; import org.apache.soap.SOAPException; import org.apache.soap.encoding.SOAPMappingRegistry; import org.apache.soap.encoding.soapenc.BeanSerializer; import org.apache.soap.rpc.Call; import org.apache.soap.rpc.Parameter; import org.apache.soap.rpc.Response; import org.apache.soap.util.xml.QName;Теперь внесем изменения для обработки ошибок в методе list():
if (!response.generatedFault()) { Parameter returnValue = response.getReturnValue(); Hashtable catalog = (Hashtable)returnValue.getValue(); Enumeration e = catalog.keys(); while (e.hasMoreElements()) { String title = (String)e.nextElement(); CD cd = (CD)catalog.get(title); System.out.println(" "" + cd.getTitle() + "" исполнителя " + cd.getArtist() + " студии " + cd.getLabel()); } } else { Fault fault = response.getFault(); System.out.println("Ошибка: " + fault.getFaultString()); Vector entries = fault.getDetailEntries(); for (Iterator i = entries.iterator(); i.hasNext();) { org.w3c.dom.Element entry = (org.w3c.dom.Element)i.next(); System.out.println(entry.getFirstChild().getNodeValue()); } }Используя метод getDetailEntries() вы получаете доступ к поддерживаемым сервисом SOAP и сервером с необработанным данным, с информацией о проблеме. Код повторно обрабатывает их (как правило существует только один элемент, но он требует пристального внимания) и перехватывает DOM Element , содержащийся в каждой записи. По сути дела, вот XML с которым вы работаете:
Иными словами, объект Fault предоставляет вам доступ к части конверта SOAP, которая содержит ошибки. Кроме того, Apache SOAP обеспечивает трассировку стека Java в случае возникновения ошибок, предоставляющую детализованную информацию, необходимую для их исправления. Перехватив элемент stackTrace и распечатав значение узла Text из этого элемента ваш клиент может распечатать трассировку стека сервера. Скомпилировав эти изменения и перезапустив клиент вы получите следующий результат:
C:\javaxml2\build>java javaxml2.CDLister http://localhost:8080/soap/servlet/rpcr outer Просмотр текущего каталога CD. Ошибка: Не удается разрешить целевой объект: null java.lang.NullPointerException в javaxml2.CDCatalog.addCD(CDCatalog.java:24) в javaxml2.CDCatalog.Это немногим лучше, но по крайней мере вы можете видеть лакомную информацию о том, что возникла исключительная ситуация NullPointerException и даже узнать номера строк в классах сервера, в которых возникла эта проблема. Результат этих последних изменений позволил вам получить наглядное представление о проблеме обработки ошибок. Теперь вы должны проверить на наличие ошибок классы вашего сервера. Да, чуть не забыл, перед этим не забудьте обратно изменить ваш класс CDCatalog , чтобы избавиться от намеренно внесенных нами для наглядности ошибок!
- Ведется множество разговоров относительно запуска SOAP через другие протоколы, например SMTP (или даже Jabber). Пока стандарт SOAP не предусматривает этого, но подобные возможности могут быть добавлены в будущем. Поэтому не удивляйтесь если встретитесь с активными обсуждениями этой темы.
