With the previous two recipes, Creating a document transport web service and Creating a RPC transport web service, we addressed the transport style aspect of web service definition. This recipe will further address the usage of the SOAP binding. With the transport style, we get four combinations of possible usage as shown in the following table:
|
Transport style |
Use |
|---|---|
|
Document |
Literal |
|
Document |
Encoded |
|
RPC |
Literal |
|
RPC |
Encoded |
This recipe will give an explanation of all four combinations.
Open the BookLibraryImpl.java class in JDeveloper. Depending on the transport style and use, we modify the @SOAPBinding annotation in one of the following ways:
- Document transport style with literal use attribute:
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL)
- Document transport style with encoded use attribute:
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.ENCODED)
- RPC transport style with literal use attribute:
@SOAPBinding(style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.LITERAL)
- RPC transport style with encoded use attribute:
@SOAPBinding(style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.ENCODED)
That's it. Choosing any of these combinations defined results in a one-liner combination of attributes inside the @SOAPBinding annotation.
We will now explain what each of the transport style definitions and use attributes contribute to the resulting WSDL definition and how the definition is reflected within the SOAP request messages. We will explore the reserveBook operation.
The WSDL definition of the SOAP binding tag is defined as follows:
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>The reserveBook operation is defined in WSDL with the following code:
<wsdl:operation name="reserveBook">
<soap:operation soapAction=""/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="BookAlreadyBorrowed">
<soap:fault name="BookAlreadyBorrowed" use="literal"/>
</wsdl:fault>
</wsdl:operation>We identified the document transport style as well as the literal use of SOAP body formatting.
A sample of the SOAP request message is shown in the following code:
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<reserveBook xmlns="http://ws.java.packt.org/">
<arg0 xmlns="">1</arg0>
<arg1 xmlns="">1</arg1>
</reserveBook>
</env:Body>
</env:Envelope>The SOAP request message does not contain any type encoding info (they are empty). Also, it is possible to validate the content of the SOAP body element against the XML validator tool because all the elements are defined by the XSD schema.
The document transport style with the encoded use attribute is not supported by the JAX-WS annotations. Actually, no implementation follows this combination, since it lacks conformance to the web service interoperability specification.
Tip
The interoperability of web services is defined in the WS-I Basic Profile specification at http://ws-i.org/Profiles/BasicProfile-1.2-2010-11-09.html.
The WSDL definition of the SOAP binding tag is defined as shown in the following code:
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>The reserveBook operation is defined in WSDL as shown in the following code:
<wsdl:operation name="reserveBook">
<soap:operation soapAction=""/>
<wsdl:input>
<soap:body use="literal" namespace="http://ws.java.packt.org/" parts="arg0 arg1"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal" namespace="http://ws.java.packt.org/"/>
</wsdl:output>
<wsdl:fault name="BookAlreadyBorrowed">
<soap:fault name="BookAlreadyBorrowed" use="literal"/>
</wsdl:fault>
</wsdl:operation>We identified the RPC transport style as well as the literal use of SOAP body formatting.
A sample of the SOAP request message is shown in the following code:
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header />
<env:Body>
<target:reserveBook xmlns:target="http://ws.java.packt.org/">
<arg0>1</arg0>
<arg1>1</arg1>
</target:reserveBook>
</env:Body>
</env:Envelope>We can see a similar structure of SOAP request message as with the document/literal combination. Also, the SOAP request message does not contain any type encoding info (they are empty). In both cases, we see that the name of the operation is present in the SOAP message body. The distinction between the two concepts is in their ability to validate the body content of the SOAP request message. With the RPC/literal combination, we have trouble validating the content of the body because every element is defined inside the WSDL document and is not part of the schema.
Remember we said that the document/literal binding style is not fully compliant with WS-I Basic Profile. For that purpose, an additional transport and use combination is available; that is the document or literal-wrapped combination, which is fully compliant with WS-I Basic Profile and also uses the preferred binding style.
To use the document/literal-wrapped combination web service, we need to use the third parameter in the @SOAPBinding annotation as shown in the following code:
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)The javax.jws.soap.SOAPBinding.ParameterStyle enables two constants: BARE and WRAPPED. If we don't specify anything, the default value is BARE.
Let's compare the WSDL and SOAP message request between the document/literal and document/literal-wrapped styles.
The reserveBook operation is defined in WSDL as shown in the following code:
<wsdl:operation name="reserveBook">
<wsdl:input message="tns:reserveBookInput" xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl"
ns1:Action=""/>
<wsdl:output message="tns:reserveBookOutput" xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl"
ns1:Action=""/>
<wsdl:fault name="BookAlreadyBorrowed" message="tns:BookAlreadyBorrowed"/>
</wsdl:operation>Note that there is no literal use attribute defined in the WSDL document. Also, the SOAP request message remains the same when the client calls a web service.