org.infolayer.soap.util
Interface SoapInboundMessage

All Known Implementing Classes:

SoapInboundMessageImpl

public interface SoapInboundMessage

A minimalistic interface for handling inbound (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 parser that conforms to) the XmlPullParser. The KDOM is not used, but it is reasonably easy to generate a DOM for the SOAP body by calling "new Document.read(myMsg.getBody())". There's also no direct dependency to the servlet API. The message class is initialized on the InputStream and content type returned from 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:

J�rg Pleumann (joerg@pleumann.de)

Method Summary

void	decode(java.io.InputStream input, java.lang.String contentType) Decodes and initializes the object.
java.io.InputStream	getAttachment(java.lang.String key) Returns an InputStream to a single attachment by its key.
java.util.Enumeration	getAttachments() Returns an enumeration holding the keys for all the attachments of the SOAP request.
java.lang.String	getAttachmentType(java.lang.String key) Returns the MIME type of a single attachment by its key.
XmlPullParser	getBody() Returns an XML parser for the body of the SOAP request.
java.lang.String	getLogin() Returns the remote user's login or null if no login has been set.
java.lang.String	getPassword() Returns the remote user's password or null if no password has been set.

Method Detail

getLogin

public java.lang.String getLogin()

Returns the remote user's login or null if no login has been set.

getPassword

public java.lang.String getPassword()

Returns the remote user's password or null if no password has been set.

getBody

public XmlPullParser getBody()
                      throws XmlPullParserException

Returns an XML parser for the body of the SOAP request. The first token will be the start tag of the first XML element after the SOAP body start tag, that is, the real SOAP payload. Note that this method always returns the same parser instance, so it is possible to read the whole SOAP body exactly once.

Throws:

XmlPullParserException

getAttachments

public java.util.Enumeration getAttachments()

Returns an enumeration holding the keys for all the attachments of the SOAP request. The keys are actually strings, but the Enumeration doesn't know about that. Maybe a String array would be a better return type? Do we need this method at all? Under normal circumstances, each attachment would be referenced at least once in the body.

getAttachment

public java.io.InputStream getAttachment(java.lang.String key)
                                  throws java.lang.IllegalArgumentException,
                                         java.io.IOException

Returns an InputStream to a single attachment by its key. Keys always start with the "cid:" prefix, as defined in the SOAP-with-attachments RFC document. Requesting the InputStream for an unknown key results in an IllegalArgumentException.

Throws:

java.lang.IllegalArgumentException

java.io.IOException

getAttachmentType

public java.lang.String getAttachmentType(java.lang.String key)
                                   throws java.lang.IllegalArgumentException

Returns the MIME type of a single attachment by its key. Keys always start with the "cid:" prefix, as defined in the SOAP-with-attachments RFC document. Requesting the content type for an unknown key results in an IllegalArgumentException.

Throws:

java.lang.IllegalArgumentException

decode

public void decode(java.io.InputStream input,
                   java.lang.String contentType)
            throws java.io.IOException,
                   XmlPullParserException,
                   java.lang.IllegalArgumentException

Decodes and initializes the object. The InputStream holds the - possibly multipart - SOAP request in its transmission form. The content type is needed to know in advance whether the InputStream holds multipart data or not (this can't be derived from the InputStream alone). It must be either "text/xml" or "multipart/related". Anything else will result in an IllegalArgumentException. Both parameters should suffice to decode a SOAP request regardless of the way it has been transmitted. Thus we are not bound to an HTTP request and do not have a dependency to the servlet API.

Throws:

java.io.IOException

XmlPullParserException

java.lang.IllegalArgumentException