- The Basic Structure of SOAP
- SOAP Namespaces
- SOAP Headers
- The SOAP Body
- SOAP Messaging Modes
- SOAP Faults
- SOAP over HTTP
- Wrapping Up
This chapter is from the book
This chapter is from the book
This chapter is from the book
Except in the case of fault messages, SOAP does not specify the contents of the Body element (although it does specify the general structure of RPC-type messages). As long as the Body contains well-formed XML, the application-specific data can be anything. The Body element may contain any XML element or it can be empty.
Although SOAP supports four modes of messaging (RPC/Literal, Document/ Literal, RPC/Encoded, and Document/Encoded) the BP permits the use of RPC/ Literal or Document/Literal only. The RPC/Encoded and Document/Encoded modes are explicitly prohibited.BP
A messaging mode is defined by its messaging style (RPC or Document) and its encoding style. There are two common types of encoding used in SOAP messaging: SOAP encoding as described in Section 5 of the SOAP 1.1 specification, and Literal encoding. SOAP encoding is not supported by WS-I-conformant Web services because it causes significant interoperability problems.BP The term “Literal” means that the XML document fragment can be validated against its XML schema.
4.5.1 Document/Literal
In the Document/Literal mode of messaging, a SOAP Body element contains an XML document fragment, a well-formed XML element that contains arbitrary application data (text and other elements) that belongs to an XML schema and namespace separate from the SOAP message's.
For example, a set of XML elements that describes a purchase order, embedded within a SOAP message, is considered an XML document fragment. The purchase-order SOAP message, which is used as an example throughout this chapter, is a Document/Literal message. Listing 4-15 shows the complete purchase-order SOAP message, which contains the purchaseOrder XML document fragment.
Listing 4-15 A Document-Style SOAP Message
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mi="http://www.Monson-Haefel.com/jwsbook/message-id"
xmlns:proc="http://www.Monson-Haefel.com/jwsbook/processed-by">
<soap:Header>
<!-- Header blocks go here -->
</soap:Header>
<soap:Body>
<po:purchaseOrder orderDate="2003-09-22"
xmlns:po="http://www.Monson-Haefel.com/jwsbook/PO">
<po:accountName>Amazon.com</po:accountName>
<po:accountNumber>923</po:accountNumber>
...
<po:book>
<po:title>J2EE Web Services</po:title>
<po:quantity>300</po:quantity>
<po:wholesale-price>24.99</po:wholesale-price>
</po:book>
</po:purchaseOrder>
</soap:Body>
</soap:Envelope>
4.5.2 RPC/Literal
The RPC/Literal mode of messaging enables SOAP messages to model calls to procedures or method calls with parameters and return values. In RPC/Literal messaging, the contents of the Body are always formatted as a struct. An RPC request message contains the method name and the input parameters of the call. An RPC response message contains the return value and any output parameters (or a fault). In many cases, RPC/Literal messaging is used to expose traditional components as Web services. A traditional component might be a servlet, stateless session bean, Java RMI object, CORBA object, or DCOM component. These components do not explicitly exchange XML data; rather, they have methods with parameters and return values.
For example, Monson-Haefel Books has a JAX-RPC service endpoint (a J2EE Web Service endpoint) called BookQuote that Monson-Haefel's sales force uses. The remote interface to the BookQuote looks like this:
package com.jwsbook.soap;
import java.rmi.RemoteException;
public interface BookQuote extends java.rmi.Remote {
// Get the wholesale price of a book
public float getBookPrice(String ISBN)
throws RemoteException, InvalidISBNException;
}
The getBookPrice() method declares a parameter in the form of an ISBN (International Standard Book Number), a unique string of characters assigned to every retail book. When you invoke this method with a proper ISBN, the Web service will return the wholesale price of the book identified.
This JAX-RPC service endpoint can use the RPC/Literal mode of messaging. The Web service uses two SOAP messages: a request message and a reply message. The request message is sent from an initial sender to the Web service and contains the method name, getBookPrice, and the ISBN string parameter. The reply message is sent back to the initial sender and contains the price of the book as a float value. Listing 4-16 shows the SOAP request message for the BookQuote Web service.
Listing 4-16 An RPC/Literal SOAP Request Message
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mh="http://www.Monson-Haefel.com/jwsbook/BookQuote">
<soap:Body>
<mh:getBookPrice>
<isbn>0321146182</isbn>
</mh:getBookPrice>
</soap:Body>
</soap:Envelope>
Listing 4-17 shows the corresponding response.
Listing 4-17 An RPC/Literal SOAP Response Message
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mh="http://www.Monson-Haefel.com/jwsbook/BookQuote" >
<soap:Body>
<mh:getBookPriceResponse>
<result>24.99</result>
</mh:getBookPriceResponse>
</soap:Body>
</soap:Envelope>
Unlike Document/Literal messaging, which makes no assumptions about the type and structure of elements contained in the Body of the message—except that the document fragment adheres to some XML schema—RPC/Literal messages carry a simple set of arguments. RPC-style messaging is a common idiom in distributed technologies, including EJB, CORBA, DCOM, and others, so SOAP defines a standard XML format for RPC-style messaging, called RPC/Literal. The RPC/Literal mode of messaging specifies how methods and their arguments (parameters and return values) are represented within the Body element of a SOAP message.
It's important to understand that RPC/Literal and Document/Literal may be indistinguishable from the perspective of a developer using tools like JAX-RPC, because JAX-RPC can present procedure-call semantics for both RPC/Literal and Document/Literal. A few people question the usefulness of RPC/Literal in the first place. Why use it when you can use Document/Literal, which is arguably simpler to implement in some respects, and can exploit XML schema validation? This book covers both models without taking sides on this issue.
4.5.3 Messaging Modes versus Messaging Exchange Patterns
It's easy to confuse Document/Literal and RPC/Literal modes of messaging with the One-Way and Request/Response message exchange patterns (MEPs), but the concepts are distinctly different. When you say a messaging mode is Document/ Literal or RPC/Literal, you are usually describing the payload of the SOAP message: an XML document fragment or an XML representation of the parameters and return values associated with a remote procedure call. In contrast, One-Way and Request/Response MEPs refer to the flow of messages, not their contents. One-Way messaging is unidirectional, Request/Response is bi-directional. You can use the Document/Literal mode of messaging with either One-Way or Request/Response messaging. The RPC/Literal mode of messaging can also be used with either MEP, although it's usually used with Request/Response messaging.
Figure 4-8 shows the response message flows (the gray arrows) as optional in both document-style and RPC-style messaging.
)
Figure 4-8. Using Document/Literal and RPC/Literal with One-Way and Request/Response Messaging
4.5.4 Other Messaging Modes
Two other modes of messaging can be used with SOAP, RPC/Encoded and Document/Encoded, but the BP frowns on them, for two reasons: XML schema makes them obsolete, and they introduce a number of difficult interoperability problems.BP
RPC/Encoded actually receives more attention from SOAP than any other messaging mode. It attempts to define a mapping between common RPC semantics and programmatic types on one hand and XML on the other. An entire section of the SOAP 1.1 Note (the infamous Section 5) is devoted to explaining SOAP encoding. RPC/Encoded relies on built-in XML schema types, but it is designed to represent a graph of objects. XML schema organizes data into a tree, which is not nearly as flexible as an object graph. Although RPC/Encoded messaging was popular at first, its overall complexity and the interoperability problems it has caused have convinced most SOAP specialists to avoid it. You can accomplish pretty much the same results using the RPC/Literal or Document/Literal modes of messaging, with the added bonuses of better interoperability and conformance with the XML schema. It's likely, however, that you will encounter legacy Web service implementations that continue to use RPC/Encoded messaging despite its lack of support from the WS-I. To help you understand and work with these services, Appendix D: SOAP RPC/Encoded provides detailed coverage of this messaging mode.
Document/Encoded messaging applies SOAP encoding as defined in Section 5 of the SOAP 1.1 Note to document-style messaging. This mode of messaging is rarely, if ever, used in practice because Document/Literal messaging is much simpler, and interoperable. Document/Encoded messaging is not supported in J2EE Web services, so it's given no more consideration in this book.