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

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

  You can override the default mapping between XML namespaces and Java package names by 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:

  Table 2. Mapping of Java to WSDL or an XML construct . Describes the mapping from a Java construct to the related WSDL and XML construct.

  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.

• 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. You can override the default mapping between XML namespaces and Java package names by 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.

  Table 3. Mapping of a WSDL or an XML construct to Java . Describes the mapping between constructions for XML and Java.

  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 that are 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, that is 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:

      Table 4. Mapping of MIME type and Java type . Describes the mapping between MIME types and Java 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.

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>