Практическое использование Web-сервисов в IBM Lotus Domino 7: Написание и проверка простых Web-сервисов

Опции документа Опции документа, требующие включения JavaScript, не отображаются Обсудить Исходные тексты примера Выскажите мнение об этой странице Помогите нам улучшить содержание

Уровень сложности: средний

Джулиан Робиччо, разработчик, консультант

27.11.2007

Во второй статье нашей серии о Web-сервисах мы покажем вам, как написать простой, принимающий и возвращающий простые типы данных, массивы и входяще-исходящие параметры Web-сервис в IBM Lotus Domino V7.0. Еще мы рассмотрим несколько методов тестирования с использованием таких инструментов, как soapUI, Eclipse, MSSOAP toolkit и Apache Axis.

Итак, вы решили написать Web-сервис. Великолепно! Если вы прочитали нашу первую статью "Практическое использование Web-сервисов в IBM Lotus Domino 7: Что такое Web-сервисы и почему они важны?", то вы понимаете, что такое Web-сервисы и почему они важны. При помощи IBM Lotus Domino V7.0 вы можете запросто создавать свои Web-сервисы, которыми смогут пользоваться клиенты или системы. Иногда это ничуть не сложнее, чем написать агента.

Хотя в IBM Lotus Domino Designer писать Web-сервисы можно как на LotusScript, так и на Java, все примеры в статье написаны на LotusScript. Однако в базе данных, идущей примером к этой статье, (смотрите в разделе Загрузка) есть примеры Web-сервисов, написанных как на LotusScript, так и на Java.

Краткое вступление

В Lotus Domino V7.0 в Lotus Domino Designer появился новый проектировочный элемент - Web-сервис. Открыв базу данных в клиенте Lotus Domino Designer V7.0, вы увидите Web-сервисы прямо под элементом Agents в дереве проектировочных элементов секции Shared Code (см. рисунок 1).

Lotus Domino разбирается за вас с созданием WSDL и работой с SOAP, и все что требуется от вас - написать код для самого сервиса так, будто вы пишите агента. Если вы определяете, какой класс использовать в качестве интерфейса для сервиса, то Lotus Domino может опубликовать файл WSDL, преобразовать входящие запросы SOAP в запросы для методов вашего класса и вернуть результаты вашего метода (если они есть) в качестве ответа SOAP.

Кроме создания кода вам надо только написать класс LotusScript или Java. Остальное делает Lotus Domino!

В начало

Написание простого Web-сервиса

Давайте по-быстрому напишем Web-сервис. Для создания нового Web-сервиса откройте базу данных в Lotus Domino Designer, перейдите в проектирование базы данных на секцию Web-сервисов и нажмите на кнопку New Web Service (см. рисунок 1).

Появится окно, похожее на то, которое вы видите, создавая агента (см. рисунок 2). В окне Web Services Properties укажите имя нового Web-сервиса (в нашем примере - EchoTestService) и закройте окно. Мы коротко рассмотрим отдельные поля окна Properties.

Теперь у вас появится экран, похожий на тот, в котором пишутся агенты LotusScript. Нажмите (Declarations) во вкладке Objects в событиях LotusScript, и вы сможете написать класс (классы должны быть обязательно определены в секции (Declarations)). Введите этот код в IDE:

                
Class EchoTest
	Public Function Echo (txt As String) As String
		Echo = txt
	End Function
End Class

Вот что делает этот код:

• Создает класс EchoTest.
• Определяет в классе метод Echo, принимающий строку и возвращающий строку (функции и подпрограммы в классах называются методами).

Метод Echo из EchoTest принимает строчный параметр и возвращает такую же строку. Давайте разберемся, является ли это полноценным Web-сервисом. Попробуйте сохранить и закрыть сервис. Вы получите сообщение об ошибке:

The Web Service has been saved, but is not valid: 
Please specify which class exposes your Web service interface(s), 
using the 'PortType class' field of the Web Service properties panel.

(Web-сервис сохранен, но она с ошибками: Определите, пожалуйста, какой класс будет публиковать интерфейс вашего Web-сервиса, воспользуйтесь полем 'PortType class' на панели свойств Web-сервиса.)

Чтобы избежать эту ошибку, откройте окно Web Service Properties и определите используемый класс. Поскольку классов в коде может быть определено много, вы должны выбрать только один из них в качестве интерфейсного. В этом классе должны быть публичные методы, к которым смогут обращаться пользователи.

В окне свойств на первой закладке в поле PortType class введите EchoTest (класс, который вы создали). Закройте окно и попробуйте опять сохранить и закрыть Web-сервис. На этот раз должно сработать. У вас получился работающий Web-сервис!

В начало

Окно свойств Web-сервиса

Давайте снова откроем Web-сервис и окно его свойств. Первая закладка в окне (Basics - базовые настройки) выглядит как на рисунке 3.

Во вкладке Basic есть следующие поля:

• Name (Имя) (обязательное). Имя Web-сервиса, оно используется при запрашивании клиентами файла WSDL или методов сервиса.
• Alias (псевдоним). Альтернативное имя, дополнительное к основному, по которому пользователи могут обращаться к сервису.
• Comment (комментарий). Поле для информации о Web-сервисе (не стоит сюда писать больше одного предложения; длинные описания лучше размещать в комментариях в коде).
• Warn if the WSDL interface is modified (предупреждать об изменении интерфейса WSDL). Эта опция предупреждает вас в случае, если внесенные в код изменения влекут изменения в файле WSDL. Это пригодится, если вы хотите, чтобы файл WSDL оставался неизменным. Однако если эта опция включена, вы не сможете сохранить Web-сервис с измененным файлом WSDL.
• PortType class (обязательное). Имя класса, используемого в качестве интерфейса Web-сервиса. Иными словами, пользователи смогут использовать через Web-сервис публичные методы этого класса.

Вторая вкладка в окне - Security (безопасность)(см. рисунок 4).

Поля на вкладке Security следующие:

• Run as web user (Запускать как web-пользователя). Эта опция позволяет коду Web-сервиса работать с настройками безопасности пользователя, использующего сервис (по умолчанию она запускается с настройками безопасности ID, которое в последний раз подписывало Web-сервис в Lotus Domino Designer).
• Run on behalf of (Запускать как...). В этом поле вы можете указать ID того, под чьими настройками безопасности будет работать Web-сервис, вместо настроек безопасности того, кто последний его подписывал в Lotus Domino Designer.
• Allow remote debugging (Разрешить удаленную отладку). Эта опция разрешает удаленную отладку Web-сервиса (информацию об удаленной отладке вы найдете в справке Lotus Domino Designer по теме "Using the Remote Debugger" (использование удаленного отладчика)).
• Profile this web service (Создать профиль Web-сервиса). Эта опция заставляет Web-сервис создать при работе профильную информацию (информацию о профиле вы найдете в справке Lotus Domino Designer по теме "Profiling agents and Web services" (профилирование агентов и Web-сервисов)).
• Set runtime security level (Установить уровень рабочей безопасности). Установка 1 позволяет большинству операций LotusScript и Java нормально работать; установка 2 или 3 необходима для таких операций, как чтение/запись, создание объектов COM или выполнения сетевых операций (за дополнительной информацией обращайтесь к справке Lotus Domino Designer по теме "Restricted LotusScript and Java agent operations" (ограниченные операции LotusScript и Java)).
• Default access for this web service (Доступ по умолчанию этому сервису). Эта опция позволяет вам контролировать, какие пользователи имеют право доступа к Web-сервису, в дополнение к контролю со стороны ACL базы данных (если анонимные пользователи не имеют прав использовать Web-сервис, то при попытке подключиться они получают в ответ ошибки 401 Access Denied или 404 Not Found).
• Allow Public Access users to use this web service (Разрешить пользователям с публичным уровнем доступа пользоваться сервисом). Эта опция позволяет пользователям с уровнем доступа в ACL "Read Public Documents" использовать Web-сервис, и полезна на тот случай, если вы не хотите раздавать направо и налево права для полного чтения (или выше).

Третьей вкладкой окна является Options (опции) (см. рисунок 5).

На вкладке Options есть такие поля:

• Programming model (Модель программирования). Можно выбрать RPC или Message (вы почти всегда будете выбирать RPC).
• SOAP message format (Формат сообщения SOAP). В этом поле вы выбираете формат сообщений SOAP для вашего сервиса (подробнее о форматах вы узнаете в следующем разделе). В Lotus Domino V7.0 по умолчанию стоит формат RPC/encoded.
• Include operation name in SOAP action (Включать имя операции в действия SOAP). Эта опция требует, чтобы во входящих запросах в заголовок действий SOAP включалось имя операции (почти не используется).
• Port type name (Имя типа порта). По умолчанию значение этого поля то же, что и указано в поле PortType class на вкладке Basics (однако вы можете использовать любое имя). Используется при создании файла WSDL.
• Service element name (Имя сервисного элемента). По умолчанию, значение этого поля такое же, как и имя типа порта с добавлением слова Service (однако вы можете поменять его на любое другое). Используется при создании файла WSDL.
• Service port name (Имя сервисного порта). По умолчанию значение этого поля Domino, вы же можете сменить его на любое другое. Используется при создании файла WSDL.

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

Форматы сообщений SOAP

В окне настроек можно выбрать разные форматы сообщений SOAP, и не всегда просто решить, какой использовать. В разных форматах создаются разные файлы WSDL, которые приводят к разным запросам и ответам SOAP.

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

Формат RPC/encoded лучше всего воспринимается старыми клиентскими технологиями для Web-сервисов, такими как Apache SOAP и MSSOAP. Doc/literal используется по умолчанию клиентами и серверами Microsoft .NET, последние несколько лет он становится популярным.

Выбирать формат сообщений вам следует с учетом использующих ваш сервис клиентов и тот формат, который им удобнее использовать. Если же вы не знаете, чем пользуются ваши клиенты, выбирайте хоть RPC/encoded, хоть Doc/literal.

Хорошее объяснение разницы форматов и того, как они влияют на структуру WSDL и сообщений SOAP вы найдете в часто цитируемой статье developerWorks, "Какой стиль WSDL мне использовать?."

В начало

Классы Web-сервисов, использующие простые типы данных

Давайте вернемся к написанию кода Web-сервиса. Вы знаете, что код LotusScript, отображаемый в качестве Web-сервиса, должен быть написан как класс. Виртуально любая функция или подпрограмма LotusScript в качестве метода класса со следующими ограничениями:

• Не используйте родные классы LotusScript (такие как NotesDatabase, NotesDocument, и т.д.) в качестве параметров или возвращаемых значений.
• Не используйте в качестве параметров или возвращаемых значений типы данных variants или currency.
• Не используйте списки или массивы в качестве параметров или возвращаемых значений (массивы использовать можно, однако ими надо пользоваться при помощи специальных типов данных, описание которых вы найдете в этой статье).
• Не используйте в качестве параметров или возвращаемых значений собственные типы данных.

Таким образом, в качестве параметров или возвращаемых значений в методах Web-сервисов вы можете использовать следующее:

• Простые типы данных (string, integer и т.д.)
• Определенные пользователем собственные классы
• Специальные классы, определенные в файле lsxsd.lss (включен в Lotus Notes/Domino V7.0 client и server)

Определенные пользователем классы используются как комплексные типы данных, к которым мы вернемся в следующей статье. Классы из файла lsxsd.lss (который находится в директории local Notes) очень полезны и помогают вам передавать строчные массивы, файлы и даты. Некоторые из этих классов мы обсудим в этой статье, некоторые в следующей.

Теперь давайте взглянем на примеры использования в ваших классах простых типов данных. Взгляните на этот класс:

                
Class DatabaseInfo
	Private session As NotesSession
	Private db As NotesDatabase
	
	Public Sub New ()
		Set session = New NotesSession
		Set db = session.CurrentDatabase
	End Sub
	
	Public Function GetDbName () As String
		GetDbName = db.Title
	End Function
	
	Public Sub UpdateFTIndex ()
		Call db.UpdateFTIndex(True)
	End Sub
	
	Public Function GetUserRoles (userName As String) As String
		GetUserRoles = Join(getRoles(userName), ",")
	End Function
	
	Private Function getRoles (userName As String) As Variant
		Dim acl As NotesACL
		Dim entry As NotesACLEntry
		Dim sep As String
		
		Set acl = db.ACL
		Set entry = acl.GetEntry(userName)
		
		If (entry Is Nothing) Then
			Dim returnArray(0) As String
			getRoles = returnArray
		Else
			getRoles = entry.Roles
		End If
	End Function
End Class

Код простой и последовательный, однако обратите внимание на следующие особенности разных методов:

• New (Новый). Метод New не обязателен и недоступен пользователям сервиса. Он используется для инициализации, если таковая нужна. Кроме того, если вы используете метод New, то он должен быть подпрограммой и не принимать никаких параметров.
• GetDbName. Метод GetDbName не принимает никаких параметров. Здесь все в порядке.
• UpdateFTIndex. Метод UpdateFTIndex не принимает параметры и не возвращает значений. Здесь тоже все в порядке.
• GetUserRoles. Метод GetUserRoles вызывает другой метод, который делает за него большую часть работы. Вы можете вызывать и другие функции и подпрограммы (за пределами класса), и даже классы, функции и подпрограммы из библиотек, перечисленных в Use. Это полезно не только потому, что позволяет делать код лаконичнее, но еще и потому что помогает отделить код Web-сервиса от прочего уже имеющегося в работе кода.
• getRoles. Метод getRoles объявлен как Private и использовать его могут только прочие методы класса, и не могут использовать клиенты сервиса. Объявление некоторых методов как Private позволяет скрывать код и логику внутри класса, не позволяя пользователю вызывать все это напрямую.

  Помните, что если в методе не указано, является ли он Public или Private, то он доступен как Public.

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

В начало

Возврат массивов

Вы могли заметить, что метод GetUserRoles перед возвращением преобразовал массив из строк, возвращенный методом getRoles в одну строку с разделителями. Это потому, что вы не можете из Web-сервиса вернуть массив LotusScript ни как массив, ни как переменную.

Однако вы можете вернуть массив, возвращая один из классов ARRAY_HOLDER из файла lsxsd.lss. Классы ARRAY_HOLDER (STRINGARRAY_HOLDER, INTEGERARRAY_HOLDER и т.д.) автоматически при возвращении преобразуются в дружественные к SOAP массивы.

В качестве примера вы можете добавить в секцию (Options) web-сервиса строку %INCLUDE "lsxsd.lss" и перезаписать метод GetUserRoles таким образом:

                
	Public Function GetUserRolesArray (userName As String) As STRINGARRAY_HOLDER
		Dim returnArray As New STRINGARRAY_HOLDER
		Dim roles As Variant
		Dim i As Integer
		
		roles = getRoles(userName)
		Redim returnArray.Value(Ubound(roles))
		For i = 0 To Ubound(roles)
			returnArray.Value(i) = roles(i)
		Next
		
		Set GetUserRolesArray = returnArray
	End Function

Когда это касается пользовательского клиента, метод GetUserRolesArray возвращает нормальный массив из строк вместо специального объекта STRINGARRAY_HOLDER. Это потому что Web-сервис Domino выполняет преобразование между STRINGARRAY_HOLDER и строковым массивом в тот момент, когда осуществляется доступ к сервису. Вам придется проделать немного лишней работы, добавляя элементы массива getRoles в элемент Value из STRINGARRAY_HOLDER (потому что нельзя напрямую установить в качестве элемента Value другой массив), однако это всего несколько строчек кода.

Разумеется, возвращать можно не только массивы строк. В файле lsxsd.lss есть классы INTEGERARRAY_HOLDER, LONGARRAY_HOLDER и прочие, с такими же функциями для других типов данных. За дополнительной информацией обращайтесь к справке Lotus Domino Designer или загляните в файл lsxsd.lss.

Кроме того, массивы можно возвращать в качестве частей сложных типов данных, эту технику мы разберем в следующей статье.

В начало

Возврат многих значений при помощи входящих-возвращаемых параметров.

Если вы хотите работать только с простыми типами данных, есть еще одна техника - входящие-возвращаемые параметры. Это параметры, через которые может передаваться входящее значение, и возвращаться исходящее. Взгляните, например, на этот класс:

                
Class InOutTest
	Public Sub AddOne (inout As INTEGER_HOLDER)
		inout.Value = inout.Value + 1
	End Sub
	
	Public Function SwapAndAdd (inout1 As INTEGER_HOLDER, _
	inout2 As INTEGER_HOLDER) As Integer
		SwapAndAdd = inout1.Value + inout2.Value
		inout1.Value = inout2.Value
		inout2.Value = SwapAndAdd - inout2.Value
	End Function
End Class

Первый метод (AddOne) принимает в качестве параметра целое число. Код метода добавляет к полученному значению единицу и, поскольку это INTEGER_HOLDER - возвращает новое значение в ответе SOAP.

Это особое свойство определенных в файле lsxsd.lss классов HOLDER. Они, когда используются в качестве параметров, становятся входящими-возвращаемыми параметрами запросов/ответов SOAP, и как получают, так и возвращают значения.

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

Обратите внимание на метод SwapAndAdd. Здесь два входящих-возвращаемых параметра, и сам метод возвращает целое число. Пользовательский клиент создает запрос SOAP, содержащий два параметра, и получает ответ SOAP с тремя значениями: два значения, отправленные в качестве параметров (видоизмененные методом), и результат.

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

В начало

Работа с датами и временем

В работе вам может пригодиться еще один простой тип данных - объект дата/время. Вот пример использования даты/времени в параметрах и возвращаемы объектах:

                
Class DateTester
	Public Function getCurrentTime () As XSD_DATETIME
		Dim dt As New NotesDateTime(Now)
		Set getCurrentTime = New XSD_DATETIME
		Call getCurrentTime.SetValueFromNotesDateTime(dt)
	End Function
 	
	Public Function getLocalDateFormat (xdt As XSD_DATETIME) As String
		Dim dt As NotesDateTime
		Set dt = xdt.GetValueAsNotesDateTime()
		getLocalDateFormat = dt.LocalTime
	End Function
End Class

И опять нам помогают классы из lsxsd.lss. Вы можете просто получать и возвращать переменные типа XSD_DATETIME (которые преобразуются в элемент SOAP dateTime) и преобразовывать их в объект NotesDateTime или из него.

Однако будьте внимательны - серверы и клиенты могут добавить, а могут и не добавлять смещение времени в зависимости от часового пояса в элемент SOAP dateTime. В recent W3C Note обсуждаются некоторые аспекты этой проблемы. Как всегда, поначалу вам стоит проверять клиентов ваших Web-сервисов.

В начало

Тестирование вашего Web-сервиса

Тестирование Web-сервисов на локальных базах данных Если у вас есть локальная копия базы данных с Web-сервисом, и вы ее хотите протестировать, убедитесь что в фоновом режиме работает сервис Notes HTTP. Проще всего это сделать так: Откройте базу данных в Lotus Domino Designer. Выберите в базе данных Form или View. Выберите Design - Preview в Web Browser - Default Browser и подождите, пока форма или окно появятся в браузере. Увидев форму или окно в браузере, вы можете закрывать браузер и приступать к тестированию. Сервис HTTP будет работать в фоновом режиме до тех пор, пока вы полностью не закроете клиент Notes. Некоторые файрволлы блокируют операции локальных сервисов HTTP, поэтому вам, возможно, придется еще и настроить файрволл.

Написав Web-сервис, вы хотите его проверить. Для получения доступа к файлу WSDL вашего сервиса вам придется использовать полный путь URL вашего сервиса с командой ?WSDL в конце URL.

Например, для базы данных WSTest.nsf на сервере с DNS mydomino.example.com с web-сервисом под названием MyNewWebService вы используете следующий URL:

http://mydomino.example.com/WSTest.nsf/MyNewWebService?WSDL

Есть несколько доступных инструментов для тестирования Web-сервисов, как бесплатных, так и коммерческих, и о них можно написать длинную статью или руководство.

Ниже приведены несколько бесплатных инструментов с краткими описаниями для тестирования и обращения к Web-сервисам. Возможность разобраться в них подробнее мы оставляем читателю.

soapUI

Самый простой в использовании инструмент для тестирования Web-сервисов - это soapUI, доступный на сайте soapUI . SoapUI - бесплатная программа на Java, которая может работать на разных операционных системах. Вот как с ее помощью тестировать Web-сервис:

1. Убедитесь что у вас установлена Java 1.5 или новее.
2. Загрузите программу soapUI, разархивируйте ее.
3. Из директории /bin разархивированной программы запустите или soapui.bat (на машинах с ОС Windows) или soapui.sh (на остальных ОС).
4. Выберите File - New WSDL Project и введите имя проекта, когда попросят.
5. Нажмите правой кнопкой на новом проекте на панели навигации слева и выберите "Add WSDL From URL".
6. Введите URL тестируемого сервиса (например, http://localhost/DWSTest.nsf/EchoTestService?WSDL) и нажмите Yes, когда вам предложат создать запросы по умолчанию для всех операций.
7. Теперь вы сможете открыть проект слева и увидеть имя каждого доступного метода Web-сервиса. Дважды нажав на Request рядом с именем метода, вы увидите сконструированный запрос SOAP, который может быть отправлен для проверки (см. рисунок 6).
   
   Рисунок 6. Интерфейс soapUI
   
   
   
8. Для сервиса EchoTest на рисунке 6 у нас создан простой запрос SOAP. Желая протестировать сервис, введите текст в окошко <TXT> пакета с запросом и нажмите на кнопку с зеленой стрелкой прямо над текстом запроса SOAP. К сервису будет отправлен запрос, и на панели справа будет отображен текст полученного ответа SOAP.

SoapUI позволяет вам строить тестовые оболочки для комплексного тестирования Web-сервисов. Таким образом, вы можете создать набор тестов, и при внесении изменений в сервис запустить заранее созданные тесты, чтобы убедиться, что все по-прежнему правильно работает.

Однако вам придется работать прямо в запросах и ответах XML SOAP. Если вы хорошо знакомы с XML и SOAP, то это не проблема - самое тяжелое, написание запросов SOAP, уже сделано за вас, и вы видите уже готовые ответы. Однако если вы предпочитаете работать абстрагируясь от этого - например, используя API или вызовы функций - то этот инструмент покажется вам слишком низкоуровневым.

Eclipse и Web Tools Platform (WTP)

Если у вас установлен Eclipse, то в нем есть хороший пакет под названием Web Tools Platform (WTP) с высокоуровневым интерфейсом для тестирования Web-сервисов. Вместо работы с запросами SOAP WTP для каждого из методов вашего сервиса создает форму, в которую можно просто внести значения и отправить запрос.

Вот основные шаги при установке и использовании WTP:

1. Загрузить и установить платформу Eclipse.
2. Установить компоненты WTP. Для версий Eclipse старше 3.2, смотрите инструкции по установке WTP. Для Eclipse 3.2 или для более поздней версии, эти инструкции являются частью инструментального набора Callisto в секции "Разработка Web и J2EE ". Сделайте следующее:
   1. Выберите Help - Software Updates - Find and Install.
   2. На следующем экране выберите "Search for new features to install" и нажмите Next.
   3. Убедитесь, что выбрана опция Callisto Discovery Site и нажмите Next.
   4. Следом за секцией Callisto Discovery Site на перечне доступных для установки пакетов выберите "Web and J2EE Development" (все элементы в нем выберутся автоматически). После чего нажмите кнопку Select Required, чтобы отметить все остальные необходимые компоненты, и нажмите Next для начала установки (см. рисунок 7). Установка займет несколько минут.
   
   
   Рисунок 7. Установка пакета WST в Eclipse
   
   
   
3. После окончания установки перезагрузите Eclipse. На главной странице Workbench выберите Run - Launch the Web Services Explorer.
4. В окне Web Services Explorer нажмите кнопку WSDL Page, и WSDL Main будет добавлена на панель навигации (см. рисунок 8).
   
   Рисунок 8. WSDL Explorer в WST
   
   
   
5. Путь WSDL вы можете ввести на панели Actions. Введите URL тестируемого сервиса (например, http://localhost/DWSTest.nsf/EchoTestService?WSDL) и нажмите кнопку Go.
6. Когда будет найден файл WSDL, под элементом WSDL Main на панели навигации появится древовидная структура всех методов вашего сервиса.
7. Нажмите дважды на любом из методов дерева WSDL, что вызовет на панели Actions форму, в которую вы сможете ввести значения для каждого из параметров и отправить их Web-сервису. Ответ отображается на панели Status внизу (см. рисунок 9).
   
   Рисунок 9. Запрос SOAP в WST
   
   
   
8. Если вы хотите увидеть код XML SOAP отправленных и полученных сообщений, нажмите на ссылку Source на панели Status.

Хотя установить Eclipse WTP сложнее, чем soapUI, интерфейс у него намного удобнее (формы вместо запросов). Если вам нужны детали низкого уровня, вы по-прежнему можете просмотреть сообщения, однако некоторые люди предпочитают работать не с низкоуровневыми данными, а с формами.

Инструментарий MSSOAP

Многие программисты LotusScript под Windows для создания вызовов к Web-сервисам с успехом используют инструментарий MSSOAP. Хотя этот инструмент уже не поддерживается и не обновляется Microsoft (его вытеснил Microsoft .NET framework), это привычная для многих технология, и ее стоит упомянуть.

MSSOAP - это файл DLL, который можно загрузить с сайта Microsoft, он может быть установлен вместе с Windows. Вы можете вызывать DLL как объекты COM, используя код LotusScript похожий на этот:

                
Dim Client As Variant
Set Client = CreateObject("MSSOAP.SoapClient")
Call Client.MSSoapInit("http://localhost/DWSTest.nsf/EchoTestService?WSDL")
Print "Echo said " & Client.Echo("echo")

Разумеется, вам понадобится знание методов Web-сервиса, используемых параметров и типов данных. Если вы вызываете другой Web-сервис, вам придется либо читать и интерпретировать файл WSDL вручную (а это бывает очень неудобно) или использовать инструмент вроде soapUI или Eclipse WTP, которые преобразуют все для вас.

К сожалению, на машинах с Windows обычно находится версия MSSOAP 1.x, которая нормально работает только с RPC/Encoded Web-сервисами, использующими простые типы данных в качестве параметров. Сложные типы данных обычно возвращаются через объекты IXMLDOMNodeList, однако отправка сложных типов данных в качестве параметров требует создания новых объектов IXMLDOMNodeList, что может быть очень непросто. Кроме того, MSSOAP 1.x не способно понять Web-сервисы, использующие перечисления (которые мы рассмотрим в следующей статье).

Если вы контролируете использующие библиотеку MSSOAP сервера, то вы можете загрузить и установить SOAP Toolkit version 3.0, который позволит вам работать с более широким набором Web-сервисов. После установки пакета вы можете изменить вышеуказанный код с CreateObject("MSSOAP.SoapClient") на CreateObject("MSSOAP.SoapClient30") и использовать новую версию библиотеки. В таблице 1 перечислены различия между двумя разными версиями.

MSSOAP позволяет отправлять динамические запросы Web-сервисам (это иногда удобно), и есть множество примеров использования MSSOAP (на LotusScript и Visual Basic, который легко преобразуется в LotusScript), так что если вы обращаетесь к Web-сервису с машины под Windows, это неплохой выбор.

Apache Axis

В среде Lotus Notes фреймворк Apache Axis - еще один неплохой способ работы с Web-сервисами. Этот хорошо продуманный пакет на Java, разработанный для создания, публикации и использования Web-сервисами, используется уже много лет на разных платформах. Фактически именно на базе версии Axis Lotus Domino V7 осуществляет публикацию Web-сервисов!

Используя Axis в качестве клиента для вызова Web-сервисов, вы обычно используете командную строку Java (поставляется вместе с Axis), которая называется wsdl2java, для создания программных заглушек для вызова Web-сервисов, основанных на сервисных файлах WSDL. Эти программные заглушки - классы Java, использующиеся в качестве оболочек для сложного кода, необходимого для доступа к Web-сервису и его использования, а все что требуется от вас - это вызвать эти классы для вызова метода и получения ответа. Для вас остается только чистовая работа вроде генерации программных заглушек для вызываемого Web-сервиса, а кроме того, чуть позже вам же приходится разбираться с запутанными результатами (формат сообщений SOAP, пространства имен, анализ ответов и т.д.).

Если вы хотите писать код для вызова сервиса через Lotus Notes в Apache Axis, начинать стоит отсюда: статья developerWorks, "Использование Web-сервиса от агента Lotus Domino Java,", и свободно распостраняющаяся заполненная база данных Stubby, доступная на сайте OpenNTF . Вот пример того, как вы можете с помощью Stubby создавать код Axis, обращающийся к нашему сервису EchoTest:

1. Загрузить базу данных Stubby с OpenNTF.org, и открыть ее в клиенте Lotus Notes V7.
2. Чтобы создать новый документ в базе данных, нажмите кнопку Create New Doc и введите URL вашего сервиса EchoTest (http://localhost/DWSTest.nsf/EchoTestService?WSDL) в форме в поле WSDL File (см. рисунок 10).
   
   Рисунок 10. Документ базы данных Stubby
   
   
   
3. Для создания программных заглушек Axis нажмите в форме на кнопке Generate Stub Files. Тут же будут созданы и файлы JAR, содержащие все уже скомпилированные и готовые к использованию программные заглушки. Все созданные файлы присоединяются к полям на вкладке generated files документа Stubby.
4. Заберите файл JAR из вкладки generated files (в данном случае - EchoTestService.jar) в вашу локальную файловую систему.
5. С помощью Lotus Domino Designer V7 создайте в своей базе данных нового агента Java и присоедините сюда с помощью кнопки Edit Project полученный ранее файл JAR.
6. Из вкладки с примером в документе Stubby скопируйте сгенерированный код агента и вставьте его в агента. Еще вам придется добавить в метод Echo строку, вызывающую Web-сервис. Получившийся в результате код агента выглядит таким образом (комментарии и пустые строки удалены):
   
   Листинг 7. Использование программных заглушек Apache Axis в агенте Lotus Notes Java
   

   import lotus.domino.*; import DefaultNamespace.*; public class JavaAgent extends AgentBase { public void NotesMain() { try { EchoTestServiceLocator locator = new EchoTestServiceLocator(); EchoTest service = locator.getDomino(); System.out.println("Echo said " + service.ECHO("echo")); } catch(Exception e) { e.printStackTrace(); } } }

   
   
7. Теперь для доступа к Web-сервису вы можете запустить агента на любом клиенте или сервере Lotus Notes/Domino V7.

В базе данных Stubby есть также примеры вызова Web-сервиса с помощью LS2J для тех программистов, которым более привычен LotusScript. Больше информации о LS2J вы найдете в справке Lotus Domino Designer.

PHP nuSOAP

При тестировании Web-сервиса можно использовать еще и такую интересную вещь, как библиотеку PHP nuSOAP. С ее помощью не только легко пользоваться Web-сервисом, а еще и легко отображать информацию о вашем Web-сервисе Domino.

Например, если вы имеете доступ к серверу PHP (или у вас установлен PHP локально, такой как сервер WAMP), вы можете скопировать в него библиотеку nuSOAP и создать следующую страницу:

                
<?php
$wsdlURL = $_POST["wsdlurl"];

if ($wsdlURL) {
	// Это надо изменить - убедитесь, что путь ниже прописан правильно
	require_once('../nusoap/lib/nusoap.php');
	
	$wsdlURL = urldecode($wsdlURL);
   	$wsdl = new wsdl($wsdlURL);
	
	$wsdlerror = $wsdl->getError();
	if ($wsdlerror) {
		echo 'There was an error getting the WSDL file at ' .
		htmlspecialchars($wsdlURL) . ':<br>' . $wsdlerror;
	} else {
		echo $wsdl->WebDescription();
	}
} else {
	$htmlPage = '<html>
<head>
<title>nuSoap WSDL Documentation Generator</title>
</head>
<body>
<h3>nuSoap WSDL Documentation Generator</h3>
This page uses the 
<a href="http://sourceforge.net/projects/nusoap/">PHP nuSOAP</a> 
library to generate a nice description of a given WSDL file
and all of its available methods.<p>
<form method="post" action="' . $_SERVER['PHP_SELF'] . '">
Please enter the URL of your WSDL file below:<br>
<input type="text" size="75" name="wsdlurl"><p>
<input type="submit" value="submit" name="submit"><br />
</form>
</body>
</html>';
	
	echo $htmlPage;
}
?>

Если вы сохраните эту страницу на сервере PHP и откроете ее в браузере, у вас запросят адрес файла WSDL. Введя URL и нажав кнопку Submit, вы увидите страницу, описывающую все публичные методы вашего сервиса (см. рисунок 11).

ЗАМЕЧАНИЕ: Если Web-сервис находится в базе данных вашей локальной машины, эту страницу вам надо запустить из вашей локальной установки сервера PHP (опять-таки, сервер WAMP очень удобен при установке и использовании), и необходимо убедиться, что локальный сервер PHP не использует порт 80 (и не мешает работе локального сервиса Notes HTTP).

SoapLog для отслеживания сообщений Domino SOAP

Еще один стоящий инструмент - это SoapLog DSAPI Filter. Это файл DLL и база данных Notes, которые вы можете скопировать на свой сервер, и которые записывают все сообщения, отправленные сервисам на вашем сервере. На момент написания статьи эта DLL работает только под Windows, и ее бесплатная версия не поддерживается.

Установить SoapLog вы можете таким образом:

1. Загрузить SoapLog и разархивировать загруженный файл на вашем компьютере.
2. Скопировать soaplog.dll в программный каталог Notes вашего сервера Domino.
3. Скопировать базу данных SoapLog.nsf в каталог с данными вашего сервера Domino, и правильно настроить ACL (убедиться, что сервер может сюда записывать).
4. Добавить переменную SOAPLOG_DBNAME в серверный файл Notes.ini, указывающую на базу данных SoapLog.nsf. Например, если база данных SoapLog.nsf находится в корневом каталоге с данными, добавьте в файл Notes.ini следующую строку:

   SOAPLOG_DBNAME=SoapLog.nsf

   
   
5. Откройте серверный документ вашего сервера в Domino Directory. На вкладке Internet Protocols - HTTP справа на середине страницы вы увидите секцию DSAPI. Добавьте в это поле запись для soaplog.dll (если в этом поле уже есть запись, то перед добавлением записи soaplog.dll добавьте новую строку).
6. Перезагрузите задачу HTTP на сервере Domino. Вы увидите сообщение о том, что SoapLog DSAPI тоже загрузился.

После загрузки фильтра все запросы в сообщениях SOAP к вашему сервису будут сохраняться в новых документах в базе данных SoapLog.nsf (см. рисунки 12 и 13).

Есть еще несколько дополнительных параметров в Notes.ini, с помощью которых вы можете перенастроить создание логов. Больше информации об этом вы найдете в документе Using This Database в базе данных SoapLog.nsf.

В начало

Заключение

В этой статье вы увидели, как можно создать и протестировать простой Web-сервис Lotus Domino V7. На платформе Domino V7 очень легко создавать и публиковать Web-сервисы, при помощи кода, очень похожего на тот, который используется при написании агентов LotusScript или Java. Хотя Lotus Notes и не предназначен для тестирования и запроса Web-сервисов, в нем есть неплохие возможности для написания клиентов Web-сервисов, способных взаимодействовать с вашими Web-сервисами.

Немаловажно то, что дургие использующие Web-сервисы системы (не Domino) способны использовать написанные вами сервисы, благодаря чему Lotus Domino занимает немаловажное место в среде SOA.

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

В начало

Загрузка

	Информация о методах загрузки

Ресурсы

• Оригинал статьи "Practical Web services in IBM Lotus Domino V7: Writing and testing simple Web services".(EN)
  
  
• Статья по Lotus на developerWorks "Практическое использование Web-сервисов в IBM Lotus Domino 7: Что такое Web-сервисы и почему они важны?"
  
  
• Статья по Lotus на developerWorks "Web-сервисы Lotus Notes/Domino 7"
  
  
• Руководство developerWorks "Быстрое создание Web-сервисов Domino: новые функции Web-сервисов в Domino 7 ускоряют разработку"
  
  
• Статья по Lotus на developerWorks "Использование Web-сервиса от агента Lotus Domino Java"(EN)
  
  

• Загрузите soapUI для тестирования ваших Web-сервисов.(EN)
  
  
• Загрузите Eclipse и Web Tools Platform.(EN)
  
  
• Загрузите последнюю версию инструментария MSSOAP для вызова Web-сервисов посредством LotusScript.(EN)
  
  
• Загрузите базу данных Stubby для создания программных заглушек Apache Axis, используемых с агентами Lotus Notes Java.(EN)
  
  
• Используйте PHP nuSOAP для вызова Web-сервисов из страниц PHP на сервере.(EN)
  
  
• Если для тестирования вам нужна локальная версия PHP, загрузите сервер WAMP.(EN)
  
  

• Примите участие в обсуждении материала на форуме.
  
  
• Посетите блоги developerWorks и присоединитесь к сообществу developerWorks.(EN)

Об авторе

		Джулиан Робиччо (Julian Robichaux) работает разработчиком ПО, он профессиональный программист, специализирующийся в области IBM Lotus Notes и разработчик Java. Его можно нанять для работы как в небольших, так и в крупных проектах в области разработки, проектирования и обучения. В свободное время он пишет свой личный сайт http://www.nsftools.com. Его семья не понимает, зачем он везде таскает за собой ноутбук. Он, впрочем, тоже.

Выскажите мнение об этой странице

Пожалуйста, найдите минутку и заполните форму, чтобы повысить уровень сервиса. Помогла ли данная информация достичь Вашей цели? Да Нет Не знаю   Пожалуйста, напишите комментарий, чтобы мы могли улучшить данную страницу:   Насколько полезна эта информация? (1 = Бесполезна, 5 = Очень полезна) 1 2 3 4 5

В начало