Trastornos pragmáticos

A message body must have the local name of body. It must be associated with the

http://www.w3c.org/2002/06/soap-envelopenamespace. Child elements are optional, and multiple child elements are allowed. No body-specific attributes are defined. The mes- sage body is targeted at the ultimate receiver, who must understand the body.

Remember that SOAP is a unidirectional protocol. It is often difficult to keep that in mind. It is natural to think of SOAP as a request/response protocol. But, there is no requirement to return a response for a message received. Still, message body child ele- ments have been defined that are the logical consequence of certain inputs. Because of this, our discussion of the message body will be divided into request message body elements and response message body elements. However, the reader should keep in mind that the SOAP protocol regards communication in each direction as separate and unrelated events. A discussion of the options for returning a response to a SOAP request is discussed in the section on protocol bindings.

Request message body elements

A SOAP request message body may contain zero or more child elements. If multiple child elements are present they can represent a single unit of work, multiple units of work, or some combination of work and data. Request body elements can be divided into two categories, document type and RPC type. The distinction is subtle. There is nothing that distinguishes an RPC message body from a document body.

Document body elements are analogous to paper documents. Most likely, they will be forms that have an understood structure such as purchase orders, invoices, itiner- aries, or prescriptions. In order for the document to be processed correctly, it is impor- tant that the ultimate receiver be cognizant of the namespace that defines the elements of the document.

RPC message bodies are XML-based remote procedure calls. SOAP Version 1.2 Part

2: Adjuncts(W3C 2002f) describes how to encode data structures used by programming languages to convey parameters in procedure calls. SOAP does not mandate the use of these encoding rules and acknowledges the possibility of using other encoding rules. However, use of other encodings will adversely impact the interoperability of the RPC. Two options exist for encoding the arguments of an RPC. First, the SOAP RPC invo- cation can be a struct where the name of the struct corresponds to the procedure or method name. Each input or in/out argument to the procedure is a child element structure with a name and type corresponding to the name and type of the parameter in the procedure signature. The second RPC encoding method is to encode each argu- ment as an element of an array. The name of the array corresponds to the name of the procedure and the position in the array corresponds to the position in the argument list. If problems occur, several RPC specific faults have been defined which will be described later.

The following example invokes an RPC called buy. This RPC is in the form of a structure and takes two arguments, the order and the shipInfo. Note that there is no explicit indication that this is an RPC invocation.

<? Xml version=’1.0’ ?> <env:Envelope xmlns:env=”http://www.w3.org/2002/06/soap-envelope”> <env:Header> <sec:hdr1 xmlns:sec=”http://www.myCompany.com/logging” sec:role=”http://www.w3.org/2002/06/soap envelope/role/next” sec:mustUnderstand=”true”> ... </sec:hdr1> </env:Header> <env:Body> <buy xmlns=”http://www.widgets.com/purchasing” env:encodingStyle=”http://www.w3.org/2002/06/soap- encoding”> <order xmlns=”http://www.widgets.com” currency=”USdollars”> 42 Chapter 2

<orderNum>4567</orderNum> <quantity>6</quantity> <unitPrice>3.25</unitPrice> <aggregatePrice>19.50</aggregatePrice> </order> <shipInfo> <name>My Company</name>

<streetAddress>234 Main St.</streetAddress> <city>Boston</city> <state>MA</state> </shipInfo> </buy> </env:Body> </env:Envelope>

Response message body elements

The content of response message bodies can be documents, RPC responses, or a SOAP fault. Just as a document can be received, a document can result from the receipt of a document. For instance, a reservation request can result in the creation of an itinerary. Using SOAP to transmit a document has already been described, so the discussion will not be repeated here.

The response to an RPC can be a structure or an array. The name of the structure is identical to the name of the procedure or method that is returning the information. If the procedure or method returns a value, it must be named result, and it must be name-

space qualified with http://www.w3.org/2002/06/soap.rpc. Every other output or

input/output parameter must be represented by an element with a name correspond- ing to the parameter name. If an array is used, the result must be the first element in the array. The resultelement, if there is one, is followed by array elements for each out or in/out parameter, in the order they are specified in the procedure signature. The fol- lowing example illustrates the response to the RPC invocation from the previous sec- tion. For this response, there is no special header targeted at the recipient. A result is returned indicating the status of the RPC invocation.

<? Xml version=’1.0’ ?> <env:Envelope xmlns:env=”http://www.w3.org/2002/06/soap-envelope”> <env:Body> <ns:buy xmlns:ns=”http://www.widgets.com/purchasing” env:encodingStyle=”http://www.w3.org/2002/06/soap- encoding”> <result xmlns=”http://www.w3.org/2002/06/soap- rpc”>okay</result> </ns:buy> </env:Body> </env:Envelope> Web Services 43

A SOAP output message may also contain a SOAP fault. SOAP faults are generated in response to errors or to carry other status information. This is the only body child

element that is defined by SOAP. The element must have a local name of faultand a

namespace of http://www.w3.org/2002.06/soap-envelope. Only one fault element may

appear in the message body. Child elements of codeand reasonare required within the

faultelement. Other child elements, nodeand role, and details are optional. Codeis a structure that consists of a value that designates the high-level fault and an optional

subcodethat provides additional details on the fault. Reasonis a human-readable repre- sentation of the fault. Nodeidentifies the SOAP node that encountered the fault. Role

identifies what role the node was operating in when the fault occurred. Finally, detail

carries application-specific fault information. SOAP defined faults are:

■■ Version mismatch.

■■ Inability to understand or process a mandatory header.

■■ A DTD was contained in the message.

■■ A data encoding was referenced that is not recognized by the processor.

■■ The message was incorrectly formatted or did not contain needed information.

■■ The message could not be processed for some reason other than that the mes-

sage was malformed or incomplete.

For SOAP RPC, additional fault codes have been defined. Fault codes can be extended to handle application specific needs.