Ниже приведен Листинг 1 (запрос SOAP с параметром, закодированным с помощью шестибитного кода, в котором особого внимания заслуживает элемент address.

Листинг 1. Параметр в системе счисления с основанием 62

POST /ws/retrieve HTTP/1.0
Content-Type: text/xml; charset=utf-8
Accept: application/soap+xml multipart/related, text/*
Host: localhost:8080
SOAPAction: ""
Content-Length: 540

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soapenv:Body>
  <ps:retrieve 
           soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
           xmlns:ps="http://psol.com/2004/ws/retrieve">
   <address xsi:type="xsd:base64Binary">d3d3Lm1hcmNoYWwuY29t</address>
  </ps:retrieve>
 </soapenv:Body>
</soapenv:Envelope> 

Реализация включений

Разработчики Java могут воспользоваться включениями, используя JAX-RPC (API на Java для RPC, основанного на XML) и SAAJ (API SOAP с включениями для Java). Читателю следует обратить внимание на аббревиатуру SAAJ: JAX-RPC поддерживает включения (см., например, Ресурсы). Различие между JAX-RPC и SAAJ заключается в уровне абстракции, а не в функциональных возможностях.

JAX-RPC – это API высокого уровня, он более абстрактен по сравнению с SAAJ. JAX-RPC скрывает за слоем протокола RMI (Remote Method Invocation, технология построения распределенных приложений в спецификации языка Java) большинство ориентированных на протокол аспектов SOAP. Разработчик занимается объектами Java, а препроцессор превращает их в узлы SOAP. Для представления включений JAX-RPC использует классы java.awt.Image и javax.activation.DataHandler.

SAAJ более близок к протоколу. Поскольку для создания SOAP-сообщений с помощью SAAJ требуется больше усилий, чем с JAX-RPC (и, следовательно, он не предоставляет автоматических связей с WSDL), в большинстве случае читатель отдаст предпочтение JAX-RPC. Вместе с тем, низкоуровневые аспекты более удобны для иллюстрации того, как на самом деле работают включения. Листинг 2 – это запрос SOAP с включением. Этот запрос просит сервер изменить размер фотографии; поскольку размер файла фотографии велик, использование включения более предпочтительно.

Листинг 2. Параметр включения

POST /ws/resize HTTP/1.0
Content-Type: multipart/related; type="text/xml"; 
     start="<EB6FC7EDE9EF4E510F641C481A9FF1F3>"; 
     boundary="----=_Part_0_7145370.1075485514903"
Accept: application/soap+xml, multipart/related, text/*
Host: localhost:8080
SOAPAction: ""
Content-Length: 1506005

------=_Part_0_7145370.1075485514903
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-Id: <EB6FC7EDE9EF4E510F641C481A9FF1F3>

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soapenv:Body>
  <ps:resize 
          soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
          xmlns:ps="http://psol.com/2004/ws/resize" 
          xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
   <source href="cid:E1A97E9D40359F85CA19D1B8A7C52AA3"/>
   <percent>20</percent>
  </ps:resize>
 </soapenv:Body>
</soapenv:Envelope>

------=_Part_0_7145370.1075485514903
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-Id: <E1A97E9D40359F85CA19D1B8A7C52AA3>

note: binary data deleted...

------=_Part_0_7145370.1075485514903--

Приведенный ниже Листинг 3 демонстрирует создание запроса SOAP. Этот запрос просит сервер изменить размер изображения. Для реализации этой процедуры необходимо выполнить следующую последовательность действий:

• Создать соединение SOAP и объекты сообщения SOAP через фабрики (factories).
• Извлечь тело сообщения из объекта сообщения (промежуточный шаг: извлечь часть (part) SOAP и конверт).
• Создать новый XML-элемент для представления запроса и установить стиль кодирования.
• Создать включение и инициализировать его с объектом DataHandler.
• Создать еще элементы для представления двух параметров (source и percent).
• Ассоциировать включение с первым параметром посредством добавления атрибута href. Ссылка на это включение осуществляется через универсальный локатор ресурса cid (content-id).
• Задать значение второго параметра непосредственно в виде текста и вызвать сервис.

Сервис предоставляет ответ с изображением, размеры которого изменены, причем это изображение представлено в виде включения. Чтобы извлечь его, можно протестировать SOAP на предмет неисправности (т.е. ошибки). Если неисправностей нет, включение следует извлечь в виде файла, а затем обработать.

Листинг 3. Использование SAAJ

public File resize(String endPoint,File file)
{
   SOAPConnection connection =
      SOAPConnectionFactory.newInstance().createConnection();
   SOAPMessage message = MessageFactory.newInstance().createMessage();
   SOAPPart part = message.getSOAPPart();
   SOAPEnvelope envelope = part.getEnvelope();
   SOAPBody body = envelope.getBody();
   SOAPBodyElement operation =
      body.addBodyElement(
         envelope.createName("resize",
                             "ps",
                             "http://psol.com/2004/ws/resize"));
   operation.setEncodingStyle("http://schemas.xmlsoap.org/soap/encoding/");

   DataHandler dh = new DataHandler(new FileDataSource(file));
   AttachmentPart attachment = message.createAttachmentPart(dh);
   SOAPElement source = operation.addChildElement("source",""),
               percent = operation.addChildElement("percent","");
   message.addAttachmentPart(attachment);
   source.addAttribute(envelope.createName("href"),
                       "cid:" + attachment.getContentId());
   width.addTextNode("20");

   SOAPMessage result = connection.call(message,endPoint);
   part = result.getSOAPPart();
   envelope = part.getEnvelope();
   body = envelope.getBody();
   if(!body.hasFault())
   {
      Iterator iterator = result.getAttachments();
      if(iterator.hasNext())
      {
         dh = ((AttachmentPart)iterator.next()).getDataHandler();
         String fname = dh.getName();
         if(null != fname)
            return new File(fname);
      }
   }
   return null;
}

Стоит обратить внимание на то, что в Листинге 3 включение находится вне XML-сообщения. Такой подход повышает производительность.

Говоря о производительности, рассмотрим Листинг 4, в котором показана более общая (и существенно более короткая) версия JAX-RPC Листинга 3. Прекомпилятор JAX-RPC генерирует переходник (stub), которая значительно упрощает кодирование. В этом случае в качестве параметра метода передается объект DataHandler, а JAX-RPC автоматически генерирует это включение.

Листинг 4. Более эффективный JAX-RPC

public File resize(File file)
   throws ServiceException, RemoteException
{
   AttachmentService service = new AttachmentServiceLocator();
   AttachmentTip port = service.getAttachmentTip();   // get stub
   DataHandler dh = new DataHandler(new FileDataSource(file));
   DataHandler result = port.resize(dh,20);
   return new File(result.getName());
}

Заключение

Возможность выбора всегда желательна и SOAP предоставляет такую возможность при работе с бинарными данными: их можно либо кодировать с помощью кода base 64 внутри полезной нагрузки XML, что является хорошим решением для небольших наборов данных, либо присоединять более крупные бинарные незакодированные файлы к этому запросу.

Ресурсы

• Форум, посвященный обсуждению статей в колонке Беноита Марчала (Benoît Marchal) “XML в действии” (Working XML).
• Для изучения SAAJ и JAX-RPC можно скачать Axis. Необходимо отметить, что для работы с включениями читателю потребуется установить два дополнительных компонента: JavaMail и JavaBeans Activation Framework. Автор хотел бы подчеркнуть, что включения не работают в Axos (версии 1.1 и 1.2), если эти две компоненты не установлены.
• Международный консорциум W3C ведет работы над поддержкой вложений в SOAP 1.2 (attachment support to SOAP 1.2).
• Статья Рассела Бутека (Russell Butek) «Отправка и получение сообщений SOAP с JAX-RPC» ("Send and receive SOAP messages with JAX-RPC") (developerWorks, сентябрь 2003 г.).
• В своей статье «Преобразование типов Apache SOAP» (Apache SOAP type mapping) Гевин Бонг (Gavin Bong) рассматривает соответствие между SOAP и технологией Java. Несмотря на то, что этот материал написан с позиции Apache SOAP, он применим и к большинству инструментальных средств SOAP  (developerWorks, апрель 2002 г.).
• Ранняя версия (6.0) сервера приложений IBM WebSphere (IBM WebSphere Application Server Technology for Developers, version 6.0,), поддерживающего последнюю редакцию спецификации J2EE (версию 1.4).
• Множество других ресурсов в зоне XML рубрики developerWorks. Полный список статей колонки «Совет» (Tip) приведен на странице с кратким описанием этой рубрики. 
• На странице информационный бюллетень Web-cервисов/Советов по XMLможно подписаться на еженедельную рассылку новостей рубрики developerWorks.
• Книга Беноита Марчала «Прикладные решения XML» (Applied XML Solutions) можно приобрести в книжном магазине разработчика рубрики developerWorks.
• На странице IBM Certified Developer in XML and related technologies приведена информация о том, как стать сертифицированным разработчиком XML.

Об авторе

Бёнуа Маршаль (Benoît Marchal)  – бельгийский консультант. Он автор многих книг, посвященных XML, в том числе «XML на примерах, второе издание» (XML by Example, Second Edition). Беноит Марчал специализируется в области XML, технологий Java и электронной коммерции. Более подробную информацию о нем можно получить на его сайте www.marchal.com. С ним можно связаться по адресу bmarchal@pineapplesoft.com.