org.infolayer.soap.util
Interface SoapOutboundMessage

All Known Implementing Classes:

SoapOutboundMessageImpl

public interface SoapOutboundMessage

A minimalistic interface for handling outbound (possibly) multipart SOAP messages. Multipart SOAP messages are MIME-encoded SOAP messages with attachments, as defined in the SOAP-with-attachments RFC document. Basically, the XML elements in the SOAP body can refer to attached binary data by a "href" attribute that starts with a "cid:" prefix. The interface was designed to have as few dependencies as possible. The only requirement is (a class that conforms to) the XmlSerializer. The KDOM is not used, but it is reasonably easy to generate the SOAP body from a DOM tree by calling "myDocument.write(myMsg.getBody())". There's also no direct dependency to the servlet API. The complete message is piped into the OutputStream of an HTTP request/response instead. This allows the API (implementing classes, that is) to be used in J2SE and J2ME environments. It even opens a door for using SOAP via non-HTTP transmission channels, for example, e-mail.

Author:

Joerg Pleumann (joerg@pleumann.de)

Method Summary

java.lang.String	addAttachment(java.io.InputStream stream, java.lang.String contentType) Adds an attachment to this SOAP message and returns the access key for it.
void	encode(java.io.OutputStream output) Encodes the whole SOAP request plus all attachments into one - possibly multipart - SOAP request.
XmlSerializer	getBody() Returns an XML serializer for writing the body part of this SOAP message.
java.lang.String	getContentType() Returns the content type of this message.
void	setAuthentication(java.lang.String login, java.lang.String password) Sets the login and password to use during the authentication phase of the SOAP request.

Method Detail

setAuthentication

public void setAuthentication(java.lang.String login,
                              java.lang.String password)
                       throws java.io.IOException,
                              java.lang.IllegalStateException

Sets the login and password to use during the authentication phase of the SOAP request. Must be specified before anything is written to the body, that is, before the getBody() method ist called. Otherwise an IllegalStateException is thrown.

Throws:

java.io.IOException

java.lang.IllegalStateException

getBody

public XmlSerializer getBody()
                      throws java.io.IOException

Returns an XML serializer for writing the body part of this SOAP message. When called for the first time, the serializer has just written the start tag of the SOAP body element, so the user code can immediately start to write the real payload of the SOAP message. The closing tags for the SOAP body and the whole envelope are written automatically then piping the message into an OutputStream via encode().

Throws:

java.io.IOException

addAttachment

public java.lang.String addAttachment(java.io.InputStream stream,
                                      java.lang.String contentType)

Adds an attachment to this SOAP message and returns the access key for it. The access key always starts with the "cid:" prefix as defined in the SOAP-with-attachments RFC document.

getContentType

public java.lang.String getContentType()

Returns the content type of this message. The content type is usually required before actually transmitting the message over some other protocol, for example HTTP. In the latter case, it can be copied directly into an HTTP request/response object.

encode

public void encode(java.io.OutputStream output)
            throws java.io.IOException

Encodes the whole SOAP request plus all attachments into one - possibly multipart - SOAP request. The OutputStream could be the one belonging to a HTTP request or response. In that case, the content type of the message should be queried (and set in the HTTP object) before writing to the stream.

Throws:

java.io.IOException