[Web Service] SOAP & SOAP Connection

<SOAP>

Two vendor-neutral standards for accessing web services are REST and SOAP.
REST - Representational State Transfer.
SOAP - Simple Object Access Protocol.

---

---

Introduction

• Simple Object Access Protocol
• is a protocol specification for exchanging structured information in the implementation of Web Services in computer networks. 
• relies on XML Information Set for its message format, and usually relies on other Application Layer protocols, most notably Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission. 
• is platform independent.
• is language independent.
• is simple and extensible.
• Unlike REST, it's a W3C-recommended protocol for web services.
• SOAP is most often used with HTTP to take advantage of the existing HTTP framework. This also enables calls to bypass firewalls because they pass on the HTTP port - port 80. However, SOAP can also use TCP.

---

SOAP Syntax

A SOAP message is an ordinary XML document containing the following elements:

• An Envelope element that identifies the XML document as a SOAP message
• is the root element of a SOAP message.
• This element defines the XML document as a SOAP message.
• [empty] A Header element that contains header information
• contains application-specific information (like authentication, payment, etc) about the SOAP message.
• All immediate child elements of the Header element must be namespace-qualified.
• A Body element that contains call and response information
• actual SOAP message
• [optional] A Fault element containing errors and status information for a SOAP message.

Here are some important syntax rules:

• A SOAP message MUST be encoded using XML
• A SOAP message MUST use the SOAP Envelope namespace
• A SOAP message MUST use the SOAP Encoding namespace
• A SOAP message must NOT contain a DTD reference
• A SOAP message must NOT contain XML Processing Instructions

For example,
A SOAP  request

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"

soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

 <soap-env:Header/>
    <soap-env:Body>
        <cal:schedule xmlns:cal="http://www.example.com/calendar">
            <cal:newitem>
                <cal:eventDate>4/10/2002</cal:eventDate>
                <cal:title>Fun With Frogs</cal:title>
            </cal:newitem>
        </cal:schedule>
    </soap-env:Body>
</soap-env:Envelope>

*Notes:
Header element
soap:encodingStyle attribute is optional for SOAP.

Fault element

If a Fault element is present, it must appear as a child element of the Body element. A Fault element can only appear once in a SOAP message.

The SOAP Fault element has the following sub elements:

Sub Element	Description
<faultcode>	A code for identifying the fault
<faultstring>	A human readable explanation of the fault
<faultactor>	Information about who caused the fault to happen
<detail>	Holds application specific error information related to the Body element

SOAP Fault Codes The faultcode values defined below must be used in the faultcode element when describing faults:

Error	Description
VersionMismatch	Found an invalid namespace for the SOAP Envelope element
MustUnderstand	An immediate child element of the Header element, with the mustUnderstand attribute set to "1", was not understood
Client	The message was incorrectly formed or contained incorrect information
Server	There was a problem with the server so the message could not proceed

---

The HTTP Binding /Protocol 

---

SOAP Example

A SOAP Request
POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Body xmlns:m="http://www.example.org/stock">
  <m:GetStockPrice>
    <m:StockName>IBM</m:StockName>
  </m:GetStockPrice>
</soap:Body>

</soap:Envelope>

A SOAP Response
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Body xmlns:m="http://www.example.org/stock">
  <m:GetStockPriceResponse>
    <m:Price>34.5</m:Price>
  </m:GetStockPriceResponse>
</soap:Body>

</soap:Envelope>

---

---

<SOAP Connection>

A connection is required to send and receive all SOAP messages. The connection can go to a messaging provider or a particular destination.


The JAXM API provides the class and interface to represent two kinds of connections:

• javax.xml.soap.SOAPConnection—a connection from the sender directly to the receiver (a point-to-point connection)
• javax.xml.messaging.ProviderConnection—a connection to a messaging provider

A SOAPConnection is a point-to-point connection for sending messages directly to a remote party.
A SOAPConnection object, which represents a point-to-point connection, is simple to create and use. You do not have to do any configuration to use a SOAPConnection object because it does not need to run in a servlet container (like Tomcat) or in a J2EE server. It is the only way for a client to have a connection without a service provider.

A ProviderConnection object represents a connection to a messaging provider. (The next section explains more about messaging providers.) When you send a message via a ProviderConnection object, the message goes to the messaging provider. The messaging provider forwards the message, following the message's routing instructions, until the message gets to the ultimate recipient's messaging provider, which in turn forwards the message to the ultimate recipient.

A messaging provider keeps track of messages and routes them to the correct destination or destinations. It is a service that handles the transmission and routing of messages.

---

---

Reference 
http://www.cnblogs.com/chenying99/archive/2013/05/23/3094128.html

http://www.w3schools.com/Webservices/ws_soap_httpbinding.asp