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:
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.
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.
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>.