The XOE SOAP Service (XOE package name soap) allows an application builder to communicate with other networked applications exposed by a SOAP Server. This service is also able to act as a lightweight (i.e. incomplete) SOAP Server with the help of the XOE package named "simple-soap-server." The "simple-soap-server" XOE package is an extension of the SOAP service that allows a XOE framework to listen for incoming soap requests.
The soap package depends on the mime package.
mime ^ | soap
The mime package is not a service. It is a collection of objects that can parse inputstreams into mime attachments. For more information, please refer to the javadocs for org.xoe.mime.
The XOE SOAP Service complies with "SOAP Version 1.1" specification as well as "SOAP Messages with Attachments." It has been tested with the Apache SOAP project version 2.2. It is doubtful that Microsoft .NET services can be accessed with the XOE SOAP Service at this time.
This document assumes that the reader understands the following specifications:
Table 14-1.
W3C SOAP Version 1.1 | http://www.w3.org/TR/SOAP |
W3C SOAP Messages with Attachments | http://www.w3.org/TR/SOAP-attachments |
Apache SOAP project | http://xml.apache.org/soap/index.html |
In order to make a SOAP request, a developer will need four pieces of information:
A SOAP Service Name, also known as the URI (Universal Resource Identifier)
The Method Name the developer wishes to access on the remote SOAP Service
A list of parameter objects contained in the form of a java.util.Stack object
The URL of the remote Soap Server
There are two optional parameters that can be passed to a Soap request:
Encoding Style. This is needed if the remote method returns a more complex object than a primitive type. Currently, only DOM objects are supported.
A java.util.Vector can be passed as a way of receiving a collection of objects from the remote method.
The SOAP Service is dependent on the MIME package. This allows SOAP messages to send and receive files as MIME attachments. This adds great potential and convenience for future file sharing applications and the handling of email attachments. Currently, this feature is used exclusively with the XOE Sync Service.
The architechture of the SOAP Service can be divided into three parts:
The SOAP Message
The SOAP Document
The SOAP Parameter
The SOAP Message. The org.xoe.soap.SoapMessage object is resposible for the networking. It contains all the information necessary to send the message to a SOAP server. One of these pieces of information is a SOAP Document.
The SOAP Document. The org.xoe.soap.SoapDocument extends org.xoe.core.dom.XDocument which contains only the XML content of a SOAP Message.
The SOAP Parameter. org.xoe.soap.SoapParameter is an interface of which all SOAP parameter implementations must implement. There is a complementary org.xoe.soap.SoapParameterFactor that takes an object and creates SoapParameters for the developer. This will only work if the type of object given to the factory matches an implementation of SoapParameter. For example, if the object given to SoapParameterFactory is a String object, then there must be StringSoapParameter object provided. The following is a list of SoapParameter implementations provided in the SOAP Service package:
StringSoapParameter IntegerSoapParameter LongSoapParameter ContentElementSoapParameter PackageQuerySoapParameter VectorSoapParameter XElementSoapParameter ExceptionSoapParameter
If a developer needs to access a SOAP service method that contains a parameter that is not a String, Integer, Long, ContentElement, PackageQuery, Vector, XElement or Exception, a new SoapParameter added to the package is all that needs to be done. The SoapParameterFactory will find it through reflection, as long as the name of the class begins with the EXACT name of the parameter object.
All constants used for creating and parsing Soap Messages can be found in SoapConstants. All exceptions thrown while creating and parsing Soap Messages are caught and rethrown as SoapServiceExceptions.