Использование Web-сервисов в Cache

Web-сервис представляет собой набор логически связанных функций (методов), которые могут быть программно вызваны через Internet (или Intranet). Таким образом, программы, написанные на различных языках программирования, функционирующие на различных серверах под управлением различных платформ могут обращаться к какой-нибудь программе, работающей на другом сервере (т.е. к Web-сервису), и использовать ответ, полученный от нее на своем Web-сайте, или приложении.

Web-сервисы представляют собой особый вид Web-приложений для создания уровня бизнес-логики и связи разнородных приложений на основе использования общих стандартов, а также открытых протоколов обмена и передачи данных. В основе технологии Web-сервисов лежит язык XML (eXtensible Markup Language) – расширяемый язык разметки. Обмен данными между приложениями осуществляется с помощью стандартного протокола HTTP и некоторых других Internet-протоколов.

Например, если вам необходимо встроить в свое приложение переводчик слов на различные иностранные языки (или прогноз погоды, гороскоп и т.п.), вы можете решать задачу различными способами. Можете, например, самостоятельно реализовать такую функциональность, а можете воспользоваться услугами Web-сервиса, к которому Ваше приложение будет обращаться через Internet. Передавая такому Web-сервису запрос с параметрами, например, слово для перевода и интересующий иностранный язык, получаете ответ, в котором будет содержаться результат выполнения вашего запроса. Далее вам остается только “красиво” отобразить этот ответ в своем приложении. При этом вам совершенно не обязательно знать детали внутренней реализации используемого Web-сервиса (под управлением какой платформы функционирует, на каком языке программирования написан и т.п.), достаточно только знать какой метод вам нужен и формат вызова этого метода.

Можно выделить следующие варианты использования Web-сервисов:

В рамках данной статьи будут рассмотрены основные принципы функционирования Web-сервисов (Web-служб). А также рассмотрена возможность использования технологии Web-служб в Cache. Cache может обращаться к внешним Web-службам, опубликованным в сети Internet/Intranet, отправлять запросы, получать результаты, т.е. являться клиентом Web-служб. При этом, приложение на Cache может предоставлять определенную функциональность (набор методов), доступную внешним программам через Internet/Intranet, т.е. являться сервером Web-служб. Далее будут рассмотрены оба этих механизма.

Рисунок 1 иллюстрирует общие принципы работы механизма Web-сервисов.

Итак, есть определенный сервер Web-сервисов, реализующий некоторую функциональность (содержащий набор методов) и доступный в сети Internet/Intranet.

Для описания методов, опубликованных на данном сервере, а также формата их вызова используется специальный язык WSDL (Web Services Description Language). В основе языка WSDL лежит XML. Каждому серверу Web-служб соответствует свой собственный WSDL-документ, на основании которого клиент формирует запросы к данному сервису.

Клиент (любой компьютер в сети) формирует запрос и отправляет его серверу Web-служб. Для передачи запросов используется SOAP-протокол (Simple Object Access Protocol) – простой протокол доступа к объектам. Сообщение SOAP является обычным XML-документом, следовательно, не зависит ни от языка, ни от платформы.

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

В основе механизма Web-сервисов лежат три основные понятия: XML (eXtensible Markup Language), WSDL (Web Services Description Language) и SOAP (Simple Object Access Protocol). Рассмотрим их основные характеристики.

XML (eXtensible Markup Language)

XML – это eXtensible Markup Language, в переводе “расширяемый язык разметки”. XML создан для описания данных и фокусируется на том, что именно эти данные из себя представляют.

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

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

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

XML можно считать неким промежуточным звеном между форматом представления данных, предназначенным для восприятия человеком (например, текстовым документом), и неким бинарным кодом, используемым для представления встроенных типов данных языков программирования.

Ниже представлен пример записки (note) от Алексея к Наталье, сохраненной в виде XML-документа. У записки есть заголовок (heading) и содержательная часть (body). Кроме того, в ней содержится информация об отправителе (from) и получателе (to). Такой XML-документ просто структурирует определенную информацию (данные упакованы в XML-теги) и больше ничего не делает. Для того, чтобы такую записку отправить, получить или “красиво” отобразить на экране нужно написать специальное программное обеспечение.

<?xml version="1.0"?>
<note>
  <to>Алексей</to>
  <from>Наталья</from>
  <heading>Напоминание</heading>
  <body>Истекает срок арендной платы!</body>
</note>

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

WSDL (Web Services Description Language)

WSDL расшифровывается как Язык Описания Web-сервисов (Web Services Description Language).

Документ WSDL является XML-документом, описывающим Web-сервис, т.е. содержит набор выражений, определяющих Web-сервис. Он определяет расположение сервиса и операции (или методы), предоставляемые им, а также формат их вызова. На основании WSDL-документа клиентом осуществляется выбор необходимого метода, из предоставленных сервером Web-служб, и формируются запросы к данному Web-сервису.

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

<definitions>
<types>
   Описание типов данных, используемых Web-сервисом.
</types>
<message>
   Описание сообщений, используемых Web-сервисом. 
</message>
<portType>
   Описание операций (методов), предоставляемых Web-сервисом 
</portType>
<binding>
   Описание протоколов связи, используемых Web-сервисом
</binding>
</definitions>

WSDL-документ может также содержать и некоторые другие элементы.

Ниже приведен пример WSDL-документа, описывающего Web-сервис Arithmetic, предоставляющий всего одну операцию Sum (сложение двух целых чисел).

// Описание типов данных аргументов метода и возвращаемого

// Методу Sum передаются два аргумента val1 и val2 с

// Описание типа данных возвращаемого методом значения

// С входящим сообщением ассоциирован тип данных Sum

// С исходящим сообщением ассоциирован тип данных SumResponse

// Описание операций (методов), предоставляемых Web-сервисом

// Данный Web-сервис предоставляет операцию Sum

// Определение формата сообщения и деталей протокола для

// Определяет имя сервера Web-служб, позволяет объединить внутри

// себя несколько портов (наборов методов), определяет

SOAP (Simple Object Access Protocol)

SOAP – это основанный на XML протокол, который позволяет взаимодействовать различным приложениям на основе стандарта HTTP.

SOAP расшифровывается как “простой протокол доступа к объектам” (Simple Object Access Protocol) и предназначен для коммуникации (передачи информации) между удаленными объектами. Использование HTTP является наиболее удобным способом коммуникации между приложениями, поскольку протокол HTTP поддерживается всеми Web-браузерами и серверами. SOAP представляет собой способ коммуникации между приложениями на базе протокола HTTP и некоторых других Internet-протоколов, а использование XML в качестве основы SOAP позволяет ему работать под управлением различных операционных систем, на основе различных технологий и языков программирования.

Таким образом, протокол SOAP позволяет обмениваться сообщениями между клиентом и сервером. Сообщение SOAP является обычным XML-документом. Этот документ состоит из следующих XML-элементов:

Сообщения между сервером Web-служб и клиентом пакуются в SOAP-конверты (SOAP envelopes). Сообщения содержат либо запрос на осуществление какого-либо действия, либо ответ - результат выполнения этого действия. Конверт и его содержимое закодировано языком XML. Ниже приведен простой пример SOAP-запроса GetTranslation, который отправляется через HTTP к Web-сервису. Здесь запрашивается перевод слова помидор с русского языка на английский.

<soap:Envelope>
<soap:Body>
<xmlns:m="http://www.somesite.org/translation" /> 
  <m:GetTranslation>
    <m:Word>помидор</m:Word>
    <m:Language>RussianTOEnglish</m:Language>
 </m:GetTranslation>
</soap:Body>
</soap:Envelope>

Также приведен пример SOAP-ответа на данный запрос.

<soap:Envelope>
<soap:Body>
<xmlns:m="http://www.somesite.org/translation" />
  <m:GetTranslationResponse>
    <m:Translation>tomato</m:Translation>
 </m:GetTranslationResponse>
</soap:Body>
</soap:Envelope>

Элемент <m:GetTranslation> в запросе поменялся на элемент <m:GetTranslationResponse> в ответе на запрос. В этом элементе содержится только один элемент <m:Translation>, значение которого и обозначает запрашиваемый перевод слова помидор с русского языка на английский. Таким образом, с помощью SOAP мы сформировали запрос в виде XML, передали его серверу Web-служб и получили определенного вида ответ на языке XML. При этом, наша программа должна была только сформировать запрос и передать его серверу, никаких обращений, например, к БД наша программа не производила, а получила сразу готовый, структурированный специальным образом, результат.

Cache и Web-службы

Теперь перейдем непосредственно к применению технологии Web-сервисов в Cache. Как упоминалось ранее, Cache может являться клиентом Web-служб, т.е. обращаться к внешним по отношению к Cache сервисам. Также Cache может являться и сервером Web-служб, т.е. предоставлять сервисы, которые будут доступны клиентским приложениям по протоколу SOAP. Для передачи сообщений по протоколу SOAP используется CSP-шлюз.

Реализация клиента и сервера Web-служб в Cache построена с использованием объектной технологии. Каждому клиенту (серверу) Web-служб в Cache соответствует специальный класс. Этот класс может содержать несколько методов, обозначенных ключевым словом WebMethod. Каждой операции, предоставляемой Web-сервисом, соответствует свой собственный WebMethod. Таким образом, работа с классами, соответствующими клиенту и серверу Web-служб в Cache, аналогична работе с остальными классами Cache.

Cache как клиент Web-служб

Клиент Web-служб в Cache представляет собой класс, наследуемый от системного класса %SOAP.WebClient и содержащий набор методов, отмеченных ключевым словом WebMethod. Каждый такой метод соответствует определенному методу Web-сервиса на удаленной машине.

Для создания SOAP-клиента в Cache встроен специальный мастер. Мастер доступен из меню Cache Studio Инструменты->Расширения->1 SOAP Client Wizard. На первом шаге мастера указывается URL-адрес WSDL-документа соответствующего выбранному Web-сервису. На основании WSDL-документа мастер создает класс с необходимыми Web-методами, а также автоматически устанавливает значения параметров, определяющих имя удаленного Web-сервиса, его расположение и пространство имен. Также может быть автоматически сгенерирован дополнительный класс (классы), если, например, при вызове метода Web-сервиса необходимо передавать параметры определенного формата (например, строку определенного вида или значения из некоторого набора).

Ниже приведен пример класса, созданного мастером на основании WSDL-документа для Web-сервиса Arithmetic, предоставляющего только одну операцию Sum, которая выполняет сложение двух целых чисел.

Class Arithmetic.ArithmeticSoap Extends %SOAP.WebClient
{
  /// URL-адрес для доступа к Web-сервису.
  Parameter LOCATION = "http://MASHA:1972/csp/www/Web.Arithmetic.cls";

  /// Пространство имен Web-сервиса
  Parameter NAMESPACE = "http://tempuri.org";

  /// Имя сервиса
  Parameter SERVICENAME = "Arithmetic";

  /// Метод, обращение к которому вызывает выполнение 
  /// соответствующего метода Web-сервиса
  Method Sum(val1 As %Integer, val2 As %Integer) As %Integer [ Final, 
    ProcedureBlock = 1, 
    SoapBindingStyle = document, 
    SoapBodyUse = literal, WebMethod ]
  {
    Quit ..WebMethod("Sum").Invoke(
      ##this,"http://tempuri.org/Web.Arithmetic.Sum",.val1,.val2)
  }
}

Вы можете создавать экземпляры созданного класса и вызывать методы класса-клиента. Например:

WWW>Set client = ##class(Arithmetic.ArithmeticSoap).%New()
 
WWW>Write client
1@Arithmetic.ArithmeticSoap
WWW>Set result = client.Sum(1,-3)
 
WWW>Write result
-2

Cache как сервер Web-сервисов

Сервер Web-сервисов в Cache представляет собой класс, наследуемый от системного класса %SOAP.WebService, и содержащий набор методов, отмеченных ключевым словом WebMethod. Каждый такой метод соответствует определенному методу Web-сервиса. Целесообразно для каждого набора логически связанных методов создавать отдельный Web-сервис (соответствующий класс).

Поскольку SOAP-протокол является “stateless”, т.е. не поддерживает состояния и не позволяет вызывать методы объекта, то WebMethod’ами могут быть только методы класса. Тем не менее, внутри WebMethod’а вы можете выполнять различные действия, в том числе создавать объекты, обращаться к БД, в том числе удаленной и т.д.

Для каждого класса, унаследованного от системного класса %SOAP.WebService, Cache автоматически создает WSDL-документ, определяющий список доступных внешним программам методов и формат их вызова.

Рисунок 2 иллюстрирует механизм взаимодействия Web-сервиса Cache и клиента.

Клиент запрашивает WSDL-документ с Web-сервера, который, в свою очередь, запрашивает этот документ у сервера Cache. Используя информацию, предоставленную WSDL-документом, клиент вызывает нужный ему метод. Для вызова метода клиент создает XML-сообщение (SOAP-запрос), в котором указывается вызываемый метод и переданные этому методу параметры. Далее это сообщение отправляется серверу Cache по протоколу HTTP.

Сначала запрос передается на Web-сервер, затем его перехватывает CSP-шлюз и перенаправляет на сервер Cache, где SOAP-запрос конвертируется в специальный вызов метода Web-сервиса. Выполняется вызванный метод. В качестве значения, возвращаемого методом, может быть некоторое простое значение (например, число или строка символов) или набор объектов, представленный в виде XML. Для того, чтобы метод Web-сервиса в качестве возвращаемого значения, возвращал экземпляр какого-либо класса, соответствующий класс должен быть унаследован от класса %XML.Adaptor. Результат работы Web-метода возвращается в виде XML-документа.

Для создания SOAP-сервера в Cache создайте класс Cache, унаследованный от системного класса %SOAP.WebService. Обязательно переопределите значение параметра SERVICENAME. Для каждой операции, предоставляемой Web-сервисом, т.е. метода, который будет доступен внешним приложениям, создавайте отдельный метод класса, выставьте в True значение характеристики WebMethod для этого метода. При необходимости, в классе могут быть определены и методы объекта и методы класса, не определенные как WebMethod’ы. Такие методы не будут доступны внешним приложениям, но могут быть вызваны из WebMethod’ов.

Ниже приведен пример класса, унаследованного от %SOAP.WebService, содержащего WebMethod Sum(), которому в качестве аргументов передаются два целых числа. Метод выполняет сложение этих чисел и возвращает полученный результат.

Class Web.Arithmetic Extends %SOAP.WebService [ ProcedureBlock ]
{

  /// SERVICENAME - Should be the name of the service for which this is a proxy.
  /// Override this parameter in the subclass.
  Parameter SERVICENAME = "Arithmetic";

  /// сложение двух чисел
  ClassMethod Sum(val1 As %Integer, val2 As %Integer) As %Integer [ WebMethod ]
  {
    s res = val1 + val2
    q res
  }

}

Чтобы протестировать работу созданного Web-сервиса, откройте соответствующий класс в браузере (рисунок 3) (например, из меню Cache Studio View->Web Page). Для проверки работы нужного WebMethod’а воспользуйтесь ссылкой, соответствующей имени метода (рисунок 4). Как упоминалось ранее, при компиляции класса, соответствующего Web-сервису, Cache автоматически создает для него WSDL-документ. Просмотреть содержимое WSDL-документа можно по ссылке Service Description. URL-адрес созданного WSDL-документа будет использоваться внешними приложениями для получения информации о вашем Web-сервисе.

В качестве результата выполнения метода Web-сервис возвращает XML-документ, содержащий значение, возвращаемое вызванным методом, например:

<?xml version="1.0" encoding="UTF-8" ?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xmlns:s="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <SumResponse xmlns="http://tempuri.org">
      <SumResult>11</SumResult> 
    </SumResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

URL-адрес WSDL-документа формируется следующим образом:

< URL страницы, соответствующей открытому классу (Web-сервису)>?WSDL=1

Чтобы работать с созданным Web-сервисом Cache из внешнего приложения, необходимо этому приложению указать адрес WSDL-документа вашего Web-сервиса, что является стандартной процедурой для работы с Web-сервисом независимо от технологии, используемой для его реализации. Например, вы можете обращаться к созданному Web-сервису из .Net. Для этого в меню Visual Studio.NET выберите Project->Add Web Reference… В строку Address открывшегося окна скопируйте адрес Вашего WSDL-документа. Перейдите по введенному Вами адресу. В случае успеха в левой части окна у Вас откроется содержимое указанного WSDL-документа. А в правой части в списке доступных (Available references) отобразится введенная ссылка. Добавьте данную ссылку (кнопка Add Reference). После этого в вашем клиентском приложении будет создан класс, соответствующий Web-сервису Cache. Таким образом, в .NET создан SOAP-клиент для работы с сервисом Cache. Вы можете из вашего приложения вызывать методы созданного класса, которые, в свою очередь, будут вызывать методы Web-сервиса Cache.

Технология Клиент-Сервер 2004'4