SOAP URI

 

At http://www.fh-wedel.de/~si/seminare/ws00/Ausarbeitung/6.soap/soap07.htm one read:

The SOAPAction field of the HTTP-Header identifies the purpose of the SOAP-HTTP request. The value of this field is a URI without special requirements due to presence or format. A HTTP client which sends a SOAP request has to use this header field.

Examples:

•  SOAPAction: "http://www.aktien.de/transaktion#buy"
• SOAPAction: "doit.exe"
• SOAPAction: ""
• SOAPAction:

The presence of the SOAPAction field of the HTTP header can be used by firewalls to filter SOAP requests.

The field value of an empty String means the purpose of the request is to be determined from HTTP request URI itself (examples line 3).

No field value at all (examples line 4) means there is no hint for the purpose of the message provided.

Links

http://stackoverflow.com/questions/2262781/soap-action-wsdl

https://forums.oracle.com/forums/thread.jspa?messageID=7009298

Difference Between Document Style and RPC Style WebService

A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A SOAP binding can also have an encoded use or a literal use. This gives you four style/use models:

1. RPC/encoded
2. RPC/literal
3. Document/encoded
4. Document/literal

The terminology here is very unfortunate: RPC versus document. These terms imply that the RPC style should be used for RPC programming models and that the document style should be used for document or messaging programming models. That is not the case at all. The style has nothing to do with a programming model. It merely dictates how to translate a WSDL binding to a SOAP message. Nothing more. You can use either style with any programming model.

the terms encoded and literal are only meaningful for the WSDL-to-SOAP mapping, though, at least here, the traditional meanings of the words make a bit more sense.

See basically there is difference in WSDL and SOAP messages. Now we know there are different parts in WSDL file , the specific pasts having difference are

1.  <message&gt: and 
2. <binding&gt: 

here is how

A message part may declare either a type attribute or an element attribute, but not both. Which to use depends on the kind of messaging you're doing. If you're using RPC-style messaging, the part elements must use the type attribute; if you're using document-style messaging, the part elements must use the element attribute
     RPC Style 
<definitions name="BookPrice" ...>
  ...
  <message name="GetBulkBookPriceRequest">
    <part name="isbn" type="xsd:string"/>
    <part name="quantity" type="xsd:int"/>
  </message>
  <message name="GetBulkBookPriceResponse">
    <part name="price" type="mh:prices" />
  </message>
  ...
</definitions>
Document Style
<message name="SubmitPurchaseOrderMessage">
    <part name="order" element="mh:purchaseOrder" />
  </message>

The soapbind:binding and soapbind:body elements are responsible for expressing the SOAP-specific details of the Web service. 
• soapbind:binding tells us that the "messaging style" is RPC (or document) and that the "network application" protocol is HTTP. 
• The soapbind:body element tells us that both the input and output messages use literal encoding.
You may have noticed that attributes of the soapbind:body element change depending on whether you use RPC- or document-style messaging. The soapbind:body element has four kinds of attributes: 
1. use :- required to be literal ( ?? can it be document?? ) if absent default=literal
2. namespace :- In "rpc"-style messages, the namespace attribute must be specified with a valid URI. In document style it must not be specified.
3. part :- specifies which part elements in the message definition are being used. necessary only if you are using a subset of the part elements declared by a message
4. and encodingStyle : - never used

RPC style specify the namespace attribute in the soapbind:body. In contrast, document-style messages must not specify the namespace attribute in the soapbind:body element. The namespace of the XML document fragment is derived from its XML schema

Example of a rpc style

<?xml version="1.0" encoding="UTF-8"?>

<definitions name="BookQuoteWS"

 targetNamespace="http://www.Monson-Haefel.com/jwsbook/BookQuote"

 xmlns:mh="http://www.Monson-Haefel.com/jwsbook/BookQuote"

 xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"

 xmlns:xsd="http://www.w3.org/2001/XMLSchema"

 xmlns="http://schemas.xmlsoap.org/wsdl/">

  ...

  <!-- binding tells us which protocols and encoding styles are used -->

  <binding name="BookPrice_Binding" type="mh:BookQuote">

    <soapbind:binding style="rpc"

     transport="http://schemas.xmlsoap.org/soap/http"/>

    <operation name="getBookPrice">

      <soapbind:operation style="rpc"

       soapAction=

       "http://www.Monson-Haefel.com/jwsbook/BookQuote/GetBookPrice"/>

        <input>

          <soapbind:body use="literal"

           namespace="http://www.Monson-Haefel.com/jwsbook/BookQuote" />

        </input>

        <output>

          <soapbind:body use="literal"

           namespace="http://www.Monson-Haefel.com/jwsbook/BookQuote" />

        </output>

    </operation>

  </binding>

  ...

</definitions>

In contrast, document-style messages must not specify the namespace attribute in the soapbind:body element. The namespace of the XML document fragment is derived from its XML schema

<!-- binding tells us which protocols and encoding styles are used -->

<binding name="SubmitPurchaseOrder_Binding" type="mh:SubmitPurchaseOrder">

  <soapbind:binding style="document"

   transport="http://schemas.xmlsoap.org/soap/http"/>

  <operation name="submit">

    <soapbind:operation style="document"/>

      <input>

        <soapbind:body use="literal" />

      </input>

      <output>

        <soapbind:body use="literal" />

      </output>

  </operation>

</binding>

As an example lets consider one java method in all four ways

public void myMethod(int x, float y);
   

RPC Encoded

<message name="myMethodRequest">     <part name="x" type="xsd:int"/>     <part name="y" type="xsd:float"/> </message> <message name="empty"/>   <portType name="PT">     <operation name="myMethod">         <input message="myMethodRequest"/>         <output message="empty"/>     </operation> </portType>   <binding .../> 

Now invoke this method with "5" as the value for parameter x and "5.0" for parameter y. That sends a SOAP message which looks something like below.

 RPC/encoded SOAP message for myMethod

 <soap:envelope>

    <soap:body>

        <myMethod>

            <x xsi:type="xsd:int">5</x>

            <y xsi:type="xsd:float">5.0</y>

        </myMethod>

    </soap:body>

</soap:envelope>

Strengths

• The WSDL is about as straightforward as it's possible for WSDL to be.
• The operation name appears in the message, so the receiver has an easy time dispatching this message to the implementation of the operation.

Weakness

·         The type encoding info (such as xsi:type="xsd:int") is usually just overhead which degrades throughput performance.

·         You cannot easily validate this message since only the 5 and 5.0 lines contain things defined in a schema; the rest of the soap:body contents comes from WSDL definitions.

·         Although it is legal WSDL, RPC/encoded is not WS-I compliant.

RPC Literal

The RPC/literal WSDL for this method looks almost the same as the RPC/encoded WSDL (see Listing 4). The use in the binding is changed from encoded to literal. That's it.

 RPC/literal WSDL for myMethod

<message name="myMethodRequest">

    <part name="x" type="xsd:int"/>

    <part name="y" type="xsd:float"/>

</message>

<message name="empty"/>

<portType name="PT">

    <operation name="myMethod">

        <input message="myMethodRequest"/>

        <output message="empty"/>

    </operation>

</portType>

<binding .../> 

<!-- I won't bother with the details, just assume it's RPC/literal. -->

What about the SOAP message for RPC/literal (see Listing 5)? Here there is a bit more of a change. The type encodings have been removed.

 RPC/literal SOAP message for myMethod

<soap:envelope>

    <soap:body>

        <myMethod>

            <x>5</x>

            <y>5.0</y>

        </myMethod>

    </soap:body>

</soap:envelope>

Strengths

·         The WSDL is still about as straightforward as it is possible for WSDL to be.

·         The operation name still appears in the message.

·         The type encoding info is eliminated.

·         RPC/literal is WS-I compliant.

Weaknesses

·         You still cannot easily validate this message since only the < x ...  >5< / x > and < y ... > 5.0< / y > lines contain things defined in a schema; the rest of the soap:body contents comes from WSDL definitions.

Document Encoded

Nobody follows this style , it's not WSI compliant

Document Literal

The WSDL for document/literal changes somewhat from the WSDL for RPC/literal. The differences are highlighted in bold 

Strengths

• There is no type encoding info.
• You can finally validate this message with any XML validator. Everything within the soap:body is defined in a schema.
• Document/literal is WS-I compliant, but with restrictions (seeweaknesses).

Weaknesses

• The WSDL is getting a bit more complicated. This is a very minor weakness, however, since WSDL is not meant to be read by humans.
• The operation name in the SOAP message is lost. Without the name, dispatching can be difficult, and sometimes impossible.
• WS-I only allows one child of the soap:body in a SOAP message. As you can see in Listing 7, this example's soap:body has two children.
• 
  

SOAP With Attachments

SOAP message can handle attachments. there is another api for that SAAJ. SAAJ stands for the "SOAP with Attachments API for Java  -- an offshoot of the Java API for XML Messaging (JAXM) -- automates many of the required steps, such as creating connections or creating and sending the actual messages. This tip chronicles the creation and sending of a synchronous SOAP message.

The process involves five steps:

1. Creating a SOAP connection
2. Creating a SOAP message
3. Populating the message
4. Sending the message
5. Retrieving the reply

The figure shows a high-level structure of a SOAP message that has two attachments.

Base on above figure we have following structure of java objects. defined by SAAJ Apis

I. SOAP message

     A. SOAP part

         1. SOAP envelope

              a. SOAP header (optional)

              b. SOAP body

Note: Many SAAJ API interfaces extend DOM interfaces. 

When you create a new SOAPMessage object, it will automatically have the parts that are required to be in a SOAP message. In other words, a newSOAPMessage object has a SOAPPart object that contains a SOAPEnvelope object. The SOAPEnvelope object in turn automatically contains an empty SOAPHeader object followed by an empty SOAPBody object. If you do not need the SOAPHeader object, which is optional, you can delete it. The rationale for having it automatically included is that more often than not you will need it, so it is more convenient to have it provided.

The SAAJ API provides the AttachmentPart class to represent an attachment part of a SOAP message. A SOAPMessage object automatically has a SOAPPart object and its required subelements, but because AttachmentPart objects are optional, you must create and add them yourself. 

If a SOAPMessage object has one or more attachments, each AttachmentPart object must have a MIME header to indicate the type of data it contains. It may also have additional MIME headers to identify it or to give its location. These headers are optional but can be useful when there are multiple attachments.

SAAJ and DOM

The SAAJ APIs extend their counterparts in the org.w3c.dom package:

1. The Node interface extends the org.w3c.dom.Node interface.
2. The SOAPElement interface extends both the Node interface and the org.w3c.dom.Element interface.
3. The SOAPPart class implements the org.w3c.dom.Document interface.
4. The Text interface extends the org.w3c.dom.Text interface.

public class SOAPTip {

    

   public static void main(String args[]) {

        

      try {

     

         // First create the connection

         SOAPConnectionFactory soapConnFactory =  SOAPConnectionFactory.newInstance();

         SOAPConnection connection =  soapConnFactory.createConnection();

         

         //Next, create the actual message

         MessageFactory messageFactory = MessageFactory.newInstance();

         SOAPMessage message = messageFactory.createMessage();

         

         //Create objects for the message parts            

         SOAPPart soapPart =     message.getSOAPPart();

         SOAPEnvelope envelope = soapPart.getEnvelope();

         SOAPBody body =         envelope.getBody();

//Populate the body

        //Create the main element and namespace

        SOAPElement bodyElement =   body.addChildElement(envelope.createName("getPrice" , 

                                                                "ns1", "urn:xmethods-BNPriceCheck"));

        //Add content

        bodyElement.addChildElement("isbn").addTextNode("0672324229");

//Populate the Message

        StreamSource preppedMsgSrc = new StreamSource( new FileInputStream("prepped.msg"));

        soapPart.setContent(preppedMsgSrc);

        //Save the message

        message.saveChanges();

        //Check the input

        System.out.println("\nREQUEST:\n");

        message.writeTo(System.out);

        System.out.println();

 

//Send the message and get a reply   

            

        //Set the destination

        String destination =  "http://services.xmethods.net:80/soap/servlet/rpcrouter";

        //Send the message

        SOAPMessage reply = connection.call(message, destination);

 

        //Check the output

        System.out.println("\nRESPONSE:\n");

        //Create the transformer

        TransformerFactory transformerFactory = TransformerFactory.newInstance();

        Transformer transformer =  transformerFactory.newTransformer();

        //Extract the content of the reply

        Source sourceContent = reply.getSOAPPart().getContent();

        //Set the output for the transformation

        StreamResult result = new StreamResult(System.out);

        transformer.transform(sourceContent, result);

        System.out.println();

 

         //Close the connection            

         connection.close();

            

        } catch(Exception e) {

            System.out.println(e.getMessage());

        }

    }

}

Difference between SOAP 1.1 and SOAP 1.2

1. Just as a person can perform one or more roles in a stage play, a node can play one or more roles in a SOAP message path. Unfortunately, the designers of SOAP 1.1 confused the words "actor" and "role"; they specified that you must identify the roles a node will play by declaring an actor attribute. They've recognized their mistake, and in SOAP 1.2 this attribute has been renamed role.

2. Neither SOAP 1.1 nor the BP explicitly prohibits intermediaries from modifying the contents of the Body element. As a result, the ultimate receiver has no way of knowing if the application-specific data has changed somewhere along the message path. SOAP 1.2 reduces this uncertainty by explicitly prohibiting certain intermediaries, called forwarding intermediaries, from changing the contents of the Body element and recommending that all other intermediaries, called active intermediaries, use a header block to document any changes to the Body element.

3. SOAP 1.2 will replace the SOAPAction header with the protocol-independent action media type (a parameter to the "application/soap+xml" MIME type), so dependency on this feature may result in forward-compatibility problems.

preferred protocol unidirectional SOAP messages

Http is not the best way.

Although a One-Way SOAP message is conceptually unidirectional, but when it's sent over HTTP some type of HTTP reply will be transmitted back to the receiver. One-Way SOAP messages do not return SOAP faults or results of any kind, so the HTTP 202 Accepted response code indicates only that the message made it to the receiver—it doesn't indicate whether the message was successfully processed

SOAP Faults

A SOAP message that contains a Fault element in the Body is called a fault message. When a fault message is generated, the Body of the SOAP message must contain only a single Fault element and nothing else. The Fault element itself must contain a faultcode element and a faultstring element, and optionally faultactor and detail elements.


<?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>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>
        The ISBN value contains invalid characters
      </faultstring>
      <faultactor>http://www.xyzcorp.com</faultactor>
      <detail>
        <mh:InvalidIsbnFaultDetail>
          <offending-value>19318224-D</offending-value>
          <conformance-rules>
            The first nine characters must be digits. The last
            character may be a digit or the letter 'X'. Case is
            not important.
          </conformance-rules>
        </mh:InvalidIsbnFaultDetail>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

The faultcode element may use any of four standard SOAP fault codes to identify an error.

SOAP Standard Fault Codes

1.       Client - node that sent the SOAP message caused the error. receiver cannot process the SOAP message because there is something wrong with the message or its data, it's considered the fault of the client, the sender

When a node receives a fault message with a Client code, it should not attempt to resend the same message. It should take some action to correct the problem or abort completely.

2.       Server - the node that received the SOAP message malfunctioned or was otherwise unable to process the SOAP message.

In this case the sender can assume the SOAP message to be correct, and can redeliver it after pausing some period of time to give the receiver time to recover

3.       VersionMismatch - a SOAP 1.1 node will generate a fault with a VersionMismatch code if it receives a SOAP 1.2 message, because it finds an unexpected namespace in the Envelope.

The VersionMismatch fault applies only to the namespace assigned to the Envelope, Header, Body, and Fault elements. It does not apply to other parts of the SOAP message, like the header blocks, XML document version, or application-specific elements in the Body.

The VersionMismatch fault is also used in the unlikely event that the root element of a message is not Envelope, but something else. Sending a VersionMismatch fault message back to the sender in this case may not be helpful, however: The sender may be designed to handle a different protocol and doesn't understand SOAP faults.

4.       MustUnderstand

Although you're allowed to use arbitrary fault codes, you should use only the four standard codes listed.

The faultstring element is mandatory. It should provide a human-readable description of the fault. 

Although the faultstring element is required, the text used to describe the fault is not standardized

Optionally, the faultstring element can indicate the language of the text message using a special attribute, xml:lang.

The faultactor element indicates which node encountered the error and generated the fault (the faulting node). This element is required if the faulting node is an intermediary, but optional if it's the ultimate receiver.

The detail element of a fault message must be included if the fault was caused by the contents of the Body element, but it must not be included if the error occurred while processing a header block.

The detail element may contain any number of application-specific elements, which may be qualified or unqualified, according to their XML schema. In addition, the detail element itself may contain any number of qualified attributes, as long as they do not belong to the SOAP 1.1 namespace, "http://schemas.xmlsoap.org/soap/envelope".

Summary on Faults

This is probably a good time to recap. Faults result from one of several conditions:

1. The message received by the receiver is improperly structured or contains invalid data.
2. The incoming message is properly structured, but it uses elements and namespaces in the Body element that the receiver doesn't recognize.
3. The incoming message contains a mandatory header block that the receiver doesn't recognize.
4. The incoming message specifies an XML namespace for the SOAP Envelope and its children (Body, Fault, Header) that is not the SOAP 1.1 namespace.
5. The SOAP receiver has encountered an abnormal condition that prevents it from processing an otherwise valid SOAP message.

The first two conditions generate what are considered Client faults, faults that relate to the contents of the message: The client has sent an invalid or unfamiliar SOAP message to the receiver. The third condition results in a MustUnderstand fault, and the fourth results in a VersionMismatch fault. The fifth condition is considered a Server fault, which means the error was unrelated to the contents of the SOAP message. A server fault is generated when the receiver cannot process a SOAP message because of an abnormal condition.

SOAP : More Details

Scenario
Consider a scenario in which SOAP message goes from sender to receiver via many intermediaries 

Intermediaries in a SOAP message path must not modify the application-specific contents of the SOAP Body element, but they may, and often do, manipulate the SOAP header blocks.

two relatively simple header blocks: message-id and processed-by. The processed-by header block keeps a record of the SOAP applications (nodes) that process a SOAP message on its way from the initial sender to the ultimate receiver. Like the message-id header, the processed-by header block is useful in debugging and logging

<?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>

    <mi:message-id>11d1def534ea:b1c5fa:f3bfb4dcd7:-8000</mi:message-id>

    <proc:processed-by>

      <node>

        <time-in-millis>1013694680000</time-in-millis>

        <identity>http://www.customer.com</identity>

      </node>

      <node>

        <time-in-millis>1013694680010</time-in-millis>

        <identity>http://www.Monson-Haefel.com/sales</identity>

      </node>

      <node>

        <time-in-millis>1013694680020</time-in-millis>

        <identity>http://www.Monson-Haefel.com/AR</identity>

      </node>

      <node>

        <time-in-millis>1013694680030</time-in-millis>

        <identity>http://www.Monson-Haefel.com/inventory</identity>

      </node>

      <node>

        <time-in-millis>1013694680040</time-in-millis>

        <identity>http://www.Monson-Haefel.com/shipping</identity>

      </node>

    </proc:processed-by>

  </soap:Header>

  <soap:Body>

      <!-- Application-specific data goes here -->

  </soap:Body>

</soap:Envelope>

actor attribute

You use an actor attribute to identify a function to be performed by a particular node.

Just as a person can perform one or more roles in a stage play, a node can play one or more roles in a SOAP message path. Unfortunately, the designers of SOAP 1.1 confused the words "actor" and "role"; they specified that you must identify the roles a node will play by declaring an actor attribute. They've recognized their mistake, and in SOAP 1.2 this attribute has been renamed role.

The actor attribute is used in combination with the XML namespaces to determine which code module will process a particular header block. Conceptually, the receiving node will first determine whether it plays the role designated by the actor attribute, and then choose the correct code module to process the header block, based on the XML namespace of the header block. Therefore, the receiving node must recognize the role designated by the actor attribute assigned to a header block, as well as the XML namespace associated with the header block

<?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>
    <mi:message-id soap:actor="http://www.Monson-Haefel.com/logger" >
      11d1def534ea:b1c5fa:f3bfb4dcd7:-8000
    </mi:message-id>
    <proc:processed-by>
      <node>
        <time-in-millis>1013694680000</time-in-millis>
        <identity>http://www.customer.com</identity>
      </node>
    </proc:processed-by>
  </soap:Header>
  <soap:Body>
      <!-- Application-specific data goes here -->
  </soap:Body>
</soap:Envelope>

Only those nodes in the message path that identify themselves with the actor value "http://www.Monson-Haefel.com/logger" will process the message-id header block; all other nodes will ignore it

The actor attribute may have values like

1. 1.       custom URIs like "http://www.Monson-Haefel.com/logger",
2. 2.       two standard roles for the actor attribute: next
3. 3.       and ultimate receiver.

The next role indicates that the next node in the message path must process the header. The next role has a designated URI, which must be used as the value of the actor attribute: "http://schemas.xmlsoap.org/soap/actor/next".

The ultimate receiver role indicates that only the ultimate receiver of the message should process the header block. The protocol doesn't specify an explicit URI for this purpose; it's the absence of an actor attribute in the header block that signals that the role is ultimate receiver

must understand attribute

In many cases we may not know the exact message path or the capabilities of all the nodes in a message path, which means we don't always know whether nodes can process header blocks correctly.  For example, the processed-by header block is targeted at the next role, which means the next node to receive it should process it. But what if the next node doesn't recognize that kind of header block?

The mustUnderstand attribute can have the value of either "1" or "0", to represent true and false, respectively. 0 is default.

The "understand" in mustUnderstand means that the node must recognize the header block by its XML structure and namespace, and know how to process it.

If a node doesn't understand a mandatory header block, it must generate a SOAP fault (similar to a remote exception in Java) and discard the message; it must not forward the message to the next node in the message path

Whether or not a fault is sent back to the sender depends on whether the messaging exchange pattern (MEP) is One-Way or Request/Response.

If the mustUnderstand attribute is "0", the processing requirements specified by SOAP are very different. If a node performs the role declared by a non-mandatory header block, and an application fails to understand the header (it doesn't recognize the XML structure or the namespace), it must remove the header block.

In other words, receivers should not attempt to determine whether a message was successfully processed by previous nodes in the path based on which header blocks are present

Note :- header element is optional but body is mandatory.

Neither SOAP 1.1 nor the BP explicitly prohibits intermediaries from modifying the contents of the Body element. As a result, the ultimate receiver has no way of knowing if the application-specific data has changed somewhere along the message path. SOAP 1.2 reduces this uncertainty by explicitly prohibiting certain intermediaries, called forwarding intermediaries, from changing the contents of the Body element and recommending that all other intermediaries, called active intermediaries, use a header block to document any changes to the Body element.

ok