Mapping between Java language, WSDL and XML for JAX-RPC applications

Data for Java API for XML-based Remote Procedure Call (JAX-RPC) applications flows as extensible Markup Language (XML). JAX-RPC applications use mappings to describe the data conversion between the Java language and extensible Markup Language (XML) technologies, including XML Schema, WSDL and SOAP supported by the application server.

For JAX-RPC applications, most of the mappings between the Java language and XML are specified by the JAX-RPC specification. Some mappings that are optional or unspecified in JAX-RPC are also supported. Review the JAX-RPC specification for a complete list of APIs. For a complete list of the supported standards and specifications, see the web services specifications and API documentation.

Notational conventions

Namespace prefix	Namespace
xsd	http://www.w3.org/2001/XMLSchema
xsi	http://www.w3.org/2001/XMLSchema-instance
soapenc	http://schemas.xmlsoap.org/soap/encoding/
wsdl	http://schemas.xmlsoap.org/wsdl/
wsdlsoap	http://schemas.xmlsoap.org/wsdl/soap/
ns	user-defined namespace
apache	http://xml.apache.org/xml-soap
wasws	http://websphere.ibm.com/webservices/

Detailed mapping information

The following sections identify the supported mappings, including:

• Java-to-WSDL mapping
• WSDL-to-Java mapping
• Mapping between WSDL and SOAP messages

Java-to-WSDL mapping

This section summarizes the Java-to-WSDL mapping rules. The Java-to-WSDL mapping rules are used by the Java2WSDL command for bottom-up processing. In bottom-up processing, an existing Java service implementation is used to create a WSDL file defining the web service. The generated WSDL file can require additional manual editing for the following reasons:

• Not all Java classes and constructs have mappings to WSDL files. For example, Java classes that do not comply with the Java bean specification rules might not map to a WSDL construct.
• Some Java classes and constructs have multiple mappings to a WSDL file. For example, a java.lang.String class can map to either an xsd:string or soapenc:string construct. The Java2WSDL command chooses one of these mappings, but we must edit the WSDL file if a different mapping is required.
• Multiple ways exist to generate WSDL constructs. For example, we can generate the wsdl:part in wsdl:message with a type or element attribute. The Java2WSDL command makes an informed choice based on the -style and -use option settings.
• The WSDL file describes the instance data elements sent in the SOAP message. To modify the names or format used in the message, the WSDL file must be edited. For example, the Java2WSDL command maps a Java bean property as an XML element. In some circumstances, we might want to change the WSDL file to map the Java bean property as an XML attribute.

• The WSDL file requires editing if header or attachment support is desired.

• The WSDL file requires editing if a multipart WSDL file, using the wsdl:import construct, is desired.

For simple services, the generated WSDL file is sufficient. For complicated services, the generated WSDL file is a good starting point. Read about the Java2WSDL command-line tool for Java API for XML-based Remote Procedure Call (JAX-RPC) applications to learn more about this tool.

General issues

• Package to namespace mapping:

  The JAX-RPC specification does not indicate the default mapping of Java package names to XML namespaces. The JAX-RPC specification does specify that each Java package must map to a single XML namespace. Likewise, each XML namespace must map to a single Java package. A default mapping algorithm is provided that constructs the namespace by reversing the names of the Java package and adding an http:// prefix. For example, a package named, com.ibm.webservice, is mapped to the XML namespace http://webservice.ibm.com.

  We can override the default mapping between XML namespaces and Java package names using the -NStoPkg and -PkgtoNS options of the WSDL2Java and Java2WSDL commands.

• Identifier mapping :

  Java identifiers are mapped directly to WSDL and XML identifiers.

  Java bean property names are mapped to XML identifiers. For example, a Java bean, with getInfo and setInfo methods, maps to an XML construct with the name, info.

  The service endpoint interface method parameter names, if available, are mapped directly to the WSDL and XML identifiers. See the information for the WSDL2Java command -implClass option to learn more.

• WSDL construction summary:

  Java construct	WSDL and XML construct
  Service endpoint interface	wsdl:portType
  Method	wsdl:operation
  Parameters	wsdl:input, wsdl:message, wsdl:part
  Return	wsdl:output, wsdl:message, wsdl:part
  Throws	wsdl:fault, wsdl:message, wsdl:part
  Primitive types	xsd and soapenc simple types
  Java beans	xsd:complexType
  Java bean properties	Nested xsd:elements of xsd:complexType
  Arrays	JAX-RPC defined xsd:complexType or xsd:element with a maxOccurs="unbounded" attribute
  User defined exceptions	xsd:complexType

• Binding and service construction

  A wsdl:binding that conforms to the generated wsdl:portType is generated. A wsdl:service containing a port that references the generated wsdl:binding is generated. The names of the binding and service are controlled by the Java2WSDL command.

• Style and use

  Use the -style and -use options to generate different kinds of WSDL files. The four supported combinations are:

  • -style DOCUMENT -use LITERAL
  • -style RPC -use LITERAL
  • -style DOCUMENT -use LITERAL -wrapped false
  • -style RPC -use ENCODED

  The following is a brief description of each combination.

  • DOCUMENT LITERAL:

    The Java2WSDL command generates a Web Services - Interoperability (WS-I) specification compliant document-literal WSDL file. The wsdl:binding is generated with embedded style="document" and use="literal" attributes. An xsd:element is generated for each service endpoint interface method to describe the request message. A similar xsd:element is generated for each service endpoint interface method to describe the response message.

  • RPC LITERAL:

    The Java2WSDL command generates a WS-I compliant rpc-literal WSDL file. The wsdl:binding is generated with embedded style="rpc" and use="literal" attributes. The wsdl:message constructs are generated for the inputs and outputs of each service endpoint interface method. The parameters of the method are described by the part elements within the wsdl:message constructs.

  • DOCUMENT LITERAL not wrapped:

    The Java2WSDL command generates a document-literal WSDL file according to the JAX-RPC specification. This WSDL file is not compliant with .NET. The main difference between DOCUMENT LITERAL and DOCUMENT LITERAL not wrapped is the use of wsdl:message constructs to define the request and response messages.

  • RPC ENCODED:

    The Java2WSDL command generates an rpc-encoded WSDL file according to the JAX-RPC specification. This WSDL file is not compliant with the WS-I specification. The wsdl:binding is generated with embedded style="rpc" and use="encoded" attributes. Certain soapenc mappings are used to represent types and arrays.

  Many Java types map directly to standard XML types. For example, a java.lang.String maps to an xsd:string. These mappings are described in the JAX-RPC specification.

  Java types that cannot be mapped directly to standard XML types are generated in the wsdl:types section. A Java class that matches the Java bean pattern is mapped to an xsd:complexType. Review the JAX-RPC specification for a description of all the mapping rules. The following example illustrates the mapping for a sample base and derived Java classes.

  Java:
  
  
  public abstract class Base {  
       public Base() {}  
       public int a;                         // mapped  
       private int b;                        // mapped via setter/getter  
       private int c;                        // not mapped  
       private int[] d;                      // mapped via indexed setter/getter  
  
       public int getB() { return b;}        // map property b  
       public void setB(int b) {this.b = b;}  
  
       public int[] getD() { return d;}      // map indexed property d  
       public void setD(int[] d) {this.d = d;}  
       public int getD(int index) { return d[index];}  
       public void setB(int index, int value) {this.d[index] = value;}  
  
       public void someMethod() {...}        // not mapped  
    }  
  
    public class Derived extends Base {  
       public int x;                         // mapped  
       private int y;                        // not mapped  
    } 
  
  Mapped to: 
  
  <xsd:complexType name="Base" abstract="true">  
  	<xsd:sequence>
  		<xsd:element name="a" type="xsd:int"/> 
  		<xsd:element name="b" type="xsd:int"/> 
  		<xsd:element name="d" minOccurs="0" maxOccurs="unbounded" type="xsd:int"/>
  	</xsd:sequence>
  </xsd:complexType>
  
  <xsd:complexType name="Derived">  
  	<xsd:complexContent>
  		<xsd:extension base="ns:Base"> 
  			<xsd:sequence>  
  				<xsd:element name="x" type="xsd:int"/>
  			</xsd:sequence>
  		</xsd:extension>
  	</xsd:complexContent>
  </xsd:complexType>
      
  
  

• Unsupported classes:

  If a class cannot be mapped to an XML type, the Java2WSDL command issues a message and an xsd:anyType reference is generated in the WSDL file. In these situations, modify the web service implementation to use the JAX-RPC compliant classes.

WSDL-to-Java mapping

The WSDL2Java command generates Java classes using information described in the WSDL file.

General issues:

• Mapping of a namespace to a package:

  JAX-RPC does not specify the mapping of XML namespaces to Java package names. JAX-RPC does specify that each Java package map to a single XML namespace. Likewise, each XML namespace must map to a single Java package. A default mapping algorithm omits any protocol from the XML namespace and reverses the names. For example, an XML namespace http://websphere.ibm.com becomes a Java package with the name com.ibm.websphere.

  The default mapping of an XML namespace to a Java package disregards the context-root. If two namespaces are the same up to the first slash, they map to the same Java package. For example, the XML namespaces http://websphere.ibm.com/foo and http://websphere.ibm.com/bar map to the com.ibm.websphere Java package. We can override the default mapping between XML namespaces and Java package names using the -NStoPkg and -PkgtoNS options of the WSDL2Java and Java2WSDL commands.

  XML names are much richer than Java identifiers. They can include characters that are not permitted in Java identifiers. See Appendix 20 of the JAX-RPC specification for the rules to map an XML name to a Java identifier.

• Java construction summary:

  The following table summarizes the XML to Java construction. See the JAX-RPC specification for a description of these mappings.

  WSDL and XML construction	Java construction
  xsd:complexType	Java bean class, Java exception class, or Java array
  nested xsd:element/xsd:attribute	Java bean property
  xsd:simpleType (enumeration)	JAX-RPC enumeration class
  wsdl:message The method parameter signature typically is determined by the wsdl:message.	Service endpoint interface method signature
  wsdl:portType	Service endpoint interface
  wsdl:operation	Service endpoint interface method
  wsdl:binding	Stub
  wsdl:service	Service interface
  wsdl:port	Port accessor method in Service interface

• Mapping standard XML types:
  • JAX-RPC simple XML types mapping:

    Many XML types are mapped directly to Java types. See the JAX-RPC specification for a description of these mappings.

    The WSDL2Java command generates Java types for the XML schema constructs defined in the wsdl:types section. The XML schema language is broader than the required or optional subset defined in the JAX-RPC specification. The WSDL2Java command supports the required mappings and most of the optional mappings, as well as some XML schema mappings that are not included in the JAX-RPC specification. The WSDL2Java command ignores some constructs that it does not support. For example, the command does not support the default attribute. If an xsd:element is defined with the default attribute, the default attribute is ignored. In some cases, the command maps unsupported constructs to the Java interface, javax.xml.soap.SOAPElement.

    The standard Java bean mapping is defined in section 4.2.3 of the JAX-RPC specification. The xsd:complexType defines the type. The nested xsd:elements within the xsd:sequence or xsd:all groups are mapped to Java bean properties. For example:

    XML:
    
     
    <xsd:complexType name="Sample">
    	 <xsd:sequence>
    		<xsd:element name="a" type="xsd:string"/>
    		<xsd:element name="b" maxOccurs="unbounded" type="xsd:string"/> 
    	</xsd:sequence>
    </xsd:complexType>
    
    Java:    
      
    public class Sample {  
         // ..  
         public Sample() {}  
    
         // Bean Property a  
         public String getA()             {...}  
         public void   setA(String value) {...}  
    
         // Indexed Bean Property b  
         public String[] getB()           {...}  
         public String   getB(int index)  {...}  
         public void     setB(String[] values) {...}  
         public void     setB(int index, String value) {...}  
    
      }
    
    

  • Mapping of the wsdl:portType construct:

    The wsdl:portType construct is mapped to the service endpoint interface. The name of the wsdl:portType construct is mapped to the name of the class of the service endpoint interface.

  • Mapping of the wsdl:operation construct:

    A wsdl:operation construct within a wsdl:portType is mapped to a method of the service endpoint interface. The name of the wsdl:operation is mapped to the name of the method. The wsdl:operation contains wsdl:input and wsdl:output elements that reference the request and response wsdl:message constructs using the message attribute. The wsdl:operation can contain a wsdl:fault element that references a wsdl:message describing the fault. These faults are mapped to Java classes that extend the exception, java.lang.Exception as discussed in section 4.3.6 of the JAX-RPC specification.

    • Effect of document literal wrapped format:

      If the WSDL file uses the document literal wrapped format, the method parameters are mapped from the wrapper xsd:element. The document literal wrapped and literal format is automatically detected by the WSDL2Java command. The following criteria must be met:

      • The WSDL file must have style="document" in its wsdl:binding construct.

      • The input and output constructs of the operations within the wsdl:binding must contain soap:body elements that contain use="literal".

      • The wsdl:message referenced by the wsdl:operation input construct must have a single part.

      • The part must use the element attribute to reference an xsd:element.

      • The referenced xsd:element, or wrapper element, must have the same name as the wsdl:operation.

      • The wrapper element must not contain any xsd:attributes.

      In such cases, each parameter name is mapped from a nested xsd:element contained within wrapper element. The type of the parameter is mapped from the type of the nested xsd:element. For example:

      WSDL:
      
      <xsd:element name="myMethod"> 
      	<xsd:complexType>
      		<xsd:sequence> 
      			<xsd:element name="param1" type="xsd:string"/>
      			<xsd:element name="param2" type="xsd:int"/> 
      		</xsd:sequence> 
      	</xsd:complexType>
      </xsd:element>
      ... 
      <wsdl:message name="response"/> 
      	<part name="parameters" element="ns:myMethod"/> 
      </wsdl:message name="response"/> 
      
      <wsdl:message name="response"/>
      ...
      <wsdl:operation name="myMethod"> 
      	<input name="input" message="request"/>  
      	<output name="output" message="response"/>  
      </wsdl:operation> 
      
      Java: 
      
      void myMethod(String param1, int param2) ... 
      

    • Parameter mapping:

      If the document and literal wrapped format is not detected, the parameter mapping follows the normal JAX-RPC mapping rules set in section 4.3.4 of the JAX-RPC specification.

      Each parameter is defined by a wsdl:message part referenced from the input and output elements.

      • A wsdl:part in the request wsdl:message is mapped to an input parameter.
      • A wsdl:part in the response wsdl:message is mapped to the return value. If multiple wsdl:parts exist in the response message, they are mapped to output parameters.
        • A Holder class is generated for each output parameter, as discussed in section 4.3.5 of the JAX-RPC specification.

      • A wsdl:part that is both the request and response wsdl:message is mapped to an inout parameter.
        • A Holder class is generated for each inout parameter, as discussed in section 4.3.5 of the JAX-RPC specification.

        • The wsdl:operation parameterOrder attribute defines the order of the parameters.

      XML:
      
      <wsdl:message name="request">
      	<part name="param1" type="xsd:string"/>
      	<part name="param2" type="xsd:int"/>
      </wsdl:message name="response"/>
      
      <wsdl:message name="response"/>  
      ...
      <wsdl:operation name="myMethod" parameterOrder="param1, param2">
      	<input name="input" message="request"/>
      	<output name="output" message="response"/>
      </wsdl:operation> 
      
      
      Java: 
      
      void myMethod(String param1, int param2) ... 
      

  • Mapping of wsdl:binding:

    The WSDL2Java command uses the wsdl:binding information to generate an implementation-specific client-side stub. WebSphere Application Server uses the wsdl:binding information on the server side to properly deserialize the request, invoke the web service, and serialize the response. The information in the wsdl:binding does not affect the generation of the service endpoint interface, except when the document and literal wrapped format is used, or when MIME attachments are present.

    • MIME attachments:

      For a WSDL 1.1-compliant WSDL file, the part of an operation message, defined in the binding as a MIME attachment, becomes a parameter of the type of the attachment regardless of the part declared. For example:

      XML:
      <wsdl:types>
      	<schema ...>
      		<complexType name="ArrayOfBinary">
      			<restriction base="soapenc:Array">
      			  <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]"/>
      			</restriction>
      		</complexType>
      	</schema>
      </wsdl:types>
      
      <wsdl:message name="request">
      	<part name="param1" type="ns:ArrayOfBinary"/>
      <wsdl:message name="response"/>
      
      <wsdl:message name="response"/>
       ... 
      
      	<wsdl:operation name="myMethod">
      		<input name="input" message="request"/>
      		<output name="output" message="response"/>
      	</wsdl:operation>
        ...
      
      <binding ...  
      	<wsdl:operation name="myMethod">
      		<input>
      			<mime:multipartRelated> 
      				<mime:part>
      					<mime:content part="param1" type="image/jpeg"/>
      				</mime:part>
      			</mime:multipartRelated>
      		</input>
      		 ...
      	</wsdl:operation>
      
      Java: 
      
      void myMethod(java.awt.Image param1) ... 
      

      The JAX-RPC specification requires support for the following MIME types:

      MIME type	Java type
      image/gif	java.awt.Image
      image/jpeg	java.awt.Image
      text/plain	java.lang.String
      multipart/*	javax.mail.internet.MimeMultipart
      text/xml	javax.xml.transform.Source
      application/xml	javax.xml.transform.Source

  • Mapping of wsdl:service:

    The wsdl:service element is mapped to a generated service interface. The generated service interface contains methods to access each of the ports in the wsdl:service element. The generated service interface is discussed in sections 4.3.9, 4.3.10, and 4.3.11 of the JAX-RPC specification.

    In addition, the wsdl:service element is mapped to the implementation-specific ServiceLocator class, which is an implementation of the generated service interface.

Read about the WSDL2Java command-line tool for Java API for XML-based Remote Procedure Call (JAX-RPC) applications to learn more about this tool.

---

Mapping between WSDL and SOAP messages

The WSDL file defines the format of the SOAP message that are transmitted through network connections. The WSDL2Java command and the WAS runtime use the information in the WSDL file to ensure that the SOAP message is properly serialized and deserialized.

If a wsdl:binding element indicates that a message is sent using an RPC format, the SOAP message contains an element defining the operation. If a wsdl:binding element indicates that the message is sent using a document format, the SOAP message does not contain the operation element.

If the wsdl:part element is defined using the type attribute, the name and type of the part are used in the message. If the wsdl:part element is defined using the element attribute, the name and type of the element are used in the message. The element attribute is not supported by the JAX-RPC specification when use="encoded".

If a wsdl:binding element indicates that a message is encoded, the values in the message are sent with xsi:type information. If a wsdl:binding element indicates that a message is literal, the values in the message are typically not sent with xsi:type information. For example:

DOCUMENT/LITERAL
WSDL:

<xsd:element name="c" type="xsd:int"/>
<xsd:element name="method">
	<xsd:complexType>
		<xsd:sequence>
			<xsd:element name="a" type="xsd:string"/>
			<xsd:element ref="ns:c"/>
		</xsd:sequence>
	</xsd:complexType>
</xsd:element>
...
		<wsdl:message name="request">	
				<part name="parameters" element="ns:method"/> 
		</wsdl:message>
	... 
	<wsdl:operation name="method"> 
		<input message="request"/> 
	...

Message:
<soap:body>
		<ns:method>
			<a>ABC</a>
			<c>123</a>
		<ns:method>
</soap:body>

RPC/ENCODED
WSDL: 
<xsd:element name="c" type="xsd:int"/>

...
		<wsdl:message name="request">	
				<part name="a" type="xsd:string"/>
				<part name="b" element="ns:c"/>
		</wsdl:message>
	... 
	<wsdl:operation name="method"> 
				<input message="request"/> 
	...

Message:
<soap:body> 
		<ns:method> 
			<a xsi:type="xsd:string">ABC</a>
			<element attribute is not permitted in rpc/encoded mode> 
		</ns:method>
	</soap:body>
 

DOCUMENT/LITERAL  not wrapped 
WSDL:
<xsd:element name="c" type="xsd:int"/>

...
		<wsdl:message name="request">	
				<part name="a" type="xsd:string"/>
				<part name="b" element="ns:c"/>
		</wsdl:message>
	... 
	<wsdl:operation name="method"> 
				<input message="request"/>

...

Message:
<soap:body>
		<a>ABC</a>
		<c>123</a> 
</soap:body>

Related:

WS-I Basic Profile

Implement web services applications with JAX-RPC

Implement web services applications from existing WSDL files with JAX-RPC

Java2WSDL command for JAX-RPC applications

WSDL2Java command for JAX-RPC applications

Web services specifications and APIs