JAX-WS and RPC versus Document Web Services

I have had this buried on this web site for years and am publishing it on the blog as well.

This article will take a journey that ends with a clear and cogent elucidation of the differences between the various styles of SOAP styles for web services. The styles covered are RPC Literal versus Document Literal versus Document Wrapped. We also talk about WS-I Basic Profile that web services need to be compliant of in order to achieve interoperability with consumers on a different platform, technology stack etc.

The article assumes familiarity with XML, WSDL, SOAP as well as Java (upwards of Java 5 including annotations). You can run any of the examples with JDK 1.6 without downloading any extensions or any other libraries.

With the advent of JDK 1.6, JAX-WS and JAXB support is intrinsically available without the need to download any new libraries since Metro is part of the JDK release now.

Without digressing, lets come down to the differences between RPC and Document styles with respect to the java codebase, the WSDL and the SOAP requests and responses. For the purpose of this illustration, we would create an example with a java interface that would be annotated with JAX-WS annotations to translate it into a web service and then generate the artifacts and detail the WSDL and the SOAP requests and responses so generated.

Note: the coverage extends to styles that are mandated by the WS-I BP 1.1 (Basic Profile for interoperability of web services).

We will use the Bottoms-Up approach where in the java interface would be coded first and then the WSDL would be generated off it.

There would be java classes used for the purpose of illustrating the differences and the WSDL and Schema as well as the SOAP requests and responses would also be displayed for demonstrating the differences between the following SOAP styles:

1. RPC Literal (Wrapped)
2. Document Literal
3. Document Wrapped

The following java classes are used. They are listed in entirety (except the package or import statements for the purpose of brevity) and any differences introduced for different SOAP styles are highlighted in the relevant sections.

1. MyServiceIF => this is the web service interface
2. MyServiceImpl => this is the implementation of the MyServiceIF.
3. HolderClass1 => this is singular argument in the exposed web service operation
   • HolderClass2 => this is one of the instance variables of the HolderClass1 besides a string and an integer.
4. EndPointPublisher => as the name suggests, this publishes the web service and automatically generates the artifacts such as the WSDL.

Once the java codebase, WSDL, Schema, SOAP Request and Response are outlined for each of the SOAP styles, thereafter a section explaining the various differences is provided.

---

RPC Literal Wrapped

RPC-Literal is always wrapped (not BARE).  This is a listing of the java classes mentioned earlier.

Source Code:

---

---

---

---

Listing 1: The Java codebase.

WSDL and Schema

The WSDL generated for RPC Literal is as follows:

The schema that this WSDL refers to is:

SOAP Request

SOAP Response

 

 

---

Document Literal (BARE)

The java codebase remains the same except for the following:

1. The SOAP Binding for the MyServiceIF is updated to specify Document as the style:@SOAPBinding(style=Style.DOCUMENT, use=Use.LITERAL, parameterStyle=ParameterStyle.BARE)
2. The WebParam annotation now specifies a partName as well. This is to elucidate where the partName would be translated to in the WSDL that would be created.
3. Since WS-I BP 1.1 specifies that there should be only one child in the body of the element. Since this is a Document Literal service, there would not be an element (such as the name of the operation) that encapsulates all the parameters (such as class1 and intArg). This implies that such a case would not be WS-I BP 1.1 compliant. Therefore JAX WS will not allow it and as a result spew out this error:
   Exception in thread “main” com.sun.xml.internal.ws.model.RuntimeModelerException: runtime modeler error: SEI server.MyServiceImpl has method getHolderClass annotated as BARE but it has more than one parameter bound to body. This is invalid. Please annotate the method with annotation: @SOAPBinding(parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
   To overcome this issue and to continue to demonstrate this style, we would remove one of the arguments in the method.

Java Listing

@WebService

@SOAPBinding(style=Style.DOCUMENT, use=Use.LITERAL, parameterStyle=ParameterStyle.BARE)

publicinterface MyServiceIF {

@WebMethod(operationName=“getHolder”)

HolderClass1 getHolderClass(@WebParam( name=“holderClass1Param”, partName=“holderClass1Param2″) HolderClass1 class1);

}

 

WSDL and Schema

The WSDL so generated for this style is:

And the schema that is refers to is:

SOAP Request

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:ser=”http://server/”>

<soapenv:Header/>

<soapenv:Body>

<ser:holderClass1Param>

<holder2>

<i>2</i>

<name>?</name>

</holder2>

<i>1</i>

<name>?</name>

</ser:holderClass1Param>

</soapenv:Body>

</soapenv:Envelope>

SOAP Response

<S:Envelope xmlns:S=”http://schemas.xmlsoap.org/soap/envelope/”>

<S:Body>

<ns2:getHolderResponse xmlns:ns2=”http://server/”>

<holder2>

<i>6</i>

<name>name_holderClass2</name>

</holder2>

<i>2</i>

<name>name_holderClass1</name>

</ns2:getHolderResponse>

</S:Body>

</S:Envelope>

---

Document Literal Wrapped

The java codebase remains the same except for the following:

1. The SOAP Binding for the MyServiceIF is updated to specify Wrapped as the parameter style. The parameterStyle attribute in the SOAPBinding annotation is removed and that implies the service is wrapped due to “Wrapped” being the default for the attribute.@SOAPBinding(style=Style.DOCUMENT, use=Use.LITERAL)

Java Listing

WSDL and Schema

The WSDL so generated for this style is:

And the schema that is refers to is:

SOAP Request

SOAP Response

---

Differences between the Styles

	RPC Literal (Wrapped)	Document Literal	Document Wrapped
Request Message	The operation name appears immediately after the soap:body. The operation name is specified by the binding:operation element in the binding section of the WSDL. The name attribute of the message:part follows immediately. It is not qualified by a namespace Thereafter the names of the elements in the types section of the WSDL are specified.	The operation name is not specified in the request. The value specified by the element attribute of message:part is the first line following the soap:body. It is qualified by a namespace. Note that this value of the element attribute is actually the value of the name attribute of the schema element in the types section. Thereafter it is similar to RPC Literal in the way that the names of the elements in the types section of the WSDL are specified.	It is similar to “Document Literal Bare” style with one exception => the value of the “element” attribute in the message:part is defined to be the name of the operation. Therefore the name of the operation is part of the request. The operation name appears immediately after the soap:body. Thereafter it is similar to RPC Literal.
WS-I BP 1.1 Compliance	It is WS-I BP 1.1 compliant even though there are many parts in the input message. This is because the first element after the soap:body is the name of the operation and that encapsulates it all.	Since it can have multiple parts immediately following the soap:body, it is not WS-I BP 1.1 compliant. Therefore to make it compliant, a wrapper needs to be defined and this implies that the web method can only have one argument. You could circumvent this requirement by defining the arguments to be part of the SOAP header instead of the body.	It is WS-I BP 1.1 compliant.
WSDL	There could be many parts in the input message. The parts are always specified with a “type” attribute.	There could be many parts in the input message The parts are always specified with an “element” attribute	There is only one part in the input message. The part is always specified by an “element” attribute. This part is the entire message payload and is completely defined in the types section.