Date: Fri, 29 Mar 2024 06:29:01 +0000 (UTC) Message-ID: <1547452749.448.1711693741360@library.aws.roguewave.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_447_536049646.1711693741359" ------=_Part_447_536049646.1711693741359 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
SOAP stands for S= imple Object Access Protocol.
SOAP is a type of on-the-wire= formatting that can encapsulate entire object trees as XML text. It is typ= ically used with an HTTP-based transport to call an operation in a web = ;servic= e (i.e. through a WSDL). SOAP is a very open spe= cification and how a SOAP message is structured is largely a func= tion of its usage and environment.
All SOAP messages, thoug= h, follow a similar format. SOAP currently has two versions of it= s specification out, 1.1 and 1.2. 1.2 is a popular choice, but as it has no= t yet been fully adopted by the industry, this article will stick with = ;SOAP= span> 1.1 for its examples.
The base SOAP element is= the Envelope. This element can hold an optional Headers elem= ent, which can in turn hold any number or kind of child elements. The&= nbsp;Envelope then must either have a Body or a Fault. Faults are only allowed in a = response. The Body element can be either in a request or= a response.
The Headers ele= ment contains optional headers for the service. Only one SOAP&nbs= p;header is defined by the SOAP specification: the mustU= nderstand header, which, if true, states all suppli= ed headers must be parsed and validated by the receiving service. Al= l other headers are defined by the specific application.
Basically the Body <= /em>element contains the data for the web service. For requests, it ca= n contain which operation to call, and it always holds all of the data need= ed for the call. For responses, it can contain the operation that was calle= d and will always contain the return information when the operation complet= ed successfully. Faults, on the other hand, are present when = an error or exception occurs. This can be anything from an operation not be= ing found to invalid data to internal system problems.
The Body element can con= tain any child element, but usually only one child element is allowed. The = child element can be formatted in a number of different ways, depending on = the scenario (see below).
The fault element MUST contain at = least the fault code, the fault string, and the detail, and it MAY contain = the fault actor. SOAP defines a subset of fault codes to use, but= any valid qualified name can be used. The two most commonly used are = soa= p:Client and soap:Server errors. <= em>soap= :Client errors describe a problem with the received m= essage or the client communication. soap:Server errors d= escribe a problem which occurred on the server during execution of the = ;servic= e. In any case, the fault code is a fully qualified name which = is composed of a namespace prefix (that must already be defined) and a loca= l name (which must be a valid name within that namespace).
For example, these fault codes are= invalid:
<faul= tcode>ClientError</faultcode> <faultcode>http://mysite.com/myURI::ClientError</faultcode> <faultcode>NS1:ClientError</faultcode> // Where NS1 = is not defined as a valid namespace prefix
These are valid:
<faul= tcode>SOAP:Client</faultcode> // Where SOAP i= s declared in the envelope to be the SOAP namespace <faultcode xmlns:ns1=3D"myURI">ns1:ClientError</faultcode>
The fault string is any summary of= the error, and the fault actor is a URI defining the source of the fault.<= /span>
The detail is essentially an eleme= nt that specifies detail about the fault, and generally contains an XML ele= ment that matches one of the fault messages specified in the corr= esponding operation's definition (see Operations in the Guide: WSDL article). It is almost al= ways present, although it can be omitted in certain circumstances (e.g. if = the fault was encountered outside the SOAP Body element), and it = can be empty.
SOAP is very often sent as an= HTTP payload. This uses standard HTTP (with its benefits and limitations) = to send the SOAP message as a text payload. The standard HTTP req= uest looks like:
<meth= od> <location> HTTP/<version> <headers> ... <payload>
and t= he standard response:
HTTP/<= ;version> <status code> <reason> <headers> ... <payload>
The request <method>=
; is usually POST or GET (although other methods are available). =
The <location> maps to the address URI in the
An example HTTP request with a&nbs= p;SOAP<= /span> payload might be:
POST&nbs= p;http://server:8080/wsdl/address HTTP/1.1 Content-Length: 2080 Content-Type: text/xml Host: server:8080 SOAPAction: testOperation <SOAP:Envelope xmlns:SOAP=3D"http://schemas.xmlsoap.org/soap/envelope/"&= gt;<SOAP:Body>...
An example HTTP response to the ab= ove request might look like:
HTTP/1.1= 200 OK Content-Length: 210 Content-Type: text/xml <SOAP:Envelope xmlns:SOAP=3D"http://schemas.xmlsoap.org/soap/envelope/"&= gt;<SOAP:Body>...
<See the HTTP specification for= more information on message formats and types>.
The only other peculiarity with&nb= sp;SOAP= over HTTP is that any error in processing the SOAP r= equest will result in a SOAP fault sent and an HTTP status code o= f 500 (Internal Server Error). Any errors with the SOAP request w= ill result in a response with an HTTP status code of 500 and a SOAP&nb= sp;fault containing the error information. All other HTTP-related erro= rs will be sent back with the appropriate HTTP status code as defined by th= e HTTP specification.
The most common usage of
SOAP messages are categorized=
into two main styles: document and RPC. Document styles are based around s=
ending XML documents back and forth while RPC (Remote Pr=
ocedure Call) messages are based around sending function calls =
in and getting a return value. To further complicate matters, message parts=
(as described above) can either be a type or an
Here are the five different <= span class=3D"glossaryItem _tooltip_custom_glossary tooltipstered">SOAP styes:
Document style SOAP mess= ages are based around XML documents. The SOAP Body element, in ef= fect, becomes the root element of the document. This means that document st= yle messages are really not supposed to have more than one part, because the message is supposed to be a document, no= t a parameter list.
If the part is = a type, then the SOAP Body element becomes that&nbs= p;type. For the XSD and WSDL message:
XSD
<comp= lexType name=3D"foo"> <sequence> <element name=3D"sub1" type=3D"xsd:integer"/> <element name=3D"sub2" type=3D"xsd:string"/> </sequence> </complexType> <element name=3D"MyElement" type=3D"foo"/>
WSDL Message section<= /span>
<mess= age name=3D"docTypeIn"> <part name=3D"doesntMatter" type=3D"fooType"/> </message>
WSDL binding section:=
<bind= ing name=3D"MyBinding" type=3D"MyPortType"> <soap:binding style=3D"document" transport=3D"http://schemas.xmlso= ap.org/soap/http"/> <operation name=3D"oper1"> <soap:operation soapAction=3D"oper1"/> <input> <soap:body use=3D"literal"/> </input> <output> <soap:body use=3D"literal"/> </output> </operation> </binding>
SOAP Request= strong>
&l= t;soap:Body> <sub1>42</sub1> <sub2>The answer to everything</sub2> </soap:Body>
The response would look similar, e= xcept with the output message instead. Note that the SOAP Bod= y element becomes the fooType type and since t= he fooType type holds a sequence of two elements: su= b1 and sub2, the SOAP Body will hold= two elements: sub1 and sub2.
If the part is = an element, then the SOAP Body will contain that el= ement as a child. For the above XSD and this WSDL message section= (the WSDL binding section is the same):
<mess= age name=3D"docTypeIn"> <part name=3D"doesntMatter" element=3D"MyElement"/> </message>
The resulting document-style = SOAP message would look like:
&l= t;soap:Body> <MyElement> <sub1>42</sub1> <sub2>The answer to everything</sub2= > </MyElement> </soap:Body>
The element nam= e will be printed as a fully qualified name. In this example <M= yElement> is a simple local name with no namespace, but if a n= amespace were present, it would get printed as <ns0:MyElement x= mlns:ns0=3D"myURI">. In general, the subelements of this parent ele= ment are NOT fully qualified. There is a flag in the XML Schema specificati= on that says to qualify all children of all elements, but it is not common = to use it.
Note that with multiple p= arts, one COULD define different elements and those elements could be = placed in the Body in sequence. This is usually what hap= pens when multiple parts are specified for document-styl= e, element messages, but still bear in mind that this is not standard nor a= dvised. Also, note that the part name doesn't matter in the s= lightest. There is no place that the part name gets prin= ted in document-style SOAP messages, not even with elements.
There is one more form of document= -style SOAP messages called document-wrapped. If yo= u look at the above messages, you will notice that there is no indication o= f which operation to call. Looking at the WSDLs above, t= here are two pieces of information necessary to locate a web service: = the URI or "location", and the name of the operation. The URI= is provided by the transport protocol, in this case the HTTP location in t= he HTTP request line. However, the operation name is still mi= ssing. As you will see below with RPC, the operation nam= e CAN be sent in the SOAP payload, but another common (and usuall= y necessary for document-style messages) way to transmit the opera= tion name via the SOAPAction header in the HTT= P header section.
This can be cumbersome and prone t= o error, because we are now relying on the transport to relay the informati= on about which specific operation to call. The transport directing us to th= e proper WSDL port makes a lot of sense, but after that, the tran= sport's duties are finished. However, as you will see below, RPC style = ;SOAP= span> messages have their own drawbacks. Fortunately there is a pretty= clever way of getting the best of both worlds here.
If we take a document-style <= span class=3D"glossaryItem _tooltip_custom_glossary tooltipstered">SOAP message with an element part, and make sure to name = the part the exact operation name, th= en we, in effect, transmit the operation as part of the&= nbsp;SO= AP message, making the SOAPAction HTTP heade= r unnecessary. This style of SOAP message is really document-styl= e with an element part, but it is commonly referred to as&nbs= p;doc-wrapped and is most commonly used in .NET applications.=
Here's an example of doc-= wrapped.
XSD:
<comp= lexType name=3D"operationParams"> <sequence> <element name=3D"param1" type=3D"xsd:integer"/&g= t; <element name=3D"param2" type=3D"xsd:string"/>= ; </sequence> </complexType> <element name=3D"doTestOperation" type=3D"operationParams"/> <element name=3D"doTestOperationResponse" type=3D"xsd:integer"/>
WSDL message section:
<mess= age name=3D"doTestOperationIn"> <part name=3D"doesntMatter" element=3D"doTestOperation"/> </message> <message name=3D"doTestOperationOut"> <part name=3D"doesntMatter" element=3D"doTestOperationRespon= se"/> </message>
WSDL binding section:
<bind= ing name=3D"MyBinding" type=3D"MyPortType"> <soap:binding style=3D"document" transport=3D"http://schemas.xmlso= ap.org/soap/http"/> <operation name=3D"oper1"> <soap:operation soapAction=3D"oper1"/> <input> <soap:body use=3D"literal"/> </input> <output> <soap:body use=3D"literal"/> </output> </operation> </binding>
SOAP Request:
<soap= :Body> <doTestOperation> <param1>42</param1> <param2>The answer to everything</pa= ram2> </doTestOperation> </soap:Body>
SOAP Response:=
&l= t;soap:Body> <doTestOperationResponse> 42 </doTestOperationResponse> </soap:Body>
The SOAPAction header= can be omitted (but, if present, it MUST be equal to the operation name, in this case: doTestOperation, and the parameters to t= his operation are easy to specify and read. In effect, this style gets many= of the benefits of RPC without a lot of the drawbacks (we'll cover RP= C in the next section). For this reason, it is a very common SOAP style, used in many applications (as noted= , most commonly in .NET).
So, we've covered the document sty= les and the drawbacks. Basically, document styles are based around sending = XML documents, whereas web services in general tend to represent function c= alls. These documents have problems representing simple function parameters= and there is also the problem of needing a transport level header to speci= fy which function to invoke. Document-style messages can also only specify = one part and send a single XML document in the message.<= /span>
RPC, on the other hand, was create= d to represent function calls. RPC-style SOAP messages contain a = wrapping element that specifies the operation name, and that element contai= ns one child element for each of the function parameters. This allows multi= ple parts to be specified as either; simple types, complex types,= or elements. It also means that the SOAPAction header i= s unnecessary and can be omitted with RPC-style messages.
Both RPC with typed parts= and with element parts have the same structur= e, with the only difference being the information under the part&n= bsp;element.
Here is the general format for RPC= -style SOAP messages.
XSD:
<comp= lexType name=3D"fooType"> <sequence> <element name=3D"sub1" type=3D"xsd:integer"/> <element name=3D"sub2" type=3D"xsd:string"/> </sequence> </complexType> <element name=3D"MyElement" type=3D"fooType"/>
WSDL message section:=
<mess= age name=3D"doTestOperationIn"> <part name=3D"part1" element=3D"doTestOperation"/> <part name=3D"part2" type=3D"doTestOperation"/> </message> <message name=3D"doTestOperationOut"> <part name=3D"result" type=3D"xsd:string"/> </message>
WSDL binding section:=
<bind= ing name=3D"MyBinding" type=3D"MyPortType"> <soap:binding style=3D"rpc" transport=3D"http://schemas.xmls= oap.org/soap/http"/> <operation name=3D"oper1"> <soap:operation soapAction=3D"oper1"/> <input> <soap:body use=3D"literal" namespace= =3D"wrapperURIIn"/> </input> <output> <soap:body use=3D"literal" namespace= =3D"wrapperURIOut"/> </output> </operation> </binding>
SOAP Request:<= /strong>
&l= t;soap:Body> <ns1:oper1 xmlns:ns1=3D"wrapperURIIn"> <part1> <MyElement> <sub1>42</su= b1> <sub2>The answe= r to everything</sub2> </MyElement> </part1> <part2> <sub1>76</sub1> <sub2>Trombones leading the= parade</sub2> </part2> </ns1:oper1> </soap:Body>
SOAP Response:=
&l= t;soap:Body> <ns1:oper1Response xmlns:ns1=3D"wrapperURIOut"> <result>34</result> </ns1:oper1> </soap:Body>
You'll notice that, like document-= style, the part with the element contains the fully-qual= ified element, while the part that's a type&nbs= p;becomes the specified type.
You'll also notice that RPC, unlik=
e document-style, treats web service calls as functions with para=
meters and return values. Whereas document-style just passes around documen=
ts for requests and responses, RPC passes around function name, parameters,=
and result. The operation name in the request is qualif=
ied by a namespace specified by the SOAP input body declaration i=
n the WSDL as the namespace attribute. By convention, the
There is one more "axis" to consid=
er when formatting and parsing a SOAP message: encoding. This is =
specified in the SOAP input and output body tags in the
The use of any encoding is not WS-= I compliant because there isn't any way to standardize on encodings (becaus= e they are WSDL extensions by their definition). This doesn't mea= n that it is illegal in WSDL to use encodings, but in real-world = applications, its use is limited due to the lack of standardization.=
Note: Typed parts must refer to XSD-defined types (xsd:simpleT= ype or xsd:complexType definitions). Element parts must refer= to an XSD-defined element (xsd:element definition).
So, the question becomes, which style should we use? The different = styles have their pros and cons. There is also the WS-I profile to consider= . Although this profile isn't a "specification" per se, it is essentially a= standard that WSDL/SOAP users can rally around. The SOAP and WSDL&nb= sp;specifications are somewhat vague in places and downright ambiguous in o= thers (for example, whether or not multiple parts are al= lowed in doc-literal isn't clearly stated in the WSDL or SOAP sp= ecifications). The WS-I profile is a way to answer some of these questions = by limiting the types of WSDL an= d SOAP messages allowed in order= to clear up ambiguities and irregularities. WS-I compliance is by no means= necessary, but you'll find that the WS-I compliant styles are more common = in real-world applications.
Benefits
Drawbacks
Benefits
Drawbacks
Benefits
Drawbacks<= /p>
Benefits= p>
Drawbacks<= /p>
Benefits= p>
Drawbacks<= /p>
Each of the above styles (except f= or document/encoded which is never used) are all common. Doc-wrapped is new= er but it is definitely gaining ground in standard usage because it gains t= he benefits of RPC and can still be validated as a full document. RPC messa= ges are useful when mapping web service calls to C++ or Java meth= ods, because they can be overloaded with different parameters, and the para= meters are pretty easy to match up to C++ and Java function arguments. Docu= ment-literal can be useful when passing full XML documents around to web&nb= sp;serv= ice implementations that don't implement function calls (BPEL, = HTTP servlets, etc.). It is also useful when you need overloaded functions = but only have one parameter, or you don't want the extra overhead of the ex= tra RPC elements.
WS-I Profile 1.2: http://www.ws-i.org/= Profiles/BasicProfile-1.2.html
WSDL 1.1 spec: http://www= .w3.org/TR/wsdl
SOAP 1.1 spec: http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
XSD data types spec: ht= tp://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html
Guide to choosing WSDL styles= : http://www-128.ibm= .com/developerworks/webservices/library/ws-whichwsdl/