The @SOAPBinding annotation can be used in a Service Endpoint Interface (SEI) to configure the soap binding style, encoding and parameter style; and we does this using style, use and parameterStyle attributes respectively.

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

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

Document style vs RPC style

• In document style, SOAP messages will contain full XML documents whereas in rpc style, SOAP messages contain parameters in the request messages and return values in the response messages.
• Document style can support services with rich, explicitly defined data types. In document style, the types section holds, points to, or imports an XSD. In rpc style, the types section is usually empty, as the service return only simple types.
• While under rpc-style, the messages carry the names of the @WebMethods operations. In unwrapped document style, the SOAP message does not carry the name of the service operation. The wrapped document convention provides a way to name the body of the SOAP message after the corresponding service operation.
• Document style can support any service pattern. RPC style supports only request-reply.
• From an architectural perspective, the document style is simpler as the body of the SOAP message is a self-contained with XSD. From developer perspective, rpc is simpler as wsgen utility is not required to generate java types that correspond to XML schema.
• Document style is the default style.

Pros of document style

1. The body of a SOAP message can be validated against the XSD given in the types section of the WSDL.
2. A service in document style can use rich data types.
3. There is a great flexibility in how the body of the SOAP message is structured as the structure is clearly defined in an XSD.
4. The wrapped document convention provides a way to add the major upside of rpc style to document style, which is naming the body of the SOAP message after the corresponding service operation.

Cons of document style

1. In unwrapped document style, the SOAP message does not carry the name of the service operation, which can complicate the dispatching of messages to the appropriate program code.
2. The wrapped document style adds a level of complexity, in particular at the API level. Writing a client against a wrapped document service can be more challenging.
3. The wrapped variant does not support overloaded service operations because the XML wrapper element in the body of a SOAP message must have the name of the service operation. In effect, then, there can be only one operation for a given element name.

Pros of RPC style

1. The automatically generated WSDL is relatively short and simple because there is no types section.
2. Messages in the WSDL carry the names of the underlying web service operations by default, which are @webMethods in a java-based service. The WSDL thus has a what-you-see-is-what-you-get style wrt the service’s operations.
3. Message throughput may improve because the messages do not carry any type encoding information.

Cons of RPC style

1. The WSDL, with its empty types section, does not provide an XSD against which the body of a SOAP message can be validated.
2. The service cannot use rich data types because there is no XSD to define such types.
3. Since RPC is associated with the request /response pattern, it encourages tight coupling between server and the client.
4. Long term support for rpc from web services community and the WS-I group is doubtful.

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. The setting use=”encoded” means that the services type definitions come from encoding rules, typically the encoding rules of SOAP 1.1 spec. 

Only literal is WS-I compliant and not “encoded” and hence ‘literal’ is preferred over ‘encoded’.  RPC/encoded was used before SOAP objects were defined with XML Schema; it is not much supported anymore. One of the few uses of the RPC/encoded style was for data graphs. Document/encoded is not used at all in practice as Document style uses an XML schema and encoding in not needed. Rpc/encoded wsdls are not supported in JAXWS 2.0+. 

Please find a simple example of an RPC encoded SOAP:

An RPC/encoded soap:

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

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

The contrast between wrapped and unwrapped in 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 in the Java code.

<soapenv : Body>

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

<return> 1234 </return>

</ans:getTimeAsElapsedResponse>

</soapenv:Body>

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

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:

• 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 and 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 literal and encoded, and document and rpc services comes down mainly to how things are specified in a wsdl.
• Rpc-Lit-Wrapped and Document-Lit-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.
• 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.
• 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.

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. If you have overloaded operations, you cannot use the document/literal wrapped style. 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. So you must use the document/literal, non-wrapped style or one of the RPC styles.