Класс SOAPMessage

public abstract class SOAPMessage
extends Object

Базовый класс для всех сообщений SOAP. При передаче по "каналу" сообщение SOAP представляет собой XML-документ или MIME-сообщение, первым частью которого является XML/SOAP-документ.

Объект SOAPMessage состоит из части SOAP и необязательно одной или нескольких прикрепленных частей. Часть SOAP для объекта SOAPMessage является объектом SOAPPart, содержащим информацию, используемую для маршрутизации и идентификации сообщений, а также содержащую прикладные данные. Все данные в части SOAP сообщения должны быть в формате XML.

Новый объект SOAPMessage по умолчанию содержит следующие элементы:

• Объект SOAPPart
• Объект SOAPEnvelope
• Объект SOAPBody
• Объект SOAPHeader

Часть SOAP сообщения можно получить, вызвав метод SOAPMessage.getSOAPPart(). Объект SOAPEnvelope извлекается из объекта SOAPPart, а объект SOAPEnvelope используется для извлечения объектов SOAPBody и SOAPHeader.

SOAPPart sp = message.getSOAPPart();
     SOAPEnvelope se = sp.getEnvelope();
     SOAPBody sb = se.getBody();
     SOAPHeader sh = se.getHeader();

В дополнение к обязательному объекту SOAPPart, объект SOAPMessage может содержать ноль или более объектов AttachmentPart, каждый из которых содержит прикладные данные. Интерфейс SOAPMessage предоставляет методы для создания объектов AttachmentPart и добавления их в объект SOAPMessage. Сторона, получившая объект SOAPMessage, может просмотреть его содержимое, извлекая отдельные прикреплённые части.

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

Объект MessageFactory может создавать объекты SOAPMessage с поведением, специализированным для конкретной реализации или приложения SAAJ. Например, объект MessageFactory может создавать объекты SOAPMessage, соответствующие определённому профилю, например, ebXML. В этом случае объект MessageFactory может создавать объекты SOAPMessage, инициализированные заголовками ebXML.

Для обеспечения обратной совместимости методы, добавленные в этот класс после версии 1.1 спецификации SAAJ, являются конкретными, а не абстрактными, и все они имеют реализации по умолчанию. Если в JavaDoc для этих методов не указано иное, реализации по умолчанию просто выбрасывают исключение UnsupportedOperationException, и код реализации SAAJ должен переопределить их методами, предоставляющими указанное поведение. Однако код клиентов старых версий не имеет этого ограничения, до тех пор, пока не делается заявление о соответствии какой-либо более поздней версии спецификации, чем та, для которой он был первоначально написан. Класс legacy, расширяющий класс SOAPMessage, может быть скомпилирован и/или запущен на последующих версиях API SAAJ без модификаций. Если такой класс был реализован правильно, он будет продолжать работать корректно относительно версии спецификации, для которой он был написан.

Поля

CHARACTER_SET_ENCODING

public static final String CHARACTER_SET_ENCODING

Указывает кодировку набора символов для SOAP-сообщения. Допустимые значения включают "utf-8" и "utf-16". Дополнительные поддерживаемые значения см. в документации поставщика. По умолчанию используется "utf-8".

Since:

SAAJ 1.2

См. также:

SOAPMessage.setProperty, Значения константных полей

WRITE_XML_DECLARATION

public static final String WRITE_XML_DECLARATION

Указывает, будет ли SOAP-сообщение содержать объявление XML при отправке. Единственные допустимые значения — "true" и "false". По умолчанию используется "false".

Since:

SAAJ 1.2

См. также:

SOAPMessage.setProperty, Значения константных полей

Конструкторы

SOAPMessage

public SOAPMessage()

Методы

setContentDescription

public abstract void setContentDescription(String description)

Устанавливает описание содержимого этого объекта SOAPMessage с заданным описанием.

Параметры:

description - String , описывающее содержимое этого сообщения

См. также:

getContentDescription()

getContentDescription

public abstract String getContentDescription()

Возвращает описание содержимого этого объекта SOAPMessage.

Возвращает:

String , описывающее содержимое этого сообщения, или null , если описание не было установлено

См. также:

setContentDescription(java.lang.String)

getSOAPPart

public abstract SOAPPart getSOAPPart()

Возвращает:

объект SOAPPart для этого объекта SOAPMessage

getSOAPBody

public SOAPBody getSOAPBody()
                     throws SOAPException

Возвращает:

объект SOAPBody , содержащийся в этом объекте SOAPMessage

Исключение:

SOAPException - если SOAP-тело не существует или не может быть получено

Since:

SAAJ 1.2

getSOAPHeader

public SOAPHeader getSOAPHeader()
                         throws SOAPException

Возвращает:

объект SOAPHeader , содержащийся в этом объекте SOAPMessage

Исключение:

SOAPException - если SOAP-заголовок не существует или не может быть получен

Since:

SAAJ 1.2

removeAllAttachments

public abstract void removeAllAttachments()

countAttachments

public abstract int countAttachments()

Возвращает количество вложений в этом сообщении. Это количество не включает SOAP-часть.

Возвращает:

количество объектов AttachmentPart , которые являются частью этого объекта SOAPMessage

getAttachments

public abstract Iterator getAttachments()

Возвращает все объекты AttachmentPart , которые являются частью этого объекта SOAPMessage.

Возвращает:

итератор по всем вложениям в этом сообщении

getAttachments

public abstract Iterator getAttachments(MimeHeaders headers)

Возвращает все объекты AttachmentPart , у которых есть записи заголовков, соответствующие указанным заголовкам. Обратите внимание, что возвращаемое вложение может иметь заголовки дополнительно к указанным.

Параметры:

headers - объект MimeHeaders , содержащий MIME-заголовки для поиска

Возвращает:

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

removeAttachments

public abstract void removeAttachments(MimeHeaders headers)

Удаляет все объекты AttachmentPart , у которых есть записи заголовков, соответствующие указанным заголовкам. Обратите внимание, что удаляемое вложение может иметь заголовки дополнительно к указанным.

Параметры:

headers - объект MimeHeaders , содержащий MIME-заголовки для поиска

Since:

SAAJ 1.3

getAttachment

public abstract AttachmentPart getAttachment(SOAPElement element)
                                      throws SOAPException

Возвращает объект AttachmentPart , связанный с вложением, на которое ссылается этот объект SOAPElement или null , если такое вложение не существует. Ссылки могут быть сделаны через атрибут href , как описано в SOAP-сообщения с вложениями, или через единственный дочерний узел Text , содержащий URI, как описано в профиле WS-I Attachments 1.0 для элементов типа схемы ref:swaRef. Эти два механизма должны поддерживаться. Поддержка ссылок через атрибут href также подразумевает, что этот метод также должен поддерживаться для элемента, являющегося элементом xop:Include ( XOP). Другие механизмы ссылок могут поддерживаться отдельными реализациями этого стандарта. Обратитесь к своему поставщику для получения подробной информации.

Параметры:

element - Элемент SOAPElement , содержащий ссылку на вложение

Возвращает:

ссылочный объект AttachmentPart или null, если такой объект AttachmentPart не существует или ссылка не найдена в этом объекте SOAPElement.

Исключение:

SOAPException - если при попытке доступа к вложению возникла ошибка

Since:

SAAJ 1.3

addAttachmentPart

public abstract void addAttachmentPart(AttachmentPart AttachmentPart)

Добавляет заданный объект AttachmentPart к этому объекту SOAPMessage. Объект AttachmentPart должен быть создан перед добавлением в сообщение.

Параметры:

AttachmentPart - объект AttachmentPart , который должен стать частью этого объекта SOAPMessage

Исключение:

IllegalArgumentException

createAttachmentPart

public abstract AttachmentPart createAttachmentPart()

Создает новый пустой объект AttachmentPart. Обратите внимание, что метод addAttachmentPart должен вызываться с этим новым объектом AttachmentPart в качестве параметра, чтобы он стал вложением в этот объект SOAPMessage.

Возвращает:

новый объект AttachmentPart , который можно заполнить и добавить к этому объекту SOAPMessage

createAttachmentPart

public AttachmentPart createAttachmentPart(DataHandler dataHandler)

Создаёт объект AttachmentPart и заполняет его, используя заданный объект DataHandler.

Параметры:

dataHandler - объект javax.activation.DataHandler , который сгенерирует содержимое для этого объекта SOAPMessage

Возвращает:

новый объект AttachmentPart , содержащий данные, сгенерированные заданным объектом DataHandler

Исключение:

IllegalArgumentException - если возникла проблема с указанным объектом DataHandler

См. также:

DataHandler, DataContentHandler

getMimeHeaders

public abstract MimeHeaders getMimeHeaders()

Возвращает все транспортно-специфические MIME-заголовки для этого объекта SOAPMessage независимым от транспорта способом.

Возвращает:

объект MimeHeaders , содержащий объекты MimeHeader

createAttachmentPart

public AttachmentPart createAttachmentPart(Object content,
                                           String contentType)

Создает объект AttachmentPart и заполняет его указанными данными указанного типа содержимого. Тип Object должен соответствовать значению, заданному для Content-Type.

Параметры:

content - объект Object , содержащий содержимое для создаваемого объекта AttachmentPart

contentType - объект String , задающий тип содержимого; примерами служат "text/xml", "text/plain" и "image/jpeg"

Возвращает:

новый объект AttachmentPart , содержащий заданные данные

Исключение:

IllegalArgumentException - может быть выброшено, если contentType не соответствует типу объекта содержимого или если не было объекта DataContentHandler для данного объекта содержимого

См. также:

DataHandler, DataContentHandler

saveChanges

public abstract void saveChanges()
                          throws SOAPException

Исключение:

SOAPException - если возникла проблема при сохранении изменений в этом сообщении.

SOAPException

saveRequired

public abstract boolean saveRequired()

Указывает, необходимо ли вызывать метод saveChanges для этого объекта SOAPMessage.

Возвращает:

true если saveChanges необходимо вызвать; false в противном случае.

writeTo

public abstract void writeTo(OutputStream out)
                      throws SOAPException,
                             IOException

Параметры:

out — объект OutputStream, в который будет записан этот SOAPMessage объект.

Исключения:

IOException — если произошла ошибка ввода-вывода.

SOAPException — если возникла проблема при внешнем представлении этого SOAP-сообщения.

setProperty

public void setProperty(String property,
                        Object value)
                 throws SOAPException

Параметры:

property — свойство, с которым должно быть связано указанное значение.

value — значение, которое должно быть связано с указанным свойством.

Исключения:

SOAPException — если имя свойства не распознано.

С момента:

SAAJ 1.2

getProperty

public Object getProperty(String property)
                   throws SOAPException

Извлекает значение указанного свойства.

Параметры:

property — имя свойства для извлечения.

Возвращает:

значение, связанное с именем свойства, или null если такое свойство не существует.

Исключения:

SOAPException — если имя свойства не распознано.

С момента:

SAAJ 1.2