Creating message-oriented services in Apache SOAP is a little more complex than creating a simple RPC-based service, but in many cases a message-oriented model provides a better fit to the problem which you are trying to solve. In a message-oriented service, the service implementation is responsible for processing the contents of the SOAP Envelope. That is to say, that while the Apache SOAP API's are still available to interact with the SOAPEnvelope object, the service implementation must invoke those calls which are necessary to extract whatever information from the header and body that are needed for it to process the request. If the message-oriented service is participating in in a request-response protocol which uses SOAP messages in both directions, then it is also responsible for generating the appropriate response SOAPEnvelope. (A message-oriented service does not have to return a SOAPEnvelope, but instead can return anything that it wants.)
Because message-oriented services have full control over the SOAP Envelopes, any XML document may be passed as part of the envelope body. When the service receives the SOAP Envelope, it is free to extract the body, and do with it as it pleases.
Unlike RPC-service implementations, message-oriented service implementations must all conform to a single interface:
void name(SOAPEnvelope request-envelope, SOAPContext request-context, SOAPContext response-context)
where name is the name of the method/function, request-envelope is the SOAPEnvelope containing the incoming message, request-context is the SOAPContext for the incoming message, and response-context is the SOAPContext which may be used for a response if one is needed.
If the communications transport which you are using supports two-way interaction, such as HTTP, then you can use the response context to send a response back to the client. If you want to send a SOAP Envelope back to the client, you can use the org.apache.soap.Envelope's marshall(...) method to marshall your envelope to a java.io.StringWriter, and then invoke the response context's setRootPart(...) method, passing the StringWriter as the first argument. If you want to send back any other data types, then you may need to invoke other methods in the response context.
As with RPC-based service implementations, in a Java based message-oriented service implementation you may throw a SOAPException to indicate that some error has occurred when processing the request. Throwing a SOAPException(FAULT_CODE_CLIENT, ...) will allow your service implementation to indicate that the failure was due to a client error, whereas throwing a SOAPException(FAULT_CODE_SERVER, ...) will indicate that your service implementation was at fault. (If you throw any other type of exception, the server will catch it, and will pass it on as a SOAPException(FAULT_CODE_SERVER, ...)) If your transport supports two-way interaction, such as HTTP, then a SOAP Envelope containing a SOAP Fault will automatically be returned to the client. See the SOAP v1.1 specification for more information on SOAP Faults.
Last updated 5/20/2001 by Bill Nagy <nagy@watson.ibm.com>.