Writing RPC Services

Writing an RPC-based SOAP service is a very trivial undertaking, and really only involves the following two basic steps:

1. Create a code artifact which is supported by one of the Apache SOAP providers; either a standard Java class (including Java Beans,) an EJB, or a BSF supported script. The code artifact does not have to know anything about Apache SOAP, as you will simply be exposing either a method or a script function that exists within the artifact. For example, if you create a Java class that has a method called add(), then you could expose that method as a SOAP service. Multiple methods may be exposed for a single service, as is described in the next section.
   Note that parameters to your method/function must be serializable by SOAP, and so must exist within the SOAP mapping registry. For information on creating type mappings, look here.
   
   
2. Create an Apache SOAP deployment descriptor for your service. The deployment descriptor provides the implementation with the information necessary to handle requests for an offered service. For a Java service implementation, this will include such information as the name of the class which is providing the implementation, as well as the name of the methods which are to be exposed. More information about the deployment descriptors may be found here.
   

In a Java based 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, ...)) See the SOAP v1.1 specification for more information on SOAP Faults.

Java services can also be Apache SOAP-aware. Methods with an initial parameter of type SOAPContext can be invoked by a SOAP RPC call that passes the other parameters. The provider will invoke the method with the SOAPContext of the current request as the first parameter. The SOAPContext includes a bag (Hashtable) of instances, including the current HttpServlet, HttpSession, HttpServletRequest, HttpServletResponse, and DeploymentDescriptor. These are accessed through the getProperty method. The Constants class contains constants (beginning with BAG_) to use as parameters to getProperty. This mechanism provides services with the ability to access a great deal of information about the environment in which they are executing.

Java services can also use an Apache SOAP-provided interface ConfigurableService to receive initialization parameters. Upon instantiation, a service implementing this interface will have the configure method called. The parameters for this method are hashtables of initialization parameters for the service (from the deployment descriptor options tags), the servlet and the servlet context (web application).

Last updated 6/24/2002 by Scott Nichol <snicholnews@scottnichol.com>.