Description of how WSDL style and use are combined

The use attribute can be literal,encoded;style for rpc,document, and we will compare the binding of the five types of style/use decisions, rpc/literal, document/literal None-wrapper, document/literal with wrapper, rpc/encoded, and document/encoded.

From the perspective of generating SOAP messages

The difference between RPC and document is whether the operation name of the method appears in the generated SOAP message.

The difference between literal and encoded encoding is whether the parameter type appears in the generated SOAP message.

Rpc/encoded can fully represent a method call, but performance is poor and the validity of the SOAP message cannot be verified.

Rpc/literal does not encode the parameter type, but the SOAP message is still not validated.

Document/encoded doesn't make sense because there is no method name, and it doesn't make sense to encode the parameter type.

Document/literal None-wrapper cannot generate an operation name, which applies to a scene where the complete document is passed as a parameter to the method.

Document/literal with wrapper should be the most frequently used method.

The WSDL binding style can be either an RPC style or a document style. The usage can be encoded, or it can be literal. How do you decide which style/usage combination to use? This article will help you solve this problem.

WEB services are described through WSDL documents. The WSDL binding describes how to bind a service to a messaging protocol (especially a SOAP messaging protocol). WSDL SOAP bindings can be either RPC-style bindings or document-style bindings. Similarly, a SOAP binding can have an encoded use, or it can have the use of text. This provides us with four styles/usage models: rpc/encoding, rpc/text, document/encoding, document/text

In addition to these styles, there is also a common style, known as the document/text wrapping style, in which you have five binding styles to choose from when creating a WSDL file. Which one should you choose?

For the discussion in this article, let's start with the Java method in Listing 1 and apply the Jax-RPC java-to-wsdl rule to it. Listing 1. Java methods

public void MyMethod (int x);

 

rpc/Code

Use the method in Listing 1 and run it with your favorite JAVA-TO-WSDL tool, specifying that you want it to generate rpc/encoded WSDL. You should end up with a WSDL fragment as shown in Listing 2.

Listing 2. rpc/encoded WSDL for MyMethod

<message name= "Mymethodrequest" > <part name= "x" type= "Xsd:int"/> </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/encoded. -->

This method is now called with "5" as the value of the parameter x. We will send a SOAP message similar to listing 3.

Listing 3. RPC/encoded SOAP messages for MyMethod

<soap:envelope> <soap:body> <myMethod> <x xsi:type= "Xsd:int" >5</x> </myMethod> </soap:body> </soap:envelope>

There are a number of things to note about WSDL and SOAP messages in this rpc/-encoded example:

For the sake of simplicity, in most of the XML examples in this article, I omitted namespaces and prefixes. However, I still use a few prefixes, and you can assume that they are defined with the following namespaces.

Xmlns:xsd= "Http://www.w3.org/2001/XMLSchema"

Xmlns:xsi= "Http://www.w3.org/2001/XMLSchema-instance"

xmlns:soap= "http://schemas.xmlsoap.org/soap/envelope/"

Advantages

WSDL basically achieves as simple and understandable a requirement as possible.

The operation name appears in the message so that the receiver can easily send the message to the implementation of the method.

Disadvantages

Type-coded information, such as xsi:type= "Xsd:int", is often the cost of reducing throughput performance.

You cannot simply verify the validity of this message because only the <x xsi:type= "Xsd:int" >5</x> line contains the content defined in the Schema; the rest of the soap:body content is derived from the WSDL definition.

is there a way to preserve these advantages and eliminate the drawbacks? Maybe there is. Let's take a look at the style of rpc/text.

rpc/Text

The WSDL for the rpc/text for our method looks almost the same as the RPC/encoded WSDL (see Listing 4). Only the use of bindings is changed to text by encoding. That's all.

Listing 4. WSDL for rpc/text for MyMethod

<message name= "Mymethodrequest" > <part name= "x" type= "Xsd:int"/> </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/text (see Listing 5). The change here is a little bit more. The type encoding is removed.

Listing 5. SOAP messages for MyMethod rpc/text

<soap:envelope> <soap:body> <myMethod> <x>5</x> </myMethod> </soap:body> </soap:envelope>

The following are the advantages and disadvantages of this approach:

Advantages

WSDL is still basically up to the simplest possible requirements.

The operation name still appears in the message.

The type encoding is removed.

Disadvantages

You still cannot simply verify the validity of this message because only the <x xsi:type= "Xsd:int" >5</x> line contains the content defined in the Schema; the remaining soap:body content is derived from the WSDL definition.

What about the document style? Can they help overcome these difficulties?

I don't know who knows the true meaning of this method. I don't know any implementation of this method either. It will probably disappear from subsequent versions of the WSDL. So let's talk about something else.

WSDL for document/literal

The WSDL for the document/literal has made some changes to the WSDL of the rpc/text. The difference between them is shown in Listing 6.

Listing 6. WSDL for document/text for MyMethod

<types>     <schema>          <element name= "XElement" type= "Xsd:int"/>     </schema> </types > <message name= "Mymethodrequest" >     <part name= "x"         element= "XElement"/> </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 &NB sp;       document/literal. -->

And now SOAP should look like Listing 7:

Listing 7. SOAP messages for document/text for MyMethod

<soap:envelope> <soap:body> <xElement>5</xElement> </soap:body> </soap:envelope>

Considerations for Message Components

I could have just changed the bindings, as I did from the rpc/code to rpc/. It will be the legitimate WSDL. However, the WS-I Basic overview (WS-I-Basic profile) prescribes that the components of a document/literal message are reference elements rather than types, so I followed WS-I (and the element section here is a good way to take us to the discussion of the document/text wrapper style).

The following are the advantages and disadvantages of this approach:

Advantages

No coded information

You can verify the validity of this message at the end with any XML checker. Each of the contents of Soap:body (<xElement>5</xElement>) is defined in the Schema.

Disadvantages

WSDL becomes a bit more complex. However, this is a very small disadvantage because the WSDL is not intended to be read by people.

The operation name is missing from the SOAP message. And without an operation name, sending can be difficult and sometimes impossible.

The style of the document/text seems to be just the advantages and disadvantages of rearranging the model of the rpc/text. You can verify the validity of the message, but you lose the operation name. Is there a way to improve this? Some. It is

styles for document/text wrapping

Before I explain the meaning of the document/text wrapper style, let me show you the WSDL and SOAP messages in Listing 8 and listing 9.

Listing 8. WSDL for document/text wrapper for MyMethod

<types> <schema> <element name= "MyMethod"/> <complexType> <sequence> <element name= "x" type= "Xsd:int"/> </sequence> </complexType> </element> </schema> </types> <message name= "Mymethodrequest" > <part name= "Parameters" element= "MyMethod"/> </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 document/literal. -->

The WSDL Schema now places the parameters in the wrapper (see Listing 9).

List: 9. SOAP messages for document/text wrapping for MyMethod

<soap:envelope> <soap:body> <myMethod> <x>5</x> </myMethod> </soap:body> </soap:envelope>

Note that this SOAP message looks very similar to a rpc/literal SOAP message. You might say that it looks exactly the same as the SOAP message for rpc/text, but there is a subtle difference between the two messages. In the SOAP message for rpc/text, the <myMethod> clause of <soap:body> is the name of the operation. In a document/text wrapped SOAP message, the <myMethod> clause is the name of the element that is referenced by the component of a single input message. Therefore, the wrapper style has a feature that the INPUT element's name is the same as the name of the operation. This style is a clever way to put an operation name into a SOAP message.

The characteristics of the document/text wrapping style are:

The input message has only one component; The element has the same name as the operation; the complex type of the element has no attributes;

The following are the advantages and disadvantages of this approach:

Advantages

No encoded information.

Each item that appears in Soap:body is defined by a Schema, so you can now easily test the validity of this message.

The method name appears in the SOAP message again.

Disadvantages

WSDL is even more complex, but it is still a very small disadvantage.

As you can see, there are some drawbacks to the document/text wrapping style, but they all seem insignificant compared to the pros.

rpc/style of text wrapping?

From a WSDL point of view, there is no reason to simply associate the wrapper style with the document/text binding. It can be easily applied to rpc/text binding. But it is rather unwise to do so. SOAP will contain a myMethod element of the operation and a child myMethod element of the element name. In addition, even if it is a legitimate wsdl,rpc/text element part does not follow WS-I.

Where is the document/text style defined?

The style of this wrapper comes from Microsoft. There is no specification for this style, so while this style is a good thing, unfortunately, in order to interoperate with the implementations of Microsoft and other companies, the only option now is to guess how it works based on the output of Microsoft WSDL. The document/text wrapping style is also implemented in the IBM WebSphere SDK for Web Services. In this example, the style is quite obvious, but there are also individual cases in which the appropriate things to do due to lack of definition are not particularly clear. The ideal scenario we want to see is an independent community like the Web Services Interop Organization (Web Service Interoperability organization) that will help stabilize and standardize this.

Why not always take a document/ style of text wrapping

So far, this article has given you the impression that the document/text packaging style is the best way. And the real situation is often true. However, there are still situations in which you might want to change a different style.

reasons to adopt a document/text non-packaged style

If you have overloaded the operation, you cannot use the document/text wrapping style.

Imagine, in addition to the methods we have been using, there is another way, see listing 10.

Listing 10. Problem methods for document/text wrapping

public void MyMethod (int x); public void MyMethod (int x, String y);

The WSDL allows overloaded operations. But when you add a wrapper style to the WSDL, you need the element to have the same name as the operation, and you cannot have two elements with the same name in the XML. So you must take a document/text-not-wrapped style or some type of RPC style.

using rpc/ reasons for the style of the text

Because the document/text unpackaged style does not provide an action name, in some cases you will need to take some kind of RPC style. For example, a set of methods in Listing 11.

Listing 11. Method of problem for document/text unpackaged styles

public void MyMethod (int x); public void MyMethod (int x, String y); public void Someothermethod (int x);

Now assume that your server receives a SOAP message for the document/literal (you can look back at it in Listing 7). Which method should the server send? All you know for sure is that it must not be myMethod (int x, String x) because the message has only one parameter, and this method requires two parameters. It may be one of the other two methods. With the document/text style, you have no way of knowing which method.

Suppose the server receives a rpc/text message (as in Listing 5), rather than a document/text message. For such a message, it is easy for the server to decide which method to send it to. You know the operation name is MyMethod and you know there is only one parameter, so it must be myMethod (int x).

There are many reasons to use rpc/coding.

Among the two main reasons are:

Data Graphics

Polymorphism

Data Graphics

Imagine that you have a binary tree in which the nodes are defined in Listing 12.

Listing 12. Binary tree node Schema

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

Based on this node definition, we can construct a tree structure whose root node A can point to node B through its left and right links (see Figure 1).

The standard way to send a data graphic is to use the href tag, which is part of the rpc/encoded style (listing 13).

List: 13. rpc/coded binary tree

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

In any style of text, the HREF attribute is not available, so that the graphic link no longer works (listing 14 and Figure 2). You still have a root node A, which points from the left to a Node B, and from the right point to another node B. These two B nodes are equivalent, but they are not the same node. is to copy the data instead of referencing it two times.

14. Text Binary tree

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

In text styles, you can construct graphics in a variety of ways, but there are no standard methods, so anything you do may not interoperate with services on other endpoints on your network.

Polymorphism

Take a look at the WSDL used in Listing 15 for the polymorphic Schema.

Listing 15. An example of a polymorphic WSDL

<types> <schema> <complextype name= "Animal" > <sequence> <element name= "name" type= "xsd:string"/> </sequence> </complexType> <complextype name= "Dog" > <complexcontent mixed= "false" > <extension base= "Animal" > <sequence> <element name= "breed" type= "xsd:string"/> </sequence> </extension> </complexContent> </complexType> </schema> </types> <message name= "in" > <part name= "Trainee" type= "Animal"/> </message> <message name= "Empty"/> <porttype name= "Animaltrainer" > <operation name= "Train" > <input message= "in"/> <output message= "Empty"/> </operation> </portType>

When you pass a dog instance to the train operation, the generated SOAP message must contain the type encoding information so that the receiving terminal can know which extension it is receiving animal (see Listing 16). This type of encoding information can be used in rpc/encoded styles.

Listing 16. A polymorphic SOAP message

<soap:envelope> <soap:body> <train> <trainee xsi:type= "Dog" > <name>Bob</name> <breed>Bloodhound</breed> </trainee> </train> </soap:body> </soap:envelope>

Summarize

There are four binding styles (actually there are five of them, but the document/encoded style doesn't make any sense). Although each style has its own niche, in most cases the best style is the document/text wrapping style.