document Vs rpc message styles

[Vasim Patel]

Hi,

Can anyone please tell me the exact difference between an rpc and document message style.

I found the RMH description a bit vague...
(Chapter 4. 4.5 SOAP Messaging Modes)

"..Document 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)..."

by "arbitrary application data", what do we mean?

e.g.

<soap:Envelope
xmlns roc="http://www.Monson-Haefel.com/jwsbook/processed-by">

<soap:Body>
<po urchaseOrder orderDate="2003-09-22"
xmlns o="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 urchaseOrder>
</soap:Body>
</soap:Envelope>


"The RPC mode of messaging enables SOAP messages to model calls to procedures or method calls with parameters and return values. "

<soap:Envelope
xmlns:mh="http://www.Monson-Haefel.com/jwsbook/BookQuote">
<soap:Body>
<mh:getBookPrice>
<isbn>0321146182</isbn>
</mh:getBookPrice>
</soap:Body>
</soap:Envelope>


To argue, the Document mode definition applies for rpc mode as well.

Because according to the above defn, message in RPC mode is also an XML Document fragment, which is well-formed and hence the above RPC is also Document mode.

Although by "looking" at the two examples, I can make out the difference, but how exactly can you differentiate between the two.

Are there any specific rules for rpc which differentiate from document.

thanks
Vasim

[wise owen]

This Document may help.

[Peer Reynders]

Originally posted by Vasim Patel:
Are there any specific rules for rpc which differentiate from document.

I have to admit I have yet to run into a clear-cut definition for the two. Seems most explanations are rather nebulous along the lines of "if it's not 'rpc' it's 'document'".

Also the explanation that the root element represents an operation with parameters for "rpc" while for "document" style the root is simply the root of an XML document seems a bit weak - both SOAP payloads are still "XML documents" (well, they have to be!).

For now I'm sticking with the following (very fuzzy) rule of thumb: if the SOAP payload is (primarily) data-oriented XML (i.e. fully hierarchical, elements contain elements, elements containing text don't contain any more elements) and the root element looks like an operation and the root's immediate children look like parameters its probably "rpc". If the SOAP payload looks like one big chunk of document-oriented XML (mixed content) its probably "document". ... however I could be entirely misguided which that notion.

I can think up a scenario where the parameter for an rpc-style call is a document-oriented XML document (hence the 'primarily' in parenthesis in the above statement). So really the 'rpc' messaging style could be viewed as an indication that the root element of the SOAP payload is an 'envelope' that identifies what needs to be done with the content of that 'envelope' (leading us back to the "operation with parameters" definition).
Which style of WSDL should I use?
rpc vs document was a bigger deal when it was still rpc/encoded vs document/literal.
On document vs. RPC style, why is it a big deal?
[ February 08, 2006: Message edited by: Peer Reynders ]

[Vasim Patel]

Thanks Peer, Wise again for pointing out the links.

I did a little more reading in RMH, and got a little more clarity, though still not complete.

RMH : 5.3.1.2 The message Element for Document-Style Web Services

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.BP

Here are some differences between rpc message vs document message.

1. RPC message part has type:
If you're using RPC-style messaging, the part elements must use the type attribute
<message name="rpcmessage">
<part name="typepart" type="xsd:int"/>
</message>

Document message part has element
if you're using document-style messaging, the part elements must use the element attribute

<message name="documentmessage">
<part name="elementpart" element="ns:name"/>
</message>


2. RPC messages use types to define procedure calls. Each element represents type of parameter
Document messages exchange XML document fragments and refer to their global elements


take an example wsdl file which has both an rpc and a document style message.

Although this is not a good real life example, it might help understand the diff.


<definition>

<!--types has a type 'PersonType' and a 'Person' element-->
<types>
<xsd:schema>
<xsd:element name="Person" type="p ersonType"/>
<xsd:complexType name="PersonType">
<xsd:sequence>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="age" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
</types>

<!--rpcmessage is an rpc style message which has its part using 'type'-->
<message name="rpcmessage">
<part name="person" type="p ersonType"/>
</message>

<!--documentmessage is an document style message which has its part using 'element'-->
<message name="documentmessage">
<part name="person" element="p erson"/>
</message>
</definition>

Let me know if this is correct understanding.

regards
Vasim

[Peer Reynders]

I think you could push your example a bit further. Consider the schema:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
 xmlns:mh="http://www.Monson-Haefel.com/jwsbook"
 targetNamespace="http://www.Monson-Haefel.com/jwsbook">
 
    <element name="apurchaseOrderDoc" type="mh:APurchaseOrderType" />
 
    <complexType name="APurchaseOrderType">
        <sequence>
            <element name="accountName"     type="string" />
            <element name="accountNumber"   type="unsignedShort" />
            <element name="shipAddress"     type="mh:USAddress" />
            <element name="billAddress"     type="mh:USAddress" />
            <element name="book"            type="mh:Book" />
            <element name="total"           type="float" />
        </sequence>
    </complexType>
 
    <complexType name="USAddress">
        <sequence>
            <element name="name"    type="string" />
            <element name="street"  type="string" />
            <element name="city"    type="string" />
            <element name="state"   type="string" />
            <element name="zip"     type="string" />
        </sequence>
    </complexType>
</schema>

Note that in this XML application the root (top-level) element of a valid XML Document has to be <apurchaseOrderDoc> - no other root element is valid.

In rpc style messaging you could do this:

<!-- 
     part does not have to be a valid XML Document 
     it can simply be a valid type as defined by the schema
-->
<message name="submitUSAddress">
    <part name="address" type="mh:USAddress" />
</message>

In document style messaging you would do this:

<!-- part has to be a valid XML Document -->
<message name="submitPurchaseOrder">
    <part name="purchaseOrder" element="mh:apurchaseOrderDoc" />
</message>

Looking at it this way rpc style messaging is more flexible (less rigid) than document style messaging as rpc is not limited to the documents as allowed by the schema - it can use all of the schema's types.

I find the reference in 5.3.1.2 to "XML document fragments" a bit puzzling - unless it simply refers to the fact that a fragment is created by enclosing the XML Document in a message instance.
[ February 09, 2006: Message edited by: Peer Reynders ]

[Vasim Patel]

Thanks for a better example Peer. Looks more real world.

[Haitham Ismail]

Hello everybody
I have 2 questions related to this thread:
1) if I have a web service with 2 operations with different names. both of them use the document/literal style and use the same message as an input. then a soap message arrived to the web service as the following:
<soap:Envelop ...>
<soap:Body>
<!-- Any XML Document without an operation name -->
</soap:Body>
</soap:Envelop>
Is this case allowed in the BP. if yes How the JAX-RPC can map the message to the approperite method?

2) another question if I have a web service with 2 operations, both of them use the document/literal style. each of which uses a different message as input. How can this be defined in the WSDL?

Regards

[Peer Reynders]

As Which style of WSDL should I use? outlines:

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 a countermeasure the document/literal wrapped pattern is suggested and outlined.

Scenario 2 shouldn't be a problem because both operations would use a different "message" which each refers to a different top-level element (XML document). The SOAP message payload would be a different type of XML document in either case.

The bottom-line is that in document/literal the XML document type implies the operation.

The document/literal wrapped pattern simply creates a new type of XML document that acts as an envelope a) to identify an operation and b) to carry multiple documents. The difference to rpc/literal is that the operations and parameters are now no longer part of the WSDL definition but part of your document XML schema.

[Haitham Ismail]

thank you Peer Reynders
so you mean the first scenario is allowed by the WS-I but we should not use it. right?

[Peer Reynders]

Originally posted by Haitham Ismail:
so you mean the first scenario is allowed by the WS-I but we should not use it. right?

In my judgment the first scenario is not allowed by Basic Profile 1.0a. Look at this excerpt:
5.6.9 Child Element for Document-Literal Bindings

WSDL 1.1 is not completely clear what, in document-literal style bindings, the child element of soap:Body is.
R2712 A document-literal binding MUST be represented on the wire as a MESSAGE with a soap:Body whose child element is an instance of the global element declaration referenced by the corresponding wsdl:message part.

By saying that it�s the message that appears in the body it basically is acknowledging that the operation is meaningless in the document/literal context. So by extension having two operations with different names but the same messages/parts is equivalent to having two identical operation definitions which is clearly illegal.

[Haitham Ismail]

Thank you Peer Reynders very much. I have tried the first scenario on RAD and WAS 5 test environment and I have got a warning at the build time and an exception at runtime.