Mapping between Java language, WSDL and XML

This topic contains the mappings between the Java language and eXtensible Markup Language (XML) technologies, including XML Schema, Web Services Description Language (WSDL) and SOAP, supported by WebSphere Application Server. Most of these mappings are specified by the Java API for XML-based remote procedure call (JAX-RPC) specification. Some mappings that are optional or unspecified in JAX-RPC are also supported.

There are references to the JAX-RPC specification through this topic. You can review the JAX-RPC specification through Web services: Resources for learning.

Notational conventions

The following table specifies the namespace prefixes and corresponding namespaces used.

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

This section summarizes the Java-to-WSDL mapping rules. The Java-to-WSDL mapping rules are used by the Java2WSDL command tool 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:

For simple services, the generated WSDL file is sufficient. For complicated services, the generated WSDL file is a good starting point.

General issues

Mapping of standard XML types from Java types

Some Java types map directly to standard XML types. These types do not require additional XML definitions in the wsdl:types section.

Generation of wsdl:types

Java types that cannot be mapped directly to standard XML types are generated in the wsdl:types section.

Generation from the interface or implementation class

The class passed to the Java2WSDL command represents the interface of the wsdl:service. The wsdl:portType and wsdl:message elements generate from this interface or implementation class.

WSDL-to-Java mapping

The WSDL2Java command tool uses the following rules to generate Java classes when developing your Web services client and server. In addition, implementation specific Java classes are generated that assist in the serialization and deserialization, and invocation of the Web service.

General issues

Mapping standard XML types

Mapping XML defined in the wsdl:types section

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 by the JAX-RPC specification. The WSDL2Java command supports all required mappings and most optional mappings. In addition, the command supports some XML schema mappings that are outside the JAX-RPC specification. In general, the WSDL2Java command ignores constructs that it does not support. For example, the WSDL2Java 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 it maps unsupported constructs to wasws:SOAPElement.

Mapping of wsdl:portType

The wsdl:portType construct is mapped to the Service Endpoint Interface. The name of the wsdl:portType is mapped to the name of the class of the Service Endpoint Interface.

Mapping of wsdl:operation

A wsdl:operation 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.

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 should not affect the generation of the Service Endpoint Interface, but it can when the document and literal wrapped format is used or when there are MIME attachments.

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





Mapping between WSDL and SOAP messages



The
WSDL file defines the format of the SOAP message that is sent over the wire.
 The WSDL2Java command and the WebSphere Application Server run time
use the information in the WSDL file to confirm that the SOAP message is properly
serialized and deserialized.  



Document versus RPC, literal versus
encoded



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



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



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





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"/> 
	...
 
 





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






DOCUMENT/LITERAL: 
<soap:body>
	<a>ABC</a>
	<c>123</a>
</soap:body>






DOCUMENT/LITERAL  wrapped: 
<soap:body>
	<ns:method_wrapper>
		<a>ABC</a>
		<c>123</a>
	<ns:method_wrapper> 
</soap:body>
The document and literal wrapped mode is the same as
the document and literal mode.  However, in the document and literal wrapped
mode, there is only a single element within the body, and the element has
the same name as the operation.   



Multi-ref processing



If use=encoded,
XML types that are not simpleTypes are passed in the SOAP message using the multi-ref attributes, href and id.
The following example assumes that parameters one and two reference the same
Java bean named, info containing fields a and b:


Note: 
Deserialization produces a single instance of the info class
for the encoded case and two instances are created for the literal case.





RPC/ENCODED: 
<soap:body> 
	<ns:method> 
		<param1 href="#id1"/> 
		<param2 href="#id2"/> 
	<ns:method>
	<multiref id="id1" xsi:type="ns:info">
		<a xsi:type="xsi:string">hello<a>
		<b xsi:type="xsi:string">world</b>
	</multiref> 
</soap:body>







RPC/LITERAL: 
<soap:body> 
	<ns:method> 
		<param1> 
			<a>hello</a> 
			<b>world</b>
		</param1>
		<param2>
			<a>hello</a> 
			<b>world</b>
		</param2>
	<ns:method>
</soap:body>



XML arrays and the maxOccurs attribute



A
SOAP message is affected by whether the element is defined by an XML array
or using the maxOccurs attribute. 





WSDL: 
<element name="foo" type="ns:ArrayOfString"/> 

Literal Instance:

	<foo>
		<item>A</item> 
 		<item>B</item>
		<item>C</item>
	</foo>






WSDL: 
<element name="foo" maxOccurs="unbounded" type="xsd:string"/> 

Literal Instance:

	<foo>A</foo> 
 	<foo>B</foo>
	<foo>C</foo>
	



minOccurs and nillable attributes



An
element specified with minOccurs=0 that has a null value
is not serialized in the SOAP message.   An element specifying nillable="true" has
a null value and is serialized into a SOAP message with the xsi:nil=true attribute.
 For example:   





<a xsi:nil="true"/> 

  



Qualified versus unqualified



The XML schema attributeForm and elementForm attributes
indicate whether the attributes and nested elements are serialized with qualified
or unqualified names.  If a part name is serialized, it is always serialized
as an unqualified name. 



Related tasks

Developing Web services based on Web Services for J2EE

Related reference

Java2WSDL command

WSDL2Java command

Multipart WSDL best practices

Web services: Resources for learning