Â¥Ö÷

SOAPÏê½â 3.1 SOAP 101 The SOAP specification defines three major parts: SOAP envelope specification The SOAP XML Envelope defines specific rules for encapsulating data being transferred between computers. This includes application-specific data, such as the method name to invoke, method parameters, or return values. It can also include information about who should process the envelope contents and, in the event of failure, how to encode error messages. Web Services Essentials 44 Data encoding rules To exchange data, computers must agree on rules for encoding specific data types. For example, two computers that process stock quotes need an agreed-upon rule for encoding float data types; likewise, two computers that process multiple stock quotes need an agreed-upon rule for encoding arrays. SOAP therefore includes its own set of conventions for encoding data types. Most of these conventions are based on the W3C XML Schema specification. RPC conventions SOAP can be used in a variety of messaging systems, including one-way and twoway messaging. For two-way messaging, SOAP defines a simple convention for representing remote procedure calls and responses. This enables a client application to specify a remote method name, include any number of parameters, and receive a response from the server. To examine the specifics of the SOAP protocol, we begin by presenting a sample SOAP conversation. XMethods.net provides a simple weather service, listing current temperature by zip code. (See Figure 3-1.) The service method, getTemp , requires a zip code string and returns a single float value. Figure 3-1. SOAP in action: connecting to the XMethods weather service 3.1.1 The SOAP Request The client request must include the name of the method to invoke and any required parameters. Here is a sample client request sent to XMethods: <?xml version='1.0' encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Body> <ns1:getTemp xmlns:ns1="urn:xmethods-Temperature" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <zipcode xsi:type="xsd:string">10016</zipcode> </ns1:getTemp> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Web Services Essentials 45 There are a couple of important elements to note here. First, the request includes a single mandatory Envelope element, which in turn includes a mandatory Body element. Second, a total of four XML namespaces are defined. Namespaces are used to disambiguate XML elements and attributes, and are often used to reference external schemas. In our sample SOAP request, we'll use namespaces to disambiguate identifiers associated with the SOAP Envelope (http://schemas.xmlsoap.org/soap/envelope/), data encoding via XML Schemas (http://www.w3.org/2001/XMLSchema-instance and http://www.w3.org/2001/XMLSchema), and application identifiers specific to XMethods (urn:xmethods-Temperature). This enables application modularity, while also providing maximum flexibility for future changes to the specifications. The Body element encapsulates the main "payload" of the SOAP message. The only element is getTemp , which is tied to the XMethods namespace and corresponds to the remote method name. Each parameter to the method appears as a subelement. In our case, we have a single zip code element, which is assigned to the XML Schema xsd:string data type and set to 10016. If additional parameters are required, each can have its own data type. 3.1.2 The SOAP Response Here is the SOAP response from XMethods: <?xml version='1.0' encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Body> <ns1:getTempResponse xmlns:ns1="urn:xmethods-Temperature" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <return xsi:type="xsd:float">71.0</return> </ns1:getTempResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Just like the request, the response includes Envelope and Body elements, and the same four XML namespaces. This time, however, the Body element includes a single getTempResponse element, corresponding to our initial request. The response element includes a single return element, indicating an xsd:float data type. As of this writing, the temperature for zip code 10016 is 71 degrees Fahrenheit. 3.2 The SOAP Message If you are eager to start coding your own SOAP applications, you may want to skip ahead to the Section 3.6 section, later in this chapter. Otherwise, the following section provides additional details regarding the SOAP specification itself. A one-way message, a request from a client, or a response from a server is officially referred to as a SOAP message. Every SOAP message has a mandatory Envelope element, an optional Header element, and a mandatory Body element. (See Figure 3-2.) Each of Web Services Essentials 46 these elements has an associated set of rules, and understanding the rules will help you debug your own SOAP applications. Figure 3-2. Main elements of the XML SOAP message 3.2.1 Envelope Every SOAP message has a root Envelope element. In contrast to other specifications, such as HTTP and XML, SOAP does not define a traditional versioning model based on major and minor release numbers (e.g., HTTP 1.0 versus HTTP 1.1). Rather, SOAP uses XML namespaces to differentiate versions. The version must be referenced within the Envelope element. For example: <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" The SOAP 1.1 namespace URI is http://schemas.xmlsoap.org/soap/envelope/, whereas the SOAP 1.2 namespace URI is http://www.w3.org/2001/09/soap-envelope. [1] If the Envelope is in any other namespace, it is considered a versioning error. [1] The exact value of the SOAP 1.2 envelope namespace will likely change to reflect the final date of the SOAP 1.2 release. The value, http://www.w3.org/2001/09/soap-envelope reflects the specification from September, 2001. 3.2.2 Header The optional Header element offers a flexible framework for specifying additional application-level requirements. For example, the Header element can be used to specify a digital signature for password-protected services; likewise, it can be used to specify an account number for pay-per-use SOAP services. Many current SOAP services do not utilize the Header element, but as SOAP services mature, the Header framework provides an open mechanism for authentication, transaction management, and payment authorization. The details of the Header element are intentionally open-ended, thereby providing maximum flexibility for application providers. The protocol does, however, specify two header attributes: Web Services Essentials 47 Actor attribute The SOAP protocol defines a message path as a list of SOAP service nodes. Each of these intermediate nodes can perform some processing and then forward the message to the next node in the chain. By setting the Actor attribute, the client can specify the recipient of the SOAP header. MustUnderstand attribute Indicates whether a Header element is optional or mandatory. If set to true ,[2] the recipient must understand and process the Header attribute according to its defined semantics, or return a fault. (See Table 3-2 for the MustUnderstand fault code.) [2] SOAP 1.1 uses integer values of 1/0 for the MustUnderstand attribute; SOAP 1.2 uses Boolean values of true/1/false/0. The Header specifies a payment account, which must be understood and processed by the SOAP server. Here is an example Header : <SOAP-ENV:Header> <ns1:PaymentAccount xmlns:ns1="urn:ecerami" SOAP-ENV: mustUnderstand="true"> orsenigo473 </ns1:PaymentAccount > </SOAP-ENV:Header> 3.2.3 Body The Body element is mandatory for all SOAP messages. As we have already seen, typical uses of the Body element include RPC requests and responses. 3.2.4 Fault In the event of an error, the Body element will include a Fault element. The fault subelements are defined in Table 3-1 and include the faultCode , faultString , faultActor , and detail elements. Predefined SOAP fault codes are defined in Table 3-2. The following code is a sample Fault. The client has requested a method named ValidateCreditCard , but the service does not support such a method. This represents a client request error, and the server returns the following SOAP response: <?xml version='1.0' encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode xsi:type="xsd:string">SOAP-ENV:Client</faultcode> <faultstring xsi:type="xsd:string"> Failed to locate method (ValidateCreditCard) in class (examplesCreditCard) at /usr/local/ActivePerl-5.6/lib/ site_perl/5.6.0/SOAP/Lite.pm line 1555. </faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Web Services Essentials 48 Table 3-1. SOAP fault subelements Element name Description faultCode A text code used to indicate a class of errors. See Table 3-2 for a listing of predefined fault codes. faultString A human-readable explanation of the error. faultActor A text string indicating who caused the fault. This is useful if the SOAP message travels through several nodes in the SOAP message path, and the client needs to know which node caused the error. A node that does not act as the ultimate destination must include a faultActor element. detail An element used to carry application-specific error messages. The detail element can contain child elements, called detail entries.    Êղؠ  ·ÖÏí   ¶¥(0)