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 InformationTo 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 BodyBoth 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.
For both versions, errors in the invoked procedure are handled using RPC faults, discussed later. 5.3.3 Use of the SOAP HeaderThe 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 FaultsSince 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
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. |