Writing RPC Clients

Writing clients to access SOAP RPC-based services is fairly straightforward. Apache SOAP provides a client-side API to assist in the construction of the SOAP request, and then to assist in interpreting the response. Conceptually, RPC-based service are relatively easy to understand, because the concepts involved are those which may be found in any procedural based language. To invoke a procedure, you need the name of the procedure and the parameters to pass to it. When the invocation completes, you need to extract any response information from the return value and/or output parameters.

The basic steps for creating a client which interacts with a SOAP RPC-based service are as follows:

1. Obtain the interface description of the SOAP service, so that you know what the signatures of the methods that you wish to invoke are.
   You can either look at a WSDL file (or at some other interface definition format) for the service, or directly at its implementation.
   
   
2. Make sure that there are serializers registered for all parameters which you will be sending, and deserializers for all information which you will be receiving back.
   Parameters must be serialized into/deserialized from XML before they can be transmitted/received, and so Apache SOAP provides a number of pre-defined serializers/deserializers which are available. If you need to transmit or receive a type which has not been registered, then you will need to write and register your own serializer/deserializer.
   
   
3. Create the org.apache.soap.rpc.RPCMessage.Call object.
   The Apache SOAP Call object is the main interface to the underlying SOAP RPC code
   .
   
4. Set the target URI into the Call object using the setTargetObjectURI(...) method.
   Pass in the URN that the service used to identify itself in its deployment descriptor.
   
   
5. Set the method name that you wish to invoke into the Call object using the setMethodName(...) method.
   This must be one of the methods exposed by the service which is identified by the URN given in the previous step.
   
   
6. Create any Parameter objects necessary for the RPC call and set them into the Call object using the setParams(...) method.
   Make sure that you have the same number of parameters with the same types as the service is expecting. Also make sure that there are registered serializers/deserializers for the objects which you will be transmitting/receiving. (See step 2.)
   
   
7. Execute the Call object's invoke(...) method and capture the Response object which is returned from invoke(...).
   The invoke(...) method takes in two parameters, the first is a URL which identifies the endpoint at which the service resides (i.e. http://localhost/soap/servlet/rpcrouter) and the second is the value to be placed into the SOAPAction header. Remember that the RPC call is synchronous, and so may take a while to complete.
   
   
8. Check the Response object to see if a fault was generated using the generatedFault() method.
   
   
9. If a fault was returned, retrieve it using the getFault(...) method, otherwise extract any result or returned parameters using the getReturnValue() and getParams() methods respectively.
   While most of the providers will only return a result, if you have created your own provider (or obtained one from somewhere else,) it may also return output parameters.
   

Because SOAP is a supposed to be a standard, you should be able to use the clients that you create with the Apache SOAP API to access services running on a different implementations, and vice versa.

Special Note: Interacting with Stateful Services

Services may be stateful - that is, once an interaction is started with a service, a series of calls to it may interdepend on each other. Apache SOAP supports authoring stateful services (via deploying with a lifecycle of session) as well as calling stateful services. Currently, session support is only available for HTTP.

HTTP session maintenance is on by default. What that means is that if a service you are talking to via HTTP sets the appropriate HTTP cookies to maintain the session, those will be copied and stored in the call object used to invoke the service. If another call is made using the same call object, then that cookie will be sent back to the server, thus maintaining the session. Thus, all you have to do is ensure that a single instance of a call object is used across all the calls that you wish to make over the same HTTP session.

The "addressbook2" sample shows an example of this in action.

Special Note: Using 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 response 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.

For more information on using Apache SOAP and SMTP please see Jonathan Chawke's FAQ.

Last updated 5/19/2001 by Bill Nagy <nagy@watson.ibm.com>.