Client-Side API

Needs to be updated for 2.1!

Invoking RPC-Oriented Services

The org.apache.soap.rpc package supports performing RPC over SOAP. The Apache-SOAP model is as follows:

The URI of the method call element is used as the object ID on the remote side. The client side API has a "Call" object (org.apache.soap.rpc.Call) that is filled in with the method name, object ID and parameters. The marshalling/unmarshalling of Java datatypes to/from XML is supported by a type mapping registry (see org.apache.soap.encoding.SOAPMappingRegistry), and serialization (org.apache.soap.util.xml.Serializer) and deserialization (org.apache.soap.util.xml.Deserialization) interfaces that marshallers and unmarshallers, respectively, must implement. The built-in encoders/decoders are simply implementations of these interfaces that are preregistered in the SOAPMappingRegistry.

Once a Call object is set up, its invoke (URL, String) method may be called to call the method using the URL as the SOAP endpoint to deliver to and the 2nd argument being the value of the SOAPAction header. This method returns a Response object (org.apache.soap.rpc.Response) which contains the actual response (if any) or the fault if a fault was generated.

If the RPC is carried over HTTP, the server-side RPC router (rpcrouter.jsp in the webapp directory) receives the POST-ed envelope, unmarshalls it and then builds a Call object. Then, the target object is located by looking up the object ID in the ServiceManager's (org.apache.soap.server.ServiceManager), the method name is verified and then the invoke (Object) method is called to call the method on the target object. The return value is a Result (org.apache.soap.rpc.Result) object which is then marshalled and sent back as the HTTP response.

If the RPC is carried over SMTP, then it goes to a mailbox and sits there waiting to be acted upon. We provide a POP3 to HTTP to SMTP bridge to receive these mail messages, post the content to an HTTP SOAP endpoint, get the result and forward the result by mail (SMTP) to the original sender. The receiving side will poll the POP3 server, receive the message, extract the content, unmarshall and return the Response to the original caller.

RPC over SMTP

To do RPC over SMTP in Apache-SOAP a certain amount of email infrastructure needs to be available. Namely, you need an SMTP server, a POP3 server and an email address that you can use to be the equivalent of the server-side HTTP router. That is, all SOAP RPC calls are sent to a specific address which then processes the request somehow and send the result to the sender. To avoid duplicating the server-side infrastructure, we have implemented the SMTP server-side as a bridge that receives mail sent to the SOAP router email address via POP3, posts the SOAP envelope to an existing HTTP SOAP infrastructure and sends the response back to the sender of the email request via SMTP.

On the client side, the application sends the SOAP request via SMTP to the SOAP router email address indicating the address that the response should be sent to. Then, it starts polling a POP3 server to see whether the response has arrived. When it does, the envelope is parsed and the respose is extracted. We are using a POP3 bean from alphaWorks for the POP3 stuff and that bean does not support selective downloading of email. As a result, the current implementation relies on the "next message" arriving to the client's reply address to be the message containing the response to the request. The implication is that current implementation does not allow you to make multiple RPC calls using the same reply address at the same time.

NOTE: We strongly recommend against using your own email address for testing RPC over SMTP. There are many free POP3 email providers on the Web (such as www.mailandnews.com, for example) if you are unable to set up multiple POP3 accounts yourself.