5.3 RPC over SOAP

One of the most common applications of SOAP is to provide Remote Procedure Call (RPC) functionality. While SOAP goes beyond the goals of either XML-RPC or the original RPC itself, it is a simple fact that a large number of existing systems built around the RPC model are still in use. New applications are expected to communicate with these legacy systems in addition to any extra abilities they may offer.

The mechanics of implementing RPC via SOAP aren't at all difficult. Looking to XML-RPC as a model for encoding requests , responses, and the requisite data, adapting this protocol to run within the realm of SOAP is a fairly direct task. Both SOAP protocol versions specifically address this issue.

There is more to providing this functionality than merely taking an XML-RPC message and wrapping SOAP envelope elements around it. The SOAP RPC capabilities aren't direct mirrors of XML-RPC. The features of SOAP (named parameters, distinct separation of message header and body) are used to full advantage in the RPC framework.

5.3.1 Supplying the RPC Information

To contain RPC functionality, a message has to provide the information that sets up the call and defines the result. Besides a URI to the target SOAP node, the call must provide the procedure name (referred to in some documents as the method ) and the parameters for the call. Additionally, some information may be present that, while nor required, adds further detail and specifics to the message.

A signature for the procedure or method is optional rather than required. This is only from the viewpoint of the SOAP specification itself. Whether the node acting as the RPC server requires the signature is a different issue. A signature is something that defines the type information for the parameters coming in to the procedure call, as well as the return value if the procedure returns anything. Some servers require this information to provide polymorphic procedures and methods to their clients . The typing information allows the calls to be properly dispatched to the matching version of the code. It also lets a server detect badly formed calls without risking more serious runtime faults.

In addition to the optional signature, a RPC message may also provide extra information in the SOAP header. This information can't directly be part of the procedure call itself, but as will be explained in a later section, there are several types of application data that may be best suited for this method.

5.3.2 Putting the Call and Response in the Body

Both the request and the response in an RPC communication use the SOAP Body element. A procedure call is modeled as a SOAP structure, with each parameter to the call expressed as an accessor of the structure. The SOAP interpretation of RPC assumes that all parameters are named, just as SOAP itself does. This is a noteworthy difference from XML-RPC, in which parameters are defined by their ordinal position alone. If the call being encoded includes a signature, the order of the parameters must match the signature. The structure itself is given a name that matches the name of the method/procedure being called.

The arguments passed to and returned from the call may overlap. In the relevant sections of the SOAP specifications, the discussions of RPC refer to parameters as being one of [in] , [in/out] , or [out] . The parameters that are [in/out] are those present in both the request and the response. These attributes of the parameters aren't part of the call itself or the serialization; this is a notation carried forward from CORBA and SQL to further clarify the roles that procedure parameters play.

A response is also expected to be in the form of a structure, with accessors for all the parameters being passed back. These include the return value (if any) from the call, as well as any [in/out] parameters that were passed in, and any [out] parameters that were added.

In SOAP 1.1, the specification states that the return value of the call is the first accessor in the structure for the response, with the remaining values in the order that matches the signature (if any). It also recommends, without requiring, that the structure for the response bear the same name as the request with the string Response appended.

In contrast, the SOAP 1.2 specification has several changes to this model. The return value parameter is encouraged to be first, but it isn't required to be. However, it must be named result , and be namespace-qualified with a label that has been mapped to the namespace identifier, http://www.w3.org/2002/06/soap-rpc. In addition, it states that the return value should be present only when the value itself is a non-void (null) value. The SOAP 1.1 coverage doesn't make any reference to void or null values. Lastly, SOAP 1.2 makes no suggestion or recommendation as to the naming of the structure for the response.

For both versions, errors in the invoked procedure are handled using RPC faults, discussed later.

5.3.3 Use of the SOAP Header

The SOAP message header is generally less important in RPC usage. It can be used to provide transaction information, authentication credentials, as well as the usual application of routing information.

The information provided in the header can't be part of the actual method call itself. That must be fully expressed in the body.

5.3.4 RPC Faults

Since the framework for RPC is still SOAP itself, errors in the method or procedure execution are communicated back to the client by means of a SOAP fault structure. While general SOAP bodies don't require a Fault element be the only element within a Body , in RPC terms, a response can't signal success and failure at the same time. Because any data in the body of the response that isn't a fault constitutes success, RPC messages do have a restriction: an RPC response that contains a Fault may not contain any other elements.

RPC faults in SOAP 1.1 are simply implemented using the existing guidelines for SOAP itself. It is expected that the faultcode attribute would be specific to RPC application, and that the remaining attributes would be correctly utilized. SOAP 1.2 takes a more thorough look at the fault model for RPC and provides a subsection within the specification devoted to the subject.

The fault model in SOAP 1.2 uses an additional namespace identifier, which is given the label rpc in the specification. The URI for this namespace is http://www.w3.org/2002/6/soap-rpc , as used for other RPC-specific elements described earlier. The specification provides four predefined QNames for RPC-specific faults, as shown in Table 5-9. The table lists the faults in a decreasing order of precedence.

Table 5-9. RPC fault codes for SOAP 1.2

Fault code	Meaning
env:Server	This code is recommended for situations in which the problem is server- related , such as resource problems or a scheduled black-out period.
env:DataEncodingUnknown	All the elements are qualified to use the encodingStyle attribute provided by SOAP itself. This code is recommended for cases in which a part of the message uses an unknown encoding.
rpc:ProcedureNotPresent	If the requested method or procedure is unknown to the server, this fault code must be used (unless a higher-priority condition was met first).
rpc:BadArguments	If there is a mismatch in the arguments against a specified signature, or when the server is unable to process the arguments, this code must be used, unless a code of higher-priority has already been chosen .

Aside from these predeclared fault codes, the mechanism itself is the same as for general SOAP faults. Note that some transport bindings such as HTTP or SMTP may define additional elements or additional fault codes. If any such definitions apply, the application has a responsibility to use them as well.

In all RPC fault cases, the detail and faultstring attributes are defined on a per-implementation basis.