Introduction

  1. The WSDL is an acronym for Web Services Description Language.
  2. The WSDL documents are represented in xml and validated against "http://schemas.xmlsoap.org/wsdl/" namespace.
  3. The wsdl document is used to provide description about web service such as Interface name(s), Method name(s), Parameter types, Return type, etc in XMLformat. Also, it provides Message format (such as SOAP), Network protocol (such as HTTP), Messaging style (such as Document or RPC), Encoding style (such as Literal or soap encoding) and Endpoint address (URL) that client must use to communicate with a service.
  4. The WSDL is well suited for code generation tools, which can read a WSDL document and generate a programmatic interfaces and network stubs. Such tools are part of Apache AXIS2, JAX-RPC, JAX-WS, IBM WebSphere, Microsoft.NET, etc.

Basic Structure of WSDL

WSDL is a Schema based document whose name space is "http://schemas.xmlsoap.org/wsdl/".
The WSDL document contains 7 important elements:

  1. definitions
  2. types
  3. message
  4. portType
  5. operation
  6. binding
  7. service.
  • The <wsdl:definitions> is the root element of the WSDL document.
  • The <wsdl:types> element uses XML schema language to declare application specific XML Data Types, XML Elements, and Exception types.
  • The <wsdl:message> element describes the payload of a message using xml schema simple types (buit-in types), Complex types, or Application specific XML Types (or XML Elements) defined using <wsdl:types> element.
  • The <wsdl:portType> element defines Service Endpoint Interface (SEI). This is analogous to a Jave interface. The <wsdl:portType> element describes the kinds of operations that a web service provides.
  • The <wsdl:operation> element describes one method in Service Endpoint Interface. This is analogous to a method declaration in interface. This element uses input, output, fault, message, types.
  • The <wsdl:binding> element is used to specify Message format (such as SOAP format), Transport protocol (such as HTTP, SMTP, etc), Messaging style (such as RPC or document), encoding styles (such as ‘literal’ or soap encoding).
  • The <wsdl:service> element is responsible for assigning an Endpoint address (URL) to a specific port (binding).

WSDL file Template

<?xml version="1.0" encoding= "UTF-8"?>
<wsdl:definitions targetNamespace="http://www.java2learn.com/ss/"
	xmlns:tns="http://www.java2learn.com/ss/"
	xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
	
<!--Define application specific xml element names and element types including application specific exception types.  
Element names are required in case of document style messaging.  
Element types are required in case of RPC style.-->
<wsdl:types>
 <xsd:schema>
 </xsd:schema>
</wsdl:types>
<!--message elements describe the input, output, and fault message-->

<!--input message-->
<wsdl:message>
   <!-- Can have multiple parts-->
   <wsdl:part/>
	----
   <wsdl:part/>
</wsdl:message>
<!--output message-->
<wsdl:message>
   <!-- Can have multiple parts-->
   <wsdl:part/>
	----
   <wsdl:part/>
</wsdl:message>
<!--fault message-->
<wsdl:message>
   <!--must have only one part-->
   <wsdl:part/>
</wsdl:message>

<!--portType element describes the abstract interface of a Web service.  
It becomes a Service Endpoint Interface (SEI) in java-->
<wsdl:portType>
	<wsdl:operation>
            <!--must have single input element-->
            <wsdl:input/>
            <!--almost one output element-->
            <wsdl:output/>
            <!--zero or more fault elements-->
            <wsdl:fault/>
	<wsdl:operation>
<wsdl:portType>

<!-- The <wsdl:binding> element is used to specify Message format (such as SOAP format), 
Transport protocol (such as HTTP, SMTP, etc), Messaging style (such as RPC or Document), Encoding, styles, (such as 'literal' or soap encoding)-->

<wsdl:binding>
<soap:binding style="rpc|document"/>
  <wsdl:operation name="…"/>
     <soap:operation soapAction="…"/>
     <wsdl:input>
	<soap:body parts=" " use="literal" encodingStyle="…"namespace="…"/>
     </wsdl:input>

     <wsdl:output>
	<soap:body parts=" " use="literal" encodingStyle="…"namespace="…"/>
     </wsdl:output>

        <!--Can have zero or more fault elements-->
     <wsdl:fault name="…">
	<soap:fault name="…" use="literal" namespace="…"/>
     </wsdl:fault>
  </wsdl:operation>
</wsdl:binding>

 <!-- Contains set of ports, each refers specific port.This element maps with service interface in Java.-->
 <wsdl:service>
    <wsdl:port>
            <!-- Endpoint address-->
            <soap:address location="end point uri"/>
    <wsdl:port>
 </wsdl:service>
</wsdl:definitions>

The ‘targetNamespace’ contains all the element and element types defined in the schema. Also, it contains portTypes, opernations, bindings, ports, etc.

<wsdl:types>

The <wsdl:types> element uses XML schema language to declare application specific XML Data Types, XML Elements, and Exception types.

In case of Document style messaging, the element names must be defined in <wsdl:types> element.
Example:

<wsdl:types>
  <xsd:schema targetNamespace="http://www.java2learn.com/ss/">
	<xsd:element name="concatRequest">
	     <xsd:complexType>
		     <xsd:sequence>
		         <xsd:element name="s1" type="xsd:string"/>
		         <xsd:element name="s2" type="xsd:string"/>
	         </xsd:sequence>
	      </xsd:complexType>
	  </xsd:element>
	  <xsd:element name="concatResponse" type="xsd:string"/>
  </xsd:schema>
</wsdl:types>

In case of RPC style messaging, element names are never required, but optionally element types, exception types can be declared.
Example:

<wsdl:types>
	<xsd:schema targetNamespace="http://www.java2learn.com/ss/">
	   <!--The ISBN simple type-->
	   <xsd:simpleType name="fnType">
	       <xsd:restriction base="xsd:string">
	          <xsd:pattern value="[a-z]*[A-Z]*"/>
	       </xsd:restriction>
	  </xsd:simpleType>

	  <xsd:complexType name="InvalidSymbolException">
	      <xsd:sequence>
	         <xsd:element name="message" type="xsd:string"/>
	      </xsd:sequence>
	  </xsd:complexType>
	</xsd:schema>
</wsdl:types>

<wsdl:message>

  1. The <wsdl:message> element can describes the payloads of incoming or outgoing messages.
  2. The different types of messages are Input, Output, or Fault message(s).
  3. The way to define a message element depends on whether we use RPC-style or Document-style messaging.

The message Element for Document-Style Web Services

  1. In case of document-style messaging, the message definition refers to a top-level element name in <wsdl:types> element i.e., document-style messaging exchanges XML document and refers to their top-level element name.
  2. In document style messaging, we can use only one part element.
  3. The ‘name’ attribute of the <wsdl:part> element is unimportant but required for wsdl validation.
    We have to use ‘element’ attribute of <wsdl:part> element.

Example:

<wsdl:defintions>
  <wsdl:types>
    <xsd:schema targetNamespace="http://www.java2learn.com/ss/">
	<xsd:element name="concatRequest">
	     <xsd:complexType>
		     <xsd:sequence>
		         <xsd:element name="s1" type="xsd:string"/>
		         <xsd:element name="s2" type="xsd:string"/>
	         </xsd:sequence>
	      </xsd:complexType>
	  </xsd:element>
	  <xsd:element name="concatResponse" type="xsd:string"/>
   </xsd:schema>
 </wsdl:types>

 <!--Input message-->
 <wsdl:message name="concatRequestMessage">
   <wsdl:part element="tns:concatRequest" name="parameters"/>
 </wsdl:message>
	
 <!--Output message-->
 <wsdl:message name="concatResponseMessage">
    <wsdl:part element="tns:concatResponse" name="parameters"/>
 </wsdl:message>
</wsdl:defintions>

In case of document-style messaging, the part element (must use ‘element’ attribute, which refers top-level element name which is declared in <wsdl:type> definition.
Document-style messaging exchanges XML Document Fragment and refers to their top-level (global) element name.

The message Element for RPC-Style Web Services

  1. In case of RPC-style messaging, the message element describes the payload of the SOAP request and SOAP response messages such as parameter types, return types, etc.
  2. The </wsdl:message> can have multiple part elements. The ‘name’ attribute of </wsdl:part> is required which becomes method parameter name. The ‘type’ attribute of </wsdl:part> refers xml date type, may be built in or application specific type.

Example:

<!-- Input message-->
<wsdl:message name="concatRequestMessage">
<!-- Can have multiple part elements.  The ‘name’ attribute is required which becomes method parameter name.  The ‘type’ attribute refers xml date type-->
     <wsdl:part name="s1" type="xsd:string"/>
     <wsdl:part name="s2" type="xsd:string"/>
<wsdl:message>

<!--Output message-->
<xsd:message name="concatResponseMessage"/>
     <!-- can have multiple part elements-->
     <wsdl:part name="result" type="xsd:string"/>
</wsdl:message>
<!--fault message-->
<wsdl:message name="InvalidSymbolException">
    <!-- fault message always contains single part, which becomes exception message in java-->
    <wsdl:part name="InvalidSymbolException" type="xsd:string"/>
</wsdl:message>

In case of RPC-style messaging the part element must use the ‘type’ attribute, which indicates parameters type of return type.
Both input and output messages in Web services can have multiple parts, which is against to Java method-call semantics, which accepts multiple inputs (parameters) but only once output (return value). The C++, C#, Perl supports multiple input & output parameters. WSDL is intended to be programming-language neutral, so it must be flexible enough to accommodate all programming languages, not just for java.

<wsdl:portType>

A portType defines the abstract interface of a Web Service i.e., it is analogous to Java interface, since portType element contains operations without implementation details. Such an interface is called as Service Endpoint Interface (SEI)
Example:

<wsdl:portType name="SimpleService">
	<wsdl:operation>
	</wsdl:operation>
	…
	<wsdl:operation>
	</wsdl:operation>
</wsdl:portType>

//Java interface

public interface SimpleService{
	//operation(s)
}

<wsdl:operation>

The <wsdl:operation> is analogous to method in an interface.
Each operation is composed of one input, one output element and any number of fault elements.

In case of Document style messaging, the ‘name‘ attribute of <wsdl:operation> element is un-important (not used in generated soap message) but required for wsdl file validation. Also, the ‘name’ attribute is required for wsdl2java tool to generate skeleton and stub classes.
Example

<wsdl:portType name="SimpleService">
	<wsdl:operation name="concat">
	<wsdl:input message="tns:concatRequestMessage"/>
	<wsdl:output message="tns:concatResponseMessage"/>
	</wsdl:operation>
</wsdl:portType>

//Java interface

Public interface SimpleService{
	public ConcatResponse concat(ConcatRequest ConcatRequest);
}

In case of RPC style messaging, the ‘name’ attribute of <operation> element becomes method name in Service Endpoint interface (SEI).

Example:

<wsdl:portType name="SimpleService">
	<!--name attribute is mandatory, which is method name in service -->
	<wsdl:operation name="concat">
	<wsdl:input message="tns:concatRequestMessage"/>
	<wsdl:output message="tns:concatResponseMessage"/>
	<wsdl:fault message="tns:InvalidSymbolException" name=" InvalidSymbolException"/>
	</wsdl:operation>
</wsdl:portType>

//Java interface

public interface SimpleService{
	public String concat(String s1, String s2) throws InvalidSymbolException;
}

//Exception type

public class InvalidSymbolException extends Exception{
	public InvalidSymbolException (String invalidSymbol) {
          super(invalidSymbol);
        }
}
  1. An input message represents the payload sent to the web service, and the output message represents the payload sent back to the client.
  2. In RPC-style messaging, the input is the request, and the output is the response.
  3. In Document-style messaging the input is the XML Document Fragment sent to the web service, and the output is the XML Document Fragment sent back to the client.
  4. An operation may include zero or more fault messages, each of which describes a different kind of error.

IN, OUT, INOUT Parameters

  1. The WSDL allows a Web service to declare IN, OUT, and INOUT parameters.
  2. While IN parameters are native to Java,but both OUT and INOUT parameters are not.
  3. Other programming languages such as C#, C++, Perl, etc supports IN, OUT, INOUT parameters.
  4. To accommodate OUT and INOUT parameters JAX-RPC (and JAX-WS) defines the javax-xml.holders.Holder interface.
Pass-by-Copy: IN parameters

The Java uses pass-by-copy for all primitive values and object references between method arguments and method parameters i.e., the value passed is a copy of the actual value but not original value.Hence,any changes made to parameters are strictly local to the method and no impact on calling program.

Example:

public static void main (String[] args){
	int a=1;
	String name=new String ("java2learn");
	m1(a, name); //method calling
	sop(a); //1
	sop(name); //java2learn
}

void m1(int a, String name) {//method parameters
	a=2;
	name=new String("technologies");
}

Pass-by-Copy parameters are known as IN parameters. All modern programming languages supports IN parameters.

Pass-by-Reference: OUT and INOUT parameters
  1. When a variable is passed by reference, the parameters refers to the same variable and same memory location i.e., method argument and method parameter refers to the same memory location. Hence, any changes make inside method body will be reflected for arguments in calling method.
  2. By default, Java does not supports Pass-by-Reference. Hence, JAX-RPC (and JAX-WS) uses Holder classes to support Pass-by-Reference.
  3. Other programming languages such as C++, C#, Perl supports Pass-by-Reference.
  4. Pass-by-Reference is either OUT or INOUT parameter.
  5. The OUT parameter ignores the value passed in (the method parameter is unassigned) but can assign a value to the parameter inside method block and sends it back to the calling method (client program).
  6. An OUT parameter is more like a return value rather than a parameter.

Example #1 Declaring OUT parameter in C#

void main(){
	int a;
	System.DateTime today;
	foo(a, today);
	sop(a); // 5
	sop(today); //date will be displayed.
}
public void foo(out int param1, out System.DateTime param2){
	param1 = 5;
	param2 = new Date(1970, 1, 1);

In case of INOUT, the method parameter is assigned with argument value. If any changes make inside method block, will be reflected to argument in calling method.

Example #2

Declaring INOUT parameter in C#

void main(){
	int a = 1;
	System.DateTime today = System.DateTime.NOW;
	foo(a, today);
	sop(a); //6
	sop(today); //changed date will be displayed.
}
public void foo(ref int x, ref System.DateTime y) {//'ref' means INOUT parameter
	x = x + 5;
	y = new Date(1970, 1, 1);
}

Conclusion: The difference between INOUT and OUT parameter is, in case of INOUT, the method parameter is assigned with argument value, but in case of OUT, the method parameter is unassigned.

Holder: Supporting INOUT and OUT parameters using JAX-RPC

  1. By default, Java does not supports Pass-by-Reference, Sometimes, our java client need to interact with Web Service written in other programming language those supports INOUT and OUT parameters. Hence, JAX-RPC uses Holder classes to support Pass-by-Reference.
  2. In JAX-RPC, for every INOUT or OUT parameter needs a separate Holder class.

Example C# Web Service that uses INOUT and OUT parameter.

public class FooBar{
	public void foo(ref int param1, out System. DateTime param2){
		param1 = param1 + 5;
		param2 = newSystem.DateTime(1970, 1, 1);
	}
}

Example> A jax-rpc endpoint interface that supports inout and out parameters using Holder classes.

import javax.xml.rpc.holder.IntHolder;
import javax.xml.rpc.holder.CalendarHolder;
public interface FooBar extends java.rmi.Remote{
	public void foo(IntHolder param1, CalendarHolder param2) throw java.rmi.RemoteException;
}

Example:Java Client code

IntHolder intHolder = new IntHolder(10);
CalendarHolder calendarHolder;
FooBar fooBarStub = fooBarService.getFooBarPort ();//get port
fooBarStub.foo(intHolder,calendarHolder);
sop(intHoder.value);//15
sop(calendarHoder.value);//changed date is displayed here

Note that the value of a Holder class is always available via the public static variable named value.

Mapping Holder Types from WSDL

JAX-RPC creates stubs from WSDL document. Hence, it is important to understand how INOUT and OUT parameters are defined in WSDL and mapped to JAX-RPC endpoints.
It is easy to tell whether a WSDL operation uses in, out or inout parameter by examining the <wsdl:part> elements from input and output messages.

Rules:
  1. If a part name is declared only by input message, then it’s an in parameter, which does not require Holder type.
  2. If same part element is declared in both input and output message, then it is INOUT parameter.Hence, Holder class is required.
  3. If the part element is only defined in the output message, indicating that is it either a Return value or an OUT parameter. If the part name is listed in parameterOrder attribute, then it is OUT parameter, otherwise it is Return value. Holder class is required for OUT parameter, but not required for return type.
  4. Note: Return type and OUT parameter are almost same but not exactly same.

  5. If the pameterOrder attribute is declared, then all input message parts must be listed. The output parts may or may not be listed.
  6. If there is a single unlisted output parameter in parameterOrder attribute, then that parameter is the return type of the method. Otherwise the return type is void i.e.,
    1. If all output part element(s) are listed in parameterOder attribute, then return type of the method is void.
    2. If none of the part element(s) are listed in parameterOrder attribute, then return type of the method is void.
    3. If more than one part elements are unlisted in parameterOrder attribute, then return type of the method is void.

Example:

<!--Input message-->
<message name = "fooRequest">
   <part name= "param1" type= "xsd:int"/>
   <part name= "param2" type= "xsd:double"/>
</message>
<!-- Output message-->
<message name = "fooResponse">
   <part name= "param2" type= " xsd:double"/>
   <part name= "param3" type= "xsd:dateTime"/>
   <part name= "param4" type= "xsd:float"/>
</message>
<portType name = "fooBoo">
  <operation name = "foo" parameterOrder="param1 param2 param3">
      <input message= "tns:fooRequest"/>
      <output message= "tns:fooResponse"/>
  <operation>
  <operation name = "foo1" parameterOrder="param1 param2 param3 param4">
      <input message= "tns:fooRequest"/>
      <output message= "tns:fooResponse"/>
  </operation>
  <operation name = "foo2" parameterOrder=param1 param2">
      <input message= "tns:fooRequest"/>
      <output message= "tns:fooResponse"/>
  </operation>
  <operation name = "foo3">
    <input message= "tns:fooRequest"/>
    <output message= "tns:fooResponse"/>
  </operation>
</portType>

The Endpoint interface generated from the portType defined above is:

import javax.xml.rpc.holders.DoubleHolder:
import javax.xml.rpc.holders.CalendarHolder:
public inteface FooBoo extends java.rmi.Remote{
public float foo(int param1, DoubleHolder param2, CalendarHolder param3) throws RemoteException;
public void foo1(int param1, DoubleHolder param2, CalendarHolder param3, FloatHolder param4) throws RE;
public void foo2(int param1, DoubleHolder param2, CalendarHolder param3, FloatHolder param4) throws RE;
public void foo3(int param1, DoubleHolder param2, CalendarHolder param3, FloatHolder param4) throws RE;
}

In WSDL, the operation names cannot be same since they cause interoperability problems, hence the Basic Profile prohibits operation overloading.

Messaging Exchange Patterns (MEPs)

There are 4 basic message exchange patterns:

  1. Request/Response
  2. One-Way
  3. Notification
  4. Solicit/Response

The Basic Profile supports only Request/Response and One-Way messaging.

Request/Response Messaging
  1. The client sends a Request message and the Web Service replies Response message. Hence, it is synchronous messaging.
  2. In case of Request/Response messaging, the <wsdl:operation> includes one <wsdl:input> element, one <wsdl:output> element, and zero or more <wsdl:fault> elements.

Example:

<wsdl:portType name="BookQuote">
	<wsdl:operation name="getBookPrice">
	<wsdl:input message="tns:GetBookPriceRequest"/>
	<wsdl:output message="tns:GetBookPriceResponse"/>
	<wsdl:fault name="InvalidArgumentFault" message="tns:InvalidArgumentFault"/>
	<wsdl:fault name="SecurityFault" message="tns:SecurityFault"/>
</wsdl:operation>
</wsdl:portType>
One-Way messaging
  1. The Client sends a Request message to a Web Service, but does’t expect reply message. Hence, it is asynchronous messaging.
  2. The <wsdl:operation> includes only <wsdl:input> element without <wsdl:output> and <wsdl:fault> elements.

Example

<wsdl:portType name="SubmitPurchaseOrder_PortType">
  <wsdl:operation name="SubmitPurchaseOrder">
     <wsdl:input message="tns:SubmitPurchaseOrderMessage"/>
  <wsdl:operation>
<wsdl:portType>

<wsdl:binding>

The <wsdl:binding> element is used to specify following details for every <wsdl:portType>

  1. Message format (such as SOAP format, HTTP format)
  2. Messaging style (such as Document or RPC)
  3. Encoding style (such as ‘literal’ or soap encoding)
  4. Transport protocol (such as HTTP, SMTP, etc)

The <wsdl:binding> element(including sub elements) is used in combination with protocol specific elements.
The <wsdl:binding> element identifies which portType and operation elements are being bound.
The protocol-specific elements declare the protocol, messaging style and encoding style to be associated with the portType.
Each type of protocol(SOAP,HTTP,etc) has it’s own set of protocol specific elements and it’s own namespace.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://www.java2learn.com/ss/"  xmlns:tns="http://www.java2learn.com/ss/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" name="SimpleService">
<!--the 'type' attribute refers portType-->
<wsdl:binding name="SimpleServiceSOAP" type="tns:SimpleService">
  <soap:binding transport="..." style="..." />
   <wsdl:operation name="...">
       <soap:operation soapAction="" />
       <wsdl:input>
          <soap:body use="..." namespace="..." />
       </wsdl:input>
       
        <wsdl:output>
          <soap:body use="..." namespace="..." />
       </wsdl:output>
       <!-- The <wsdl:fault> and <soap:fault> elements includes a mandatory name attribute ,which refers to a specific fault message-->
       <wsdl:fault name="">
            <soap:body use="literal" name="" />
       </wsdl:fault>
   </wsdl:operation>
</wsdl:binding>
</wsdl:definitions>

The ‘type‘ attribute refers portType.
The sub elements of the <wsdl:binding> element(such as <wsdl:operation>,<wsdl:input>,<wsdl:output> and <wsdl:fault>) directly maps with the corresponding sub elements of the portType element.

<soap-binding>

The <soap-binding> element specifies Message format(in this case SOAP format),Transport protocol(such as HTTP,SMTP,etc) used to transport SOAP messages and the default Messaging style(document or rpc) of it’s operations.

Example:

<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style ="document"/>
<wsdl:operation>

The ‘name’ attribute of <wsdl:operation> refers method name.This is a mandatory attribute.

In case of ‘rpc’ style messaging the value of the ‘name’ attribute is the method name and which is used in generated soap message.

Example: Generated SOAP message.

<soapenv:Body>
	<tns:concat xmlns:tns=http://www.java2learn.com/ss/">
		…
	</tns:concat>
</soapenv:Body>

In case of ‘document’ style messaging, the value of the name attribute is not used in generated SOAP message, but required for wsdl2java tool to generate skeleton and stub classes.Also, required for wsdl file validation.The same method names are used in skeleton and stub class.The XML Document Fragment will be the direct child element of the SOAP message.
Example:

<soapenv:Body>
	<!—XML Document Fragment will be the direct child element of soap message-->
	<tns:concatRequest xmlns:tns="http://www.java2learn.com/ss/">
	…
</ns1:concatRequest>
</soapenv:Body>
<soap:operation>

It is mainly used to specify the "soapAction" attribute. The "soapAction" attribute is used to tell the HTTP server (tomcat) that is a soap message and its purpose. It is up to the HTTP server to interpret the actual meaning.
Note: In case of AXIS, it will handle soap message but not tomcat.
The ‘soapAction’ attribute dictates, the value must be placed in the SOAPAction header field of the HTTP request message. It is an optional attribute.
Example:

	<soap:operation soapAction="firewall url" style ="rpc"/>

The corresponding SOAPAction header field is added to HTTP request header:

POST/ss HTTP/1.1
Host:www.java2learn.com
Content-Type: text/xml; charset="utf-8"
Content-Length: 295
SOAPAction: "firewall url"

We can optionally specify the messaging style(rpc or document) using ‘style’ attribute for a specific operation.However, which is not recommended according to WS-I.
Example:

	<soap:operation soapAction="" style="document | rpc"/>
<wsdl:input>

In case of rpc style messaging, all part names are sub elements of the operation name in generated SOAP message.

Example:Generated soap message.

<soapenv:Body>
   <tns:concat xmlns:tns="http://www.java2learn.com/ss/">
		<s1>ABC</s1>
		<s2>XYZ</s2>
   </tns:concat>
</soapenv:Body>

In case of document style messaging, part names are not used in generated SOAP message, rather, the element and sub element names are used.
Example: Generated soap message.

<soapenv:Body>
	<!--XML document fragment will be the direct child element of soap message-->
	<tns:concatRequest xmlns:tns="http://www.java2learn.com/ss/">
		<s1>ABC</s1>
		<s2>XYZ</s2>
	</tns:concatRequest>
</soapenv:Body>

<soap:body>

  1. The <soap:body> element is used to specify Encoding style (such as literal or soap encoding).
  2. The <soap:body> element have 4 attributes: use, encodingStyle, namespace, parts.
  3. The ‘use’ attribute is always ‘literal’.
  4. The ‘encodingStyle’ attribute is never used at all, because WS-I conformant Web Services are based on the W3C XML Schema, which is implied by the use=’literal’ declaration. Other encoding styles, like SOAP1.1 Encoding, are not used.
  5. The parts attribute names becomes sub elements of the operation name in the generated soap request message.This attribute is applicable only for RPC-style messaging.
  6. The ‘namespace’ attribute refers operation, parameter names. Hence, applicable only for RPC-style messaging.

In case of document style messaging, the namespace attribute must not be specified, rather, the namespace of the XML document fragment is derived from its XML schema. Also, the ‘parts‘ attribute must not be used.
Example: A ‘document’-style messaging does not require namespace and parts attributes.

<soap:body use="literal"/>

In case of rpc style messaging, the namespace attribute must be specified with a valid URI.Generally, the URI can be same as the targetNamespace of the WSDL document. Also, we can optionally use ‘parts’ attribute, which indicates sub elements of the operation name in the generated soap request message.

Example: A ‘rpc’-style messaging requires namespace and parts attributes.

<soap:body use="literal" namespace="http://www.java2learn.com/ss/" parts="s1 s2"/>
<wsdl:fault>

A <wsdl:fault> is mapped to java.rmi.RemoteException, javax.xml.rpc.soap.SOAPFaultException, or Service Specific java exception.
The <wsdl:fault> element contains <soap:fault> element.

<soap:fault>
  <wsdl:portType>
   <wsdl:operation name="getBookPrice">
     <wsdl:input name="tns:GetBookPriceRequest"/>
     <wsdl:output name="tns:GetBookPriceResponse"/>
     <wsdl:fault name="InvalidSymbolException" message="tns:InvalidSymbolException"/>
  <wsdl:operation>
<wsdl:portType>
<wsdl:binding>

 <soap:binding…/>
  <wsdl:operation>
  <soap:operation…/>
  <wsdl:input>
	…
  <wsdl:input>
  <wsdl:output>
	…
   <wsdl:output>
   <wsdl:fault name="InvalidSymbolException">
	<soap:fault name="InvalidSymbolException" use="literal" namespace="…"/>
    </wsdl:fault>
  </operation>
</binding>

The <wsdl:fault> and <soap:fault> elements include a mandatory name attribute, which refers to a specific fault message declared in the associated portType element.
The ‘use’ attribute in <soap:fault> element is always literal.

<wsdl:service>

The <wsdl:service> groups a set of service endpoints (or ports), with each service endpoint defined with specific port type, binding and endpoint address (port).

Example;

<wsdl:service name="CatalogService">
<wsdl:port name="CatalogPort" binding="tns:CatalogBinding">
	<! end point address-->
<soap:address location="http://localhost:9090/BookStoreWeb/getBookPrice"/>
</wsdl:port>
</wsdl:service>

The <wsdl:service> maps with Service interface in Java. The subclass of the service interface called service class acts as a factory of the following:

  1. Instance of a generated stub class.
  2. Instance of the type javax.xml.rpc.Call e.e., Dll Call interface.
  3. Instance of the Dynamic proxy.

The generated service interface is required to follow the design pattern:

  1. The service interface must be implemented from javax.xml.rpc.Service interface.
  2. The service interface name must be same as ‘name’ attribute of the <wsdl:service> element.
  3. For each <wsdl:port> defined in <wsdl:service> element must have get<name_of_wsdl_port>() method in service interface.
  4. All above methods throws ServiceException.

//Service interface

public interface CatalogService extends javax.xml.rpc.Service {
public Catalog getCatalogPort () throws ServiceException;
}
//service impl

public class CatalogService_Impl extends com.sun.xml.rpc.client.BasicServiceimplements CatalogService {
	public Catalog getCatalogPort () {
		Catalog_Stub stub=new Catalog_Stub(…);
		….
		return stub;
	}
}

Note:

Catalog_Stub is a subclass of Catalog interface.

Sample WSDL, file in RPC style

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http//schemas.xmlsoap.org/wsdl/soap/" name="SimpleService"
targetNamespace="http//www.java2spire.com/ss"xmlns:tns="http//www.java2spire.com/ss"
xmlns:wsdl="http//schemas.xmlsoap.org/wsdl/"xmlns:xsd="http//www.w3.org/2001/XMLSchema"/>
<! In case of rpc-style messaging, the <wsdl:type> is optional.  It is required only in case of declaring application specific xml types-->
<! input message-->
<wsdl:message name="concatRequestMessage">
<! Can have multiple part elements. The ‘name’ attribute is required which becomes method IN or INOUT parameter name.  The ‘type’ attribute refers xml date type-->
	<wsdl:part name="s1" type="xsd:string"/>
	<wsdl:part name="s2" type="xsd:string"/>
<wsdl:message>
<! output message-->
<wsdl:message name="concatResponseMessage">
<! Can have multiple part elements. The  ‘name’ attribute is required which becomes method OUT or INOUT parameter name.  The ‘type’ attribute refers xml date type-->
	<wsdl:part name="return" type="xsd:string"/>
<wsdl:message>

<! The <wsdl:portType> element maps with Service Endpoint Interface (SEI) in Java -->
<wsdl:portType name> "SimpleService"
<!—name attribute is mandatory, which is method name in service-->
<wsdl:operation name="concat" parameterOrder=s1 s2">
<wsdl:input message="tns:concatRequestMessage"/>
<wsdl:output message="tns:concatResponseMessage"/>
<wsdl:operation>
<wsdl:portType>
<wsdl:binding name="SimpleServiceSOAP" type=tns:SimpleService">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="concat">
<soap:operation soapAction="http://www.java2learn.com/ss/concat"/>
<wsdl:input>

<!--namespace attribute is mandatory-->
<!--Two message parts are listed.  In RPC style messaging, these are sub elements of the operation name.-->
<soap:body use="literal" namespace="http://www.java2learn.com/ss " parts=s1 s2"/>
<wsdl:input>
<wsdl:output>
<!--namespace attribute is mandatory-->
<soap:body use="literal" namespace="http://www.java2learn.com/ss"/>
<wsdl:output>
<wsdl:operation>
	<soap:binding>
	<! the <wsdl:service> element maps with Service Interface in Java -->
	<wsdl:service name= "SimpleService">
	<wsdl:port binding="tns:SimpleServiceSOAP" name="SimpleServiceSOAP">
		<soap:address location="http://localhost:9090/axis2/services/SimpleService"/>
	</wsdl:port>
	</wsdl:service>
</wsdl:definitions>

Simple SOAP message in RPC style
#SOAP Request
Operation names and part names are used in the SOAP message.
<?xml version="1.0" encoding= "UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope"/>
	<soapenv:Body>
	<tns:concat xmlns:tns="http://www.java2learn.com./ss">
		<s1>Kandepu</s1>
		<s2>Ramesh</s2>
	</tns:concat>
	</soapenv:Body>
</soapenv:Envelope>

#SOAP Response
<?xml version="1.0" encoding= "UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope"/>
	<soapenv:Body>
	<tns:concatResponse xmlns:tns="http://www.java2learn.com./ss">
		<return>Kandepu<return>
	</tns:concatResponse>
	</soapenv:Body>
</soapenv:Envelope>

Sample WSDL file in Document style
<?xml version="1.0" encoding= "UTF-8"?>
<wsdl:definitions name="SimpleService" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

targetNamespace="http://www.java2learn.com./ss" xmlns:tns="http://www.java2learn.com./ss"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
<! In case of document-style messaging, the <wsdl:Types> is mandatory which declares xml xml elements names.-->
	<wsdl:types>
	<!--XML Schema-->
	<xsd:schema targetNamespace="http://www.java2learn.com./ss/">
		<xsd:element name="concatRequest">
			<xsd:complexType>
		<xsd:sequence>
		<xsd:element name="s1" type="xsd:string"/>
		<xsd:element name="s2" type="xsd:string"/>
		</xsd:sequence>
			</xsd:complexType>
	</xsd:element>
		<xsd:element name="concatResponse type="xsd:string"/>
	<xsd:schema>
<wsdl:types>
<! input message-->
<wsdl:message name="concatRequest">
<!-- Must have only one part element-->
<!—“name” attribute is not used in SOAP message but required for wsdl file validation-->
<wsdl:part element="tns:concatResponse "name="parameters"/>
<wsdl:message>
<wsdl:portType name="SimpleService">
<!—‘name’ attribute is not used in SOAP message but required for wsdl file validation.  Also, required for wsdl2java tool to generate skeleton and stub classes.  Same method names are used skeleton-->
<wsdl:operation name="concat">
	<wsdl:input message="tns:concatRequestMessage"/>
	<wsdl:output message="tns:concatResponseMessage"/>
</wsdl:operation>
</wsdl:portType>
</wsdl:binding name="SimpleServiceSOAP" type="tns:SimpleService">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<!—‘name’ attribute is not used in SOAP message but required for wsdl2java tool to generate skeleton and stub classes.  Also, required for wsdl file validation.  Same method names are used in skeleton.-->
<wsdl:operation name=" concat">
	<soap:operation soapAction="http://www.java2learn.com./ss/concat"/>
<wsdl:input>
<!--namespace attribute must not be required-->
<soap:body use="literal"/>
<wsdl:input>
<wsdl:output>
<!--namespace attribute must not be required-->
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="SimpleService">
<wsdl:port name="SimpleServiceSOAP" binding="tns:SimpleServiceSOAP">
<wsdl:port name="SimpleServiceSOAP" binding="tns:SimpleServiceSOAP">
<soap:address location="http://localhost:9090/axis2/services/SimpleService"/>
</wsdl:port>
</wsdl:service
</wsdl:definitions>

Sample SOAP message in Document style

#SOAP request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope"/>
<soapenv:body>
<!--XML Schema Fragment-->
<! XML element and sub element namesare used but not operation and part names-->
<! XML element and sub element namesare used but not operation and part names-->
<tns:concatRequest xmlns:tns="http://www.java2learn.com/ss/">
		<s1>Kandepu</s1>
		<s2>Ramesh</s2>
</tns:concatRequest>
</soapenv:body>
</soapenv:Envelope>

#SOAP response

<?xml version="1.0" encoding= "UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope"/>
<soapenv:body>
<! XML element name but not operation name-->
<tns:concatResponse xmlns:tns="http://www.java2learn.com/ss/">kandepu Ramesh<tns:concatResponse>
</soapenv:Body>
</soapenv:Envelope>

Difference between RPC style and Document style messaging

RPC style messaging Document style messaging
The <wsdl:types>element is optional and contains project specific xml types. The <wsdl:types>element is mandatory and contains element names.
Multiple <wsdl:part> elements can present in both input and output message.
Use ‘type’ attribute to specify xml type.
The ‘name’ attribute of the <wsdl:part>
Only one <wsdl:part> elements should be present in both input and output message.
Use ‘element’ attribute of <wsdl:part> element which refers top level xml element name defined in schema.
element becomes method parameter, hence required and important. The ‘name’ attribute is unimportant but required.
Operation and part names are used in generated SOAP message. All part elements are sub elements of the operation name.

Example:

<soapenv:Body>
<tns:concat xmlns:tns="http://www.java2learn.com/ss/">
	<s1>one</s1>
	<s2>two</s2>
</tns:concat>
</soapenv:Body>
Operation and part names are not used in generated SOAP message. Rather, element and its sub element names are used. Hence, XML schema fragment is part of SOAP message.

Example:

<soapenv:Body>
<--XML document fragment will be the direct child element of soap message-->
<tns:concatRequest>
xmlns:tns="http://www.java2learn.com/ss/">
	<s1>one</s1>
	<s2>two</s2>
</tns:concatRequest>
</soapenv:Body>
Set style attribute as ‘rpc’for <soap:binding> element.
Both ‘namespace’ and ‘parts’ attributes are required for <soap:body> element.
Set style attribute as ‘document’ <soap:binding> element.
Both ‘namespace’ and ‘parts’ attributes are not required for <soap:body> element.
Cannot be validated against schema, since schema is not defined in wsdl file. Cannot be validated against schema, since schema is not defined in wsdl file.