Chapter 12. Endpoint Design and Architecture

Given a scenario, design Web service applications using information models that are either procedure-style or document-style.

[Note]

Empty

A WSDL document describes a Web service. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. 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

Let's start with the Java method:

public void myMethod(int x, float y);					
					

RPC/encoded

RPC/encoded 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 .../>
					
					

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>
					
					

There are a number of things to notice about the WSDL and SOAP message for this RPC/encoded example:

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

  • Weaknesses

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

    • 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 above). The use in the binding is changed from encoded to literal.

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

					

RPC/literal SOAP message for myMethod:


<soap:Envelope>
    <soap:Body>
        <myMethod>
            <x>5</x>
            <y>5.0</y>
        </myMethod>
    </soap:Body>
</soap:Envelope>

					

Here are the strengths and weaknesses of RPC/literal approach:

  • 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 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 is not WS-I compliant.

Document/literal

Document/literal WSDL for myMethod:


<types>
    <schema>
        <element name="xElement" type="xsd:int"/>
        <element name="yElement" type="xsd:float"/>
    </schema>
</types>

<message name="myMethodRequest">
    <part name="x" element="xElement"/>
    <part name="y" element="yElement"/>
</message>

<message name="empty"/>

<portType name="PT">
    <operation name="myMethod">
        <input message="myMethodRequest"/>
        <output message="empty"/>
    </operation>
</portType>

<binding .../>
					
					

Document/literal SOAP message for myMethod:


<soap:Envelope>
    <soap:Body>
        <xElement>5</xElement>
        <yElement>5.0</yElement>
    </soap:Body>
</soap:Envelope>

					

Here are the strengths and weaknesses of Document/literal approach:

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

  • 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 above, this example's soap:Body has two children.

Document/literal wrapped

Document/literal wrapped WSDL for myMethod:


<types>
    <schema>
    
        <element name="myMethod">
            <complexType>
                <sequence>
                    <element name="x" type="xsd:int"/>
                    <element name="y" type="xsd:float"/>
                </sequence>
            </complexType>
        </element>
        
        <element name="myMethodResponse">
            <complexType/>
        </element>
    </schema>
</types>

<message name="myMethodRequest">
    <part name="parameters" element="myMethod"/>
</message>

<message name="empty">
    <part name="parameters" element="myMethodResponse"/>
</message>

<portType name="PT">
    <operation name="myMethod">
        <input message="myMethodRequest"/>
        <output message="empty"/>
    </operation>
</portType>

<binding .../>  

					
					

The WSDL schema now has a wrapper around the parameters.

Document/literal wrapped SOAP message for myMethod:


<soap:Envelope>
    <soap:Body>
        <myMethod>
            <x>5</x>
            <y>5.0</y>
        </myMethod>
    </soap:Body>
</soap:Envelope>

					

Notice that this SOAP message looks like the RPC/literal SOAP message, but there's a subtle difference. In the RPC/literal SOAP message, the <myMethod> child of <soap:Body> was the name of the operation. In the document/literal wrapped SOAP message, the <myMethod> clause is the name of the wrapper element which the single input message's part refers to. It just so happens that one of the characteristics of the wrapped pattern is that the name of the input element is the same as the name of the operation. This pattern is a sly way of putting the operation name back into the SOAP message.

These are the basic characteristics of the document/literal wrapped pattern:

  • The input message has a single part.

  • The part is an element.

  • The element has the same name as the operation.

  • The element's complex type has no attributes.

Here are the strengths and weaknesses of document/literal wrapped approach:

  • Strengths

    • There is no type encoding info.

    • Everything that appears in the soap:Body is defined by the schema, so you can easily validate this message.

    • You have the method name in the SOAP message.

    • Document/literal is WS-I compliant, and the wrapped pattern meets the WS-I restriction that the SOAP message's soap:Body has only one child.

  • Weaknesses

    • The WSDL is even more complicated.

Reasons to use document/literal non-wrapped

If you have overloaded operations, you cannot use the document/literal wrapped style.

public void myMethod(int x, float y);
public void myMethod(int x);
					

When you add the wrapped pattern to WSDL, you require an element to have the same name as the operation, and you cannot have two elements with the same name in XML. So you must use the document/literal, non-wrapped style or one of the RPC styles.

Reasons to use RPC/literal

Since the document/literal, non-wrapped style doesn't provide the operation name, there are cases where you'll need to use one of the RPC styles. For instance, say you have the set of methods:

public void myMethod(int x, float y);
public void myMethod(int x);
public void someOtherMethod(int x, float y);
					

Now assume that your server receives the document/literal SOAP message. Which method should the server dispatch to? All you know for sure is that it's not myMethod(int x) because the message has two parameters and this method requires one. It could be either of the other two methods. With the document/literal style, you have no way to know which one.

Instead of the document/literal message, assume that the server receives an RPC/literal message. With this message it's fairly easy for a server to decide which method to dispatch to. You know the operation name is myMethod, and you know you have two parameters, so it must be myMethod(int x, float y).

Reasons to use RPC/encoded

The primary reason to prefer the RPC/encoded style is for data graphs. Imagine that you have a binary tree whose nodes are defined:


<complexType name="Node">
    <sequence>
        <element name="name" type="xsd:string"/>
        <element name="left" type="Node" xsd:nillable="true"/>
        <element name="right" type="Node" xsd:nillable="true"/>
    </sequence>
</complexType>

					

With this node definition, you could construct a tree whose root node A points to node B through both its left and right links. The standard way to send data graphs is to use the href attribute, which is part of the RPC/encoded style:


<A>
    <name>A</name>
    <left href="12345"/>
    <right href="12345"/>
</A>
<B id="12345">
    <name>B</name>
    <left xsi:nil="true"/>
    <right xsi:nil="true"/>
</B>
					
					

Under any literal style, the href attribute is not available, so the graph linkage is lost. You still have a root node, A, which points to a node B to the left and another node B to the right. These B nodes are equal, but they are not the same node. Data have been duplicated instead of being referenced twice:


<A>
    <name>A</name>
    <left>
        <name>B</name>
        <left xsi:nil="true"/>
        <right xsi:nil="true"/>
    </left>
    <right>
        <name>B</name>
        <left xsi:nil="true"/>
        <right xsi:nil="true"/>
    </right>
</A>

					

Professional hosting     Belorussian informational portal         Free SCWCD 1.4 Study Guide     Free SCDJWS 1.4 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide     SCDJWS 5.0 Quiz