The @SOAPBinding annotation can be used to configure the soap binding styles.

You can use the @SOAPBinding annotation on the SEI and any of its methods. The settings of the method’s annotation takes precedence.

The @SOAPBinding annotation has three attributes: Style, Use and ParameterStyle.

• Values for style can be Style.DOCUMENT (Default) or Style.RPC.

• Values for use are Use.Literal (Default) or Use.Encoded.

• Values for parameterStyle are ParameterStyle.BARE and ParameterStyle.WRAPPED (Default).

Literal vs. encoded

The WSDL service contract has to specify how data types used in the implementation language are serialized to WSDL compliant types and on the client side, how the WSDL-compliant types are de-serialized into client language types. 

The setting use=”literal” in soap binding means that the service’s type definitions literally follow the WSDL documents XML Schema, or in simple terms the values that you pass and values responded are literally there in the xml.

The setting use=”encoded” means that the services type definitions come from encoding rules, typically the encoding rules of SOAP 1.1 spec, or in simple terms the values are encoded. 

Only literal is WS-I compliant and not “encoded”.  

RPC and encoded combination was used before SOAP objects were defined with XML Schema; and is not much supported now. Rpc/encoded wsdls are not supported in JAXWS 2.0+. 

Example: RPC/encoded soap message:

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

Note: Rpc/encoded wsdls are not supported in JAXWS 2.0+. 

Wrapped and Unwrapped (BARE) Document styles

The idea of wrapped convention is to give a document-style service the look and feel of an rpc-style service, thus trying to combine the benefits of document and rpc styles:

• The document style promotes web service interoperability because of the use of XSD in the WSDL’s type section.

• The rpc style also has the advantage that the web service’s operations have names linked directly to the underlying implementation, and hence are more programmers friendly.

The body of a wrapped SOAP request envelope will have name of the requested service operation with sub-elements as in the rpc style. The wrapped version makes service operation explicit.

Example: Wrapped Document Style SOAP message

<soapenv : Body>

<ans:getTimeAsElapsedResponse xmlns:ans = “http://ts.ws”>

<return> 1234 </return>

</ans:getTimeAsElapsedResponse>

</soapenv:Body>

The contrast between wrapped document-style and unwrapped document-style web services comes down to how parameters are represented in the SOAP body.

For wrapped, the parameters are wrapped/enclosed in the SOAP message by the operation name in the WSDL (not the method name in the Java code).

Guidelines for the wrapped document convention

1. The SOAP envelope’s body should contain only a single XML element with however many XML sub-elements, ie, it should have only one part.

2. The relationship between the WSDL’s XSD and the single XML element in the XSD should be named and typed. The XML elements in the XSD serve as wrappers for the SOAP message body. 

3. The request wrapper has the same name as the service operation and the response wrapper should be the request wrapper’s name with ‘Response’ appended.

4. The WSDL portType section will now have named operations whose messages are typed.

SOAP Binding combinations and observations

We can have various combinations using different soap binding styles like Document-Literal-Wrapped, RPC-Encoded etc.

Some of the important rules and observations (covered in upcoming examples) are as below:

• The JAX-WS 2.0 RI support only below styles:

  • Document/Literal (Both Wrapped and Unwrapped (BARE))

  • RPC/Literal (Only Wrapped)

• RPC-Literal-Bare is illegal.

  • If you try to publish an RPC-Literal-Bare web servie, you will get RuntimeModelerException with a message that ParameterStyle can only be WRAPPED with RPC Style Web service.

• JAX-WS 2.0 RI does not support encoded.

  • However if we use Encoded style in java class, it doesn’t throw any error, but just treats it as literal and even the value of ‘use’ is literal in generated wsdl.

• DOC-LITERAL-BARE(UnWrapped) cannot be used with multiple parameters

  • if we use, we will get an exception that the method annotated as BARE has more than one parameter bound to body.

  • The WS-I Basic Profile limits the number of child elements of the SOAP <Body> element to zero or one. Thus non-wrapped (BARE) services may have zero or one elements under body.

    • The Wrapped convention overcomes this limitation by wrapping all parameters into an element, similar to RPC.

    • We can also overcome this limitation in BARE by adding the parameters as fields to an object and passing the single object as a parameter in the soap request.

• Body of Document-Literal-BARE(Unwrapped) service’s request for a method with no parameters is empty.

• The contrast between wrapped and unwrapped services comes down to how parameters are represented in the SOAP body, whereas contrast between document and rpc styles comes down mainly to how things are specified in a wsdl.

  • Rpc-Literal-Wrapped and Document-Literal-Wrapped requests and responses look the same; the difference can be seen in the wsdl only.

• The types section

  • is empty for RPC in general and type is specified along with the parameters in the message part.

  • In DOC, type is specified in types section.

  • The types section is same for a wrapped or unwrapped DOC.

• Multiple parameters

  • In a wsdl for DOC-WRAPPED with multiple parameters, input message element has only one part with name parameters.

  • In RPC with multiple parameters, input message element has one part each for each parameter.

• Additional elements in wsdl

  • For Both DOC and RPC, portType is similar except that RPC adds parameterOrder in case of multiple parameters.

  • For Both DOC and RPC, binding is similar except that the value of ‘style’ attribute is document and rpc respectively; and RPC adds namespace attribute to the <soap:body elements.

  • For Both DOC and RPC, service element is same.

Note: Try out all these combinations for a better understanding.

Which style of WSDL should I use?

The document/literal wrapped style is the best approach and is also the default. 

Wrapped document style with literal encoding has the following advantages:

1. There is no type encoding info.

2. Everything that appears in the soap:body is defined by the Schema, so you can easily validate the message.

3. You have the method name in the soap message.

4. Document/literal is WS-I compliant, but without the WS-I restriction that the SOAP.body should have only one Child. The wrapped pattern meets the WS-I restriction that the SOAP messages SOAP.body has only one Child. 

But in few cases you might have to use another style:

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

   1. WSDL allows overloaded operations, but 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.

   2. So you must use the document/literal, non-wrapped style or one of the RPC styles.

Please practice and complete the excercies for a better understanding.