8.5 SOAP Remote Procedure Call

One application that can be built on top of SOAP is remote procedure calling (RPC). In fact, it was one of the main motivations for the definition of SOAP. This section describes the RPC specification given in [SOAP] but others are possible.

An initial SOAP message indicates a procedure call request. The SOAP message then returned is the remote procedure response presumably a return value or error indication.

8.5.1 SOAP HTTP Remote Procedure Call

Using SOAP for an RPC works independently of the transport used to carry and the encoding in use within the SOAP messages involved. However, it was anticipated that the SOAP encoding (see Section 8.3) and the HTTP protocol binding (Section 8.4) would be commonly used. In the case of HTTP, an RPC naturally uses an HTTP request and the response uses an HTTP response.

To call a remote procedure, you must have the following information:

• The URI of the target SOAP node

• The remote procedure name

• The parameters to the procedure or method

The HTTP Header includes the URI. The parameters appear as an element in a SOAP Body Block with the same name and type as the remote procedure. They are modeled as structs, with elements having the same names as the "in" and "in/out" parameters. Those names should appear in the same order as they do in the procedure. The remote procedure's response also appears as a SOAP Body Block, with an element name matching the procedure name. Such a Block contains a similar struct, whose first element should have the "result" name in the

 http://www.w3.org/2001/12/soap-rpc 

namespace specified in the schema described later in this section. The Block can have additional elements named for "out" or "in/out" parameters. The procedure must return a result element unless its return value is "void." A procedure cannot return both a result and a Fault. You can define the procedure so that, for missing parameters, it returns a result or a Fault as desired.

You can also include the following optional information:

• A procedure signature

• Optional Header data

In the latter case, you would include optional Header data as an additional SOAP Header Block. It could, for example, be a transaction identification or an indication that debugging information is requested.

Use whatever protocol binding you have set up to carry the invocation to, and the result back from, the remote procedure.

8.5.2 Remote Procedure Call Faults

Returning a Fault, as described in Section 8.2.4, indicates failure of the remote procedure. The following rules apply in such a case. When a conflict occurs, the first applicable rule appearing below dominates. The "env" and "rpc" namespace prefixes represent the appropriate prefixes for the SOAP envelope and SOAP remote procedure call namespaces, respectively.

1. Generate an "env:Server" Fault if the problem is temporary, such as a transient lack of resources.

2. Generate an "env:DataEncodingUnknown" Fault if the procedure encounters an encoding it does not recognize.

3. Generate an "rpc:ProcedureNotPresent" Fault if no such procedure exists at the server.

4. Generate an "rpc:BadArguments" Fault if a mismatch between the type and the number of supplied parameters makes it impossible to run the remote procedure.

5. Generate other application-specific Faults as needed.

8.5.3 Remote Procedure Call Schema

The schema for an RPC is trivial, because the only thing that must be defined is the element used for returning a procedure result. All other data, including procedure parameters, can be transmitted with existing SOAP mechanisms.

 Schema definition: <schema xmlns="http://www.w3.org/2001/XMLSchema"         targetNamespace="http://www.w3.org/2001/12/soap-rpc" >   <element name='result' /> </schema> 

8.5.4 Mapping Application Parameter Names into XML

The RPC technique given earlier implies that you can turn application parameter names into valid XML names. If the characters in the application name are valid XML name characters, this transformation usually isn't a problem. You can mostly solve name conflicts by qualifying them with a namespace [Names]. Even with qualification, however, all names starting with "xml" in any capitalization are reserved. The [SOAP] draft suggests the following procedure to solve this:

1. Map each character in the application name into Unicode characters [Unicode]. If no obvious mapping exists, use an application-determined mapping.

2. Scan through the results from Step 1.

   1. If the first three letters of the application name are "xml" in any capitalization, including mixed capitalization, output

       _xFFFF_ 

      and then proceed as normal. The "xml" characters will be valid XML name characters and will be copied over.

   2. If you encounter an underscore character ("_") followed by a lowercase x in the application name, output the underscore as

       _x005F_ 

      and then proceed as normal. The x character will be a valid XML name character and will be copied over.

   3. If you encounter an illegal character for an XML name or, in the first position, an illegal character for the first character of an XML name, replace it with

       _xUUUUUUUU_ 

      where UUUUUUUU is the hexadecimal encoding, using capital A F, for the 32-bit Unicode value for the character. An exception occurs when the top 16 bits are zero, in which case you replace the character with

       _xUUUU_ 

      where UUUU is the similar hex encoding of the bottom 16 bits of the character's Unicode value.

   4. Otherwise, just copy the application name character to the XML name being constructed.

   For example, the following five comma-separated parameter names in a hypothetical application

    foo, Axml, xmlA, y_x, &> 

   would map into

    foo, Axml, _xFFFF_xmlA, y_005F_x, _x0024__x003E_