JAX-WS and RPC versus Document Web Services

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.

Java Listing

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)

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