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.
References to the JAX-RPC specification throughout 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 namespace 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 informationThe following sections identify the supported mappings, including:
Java-to-WSDL mappingThis 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:
For simple services, the generated WSDL file is sufficient. For complicated services, the generated WSDL file is a good starting point. General issues
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.
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 WSDL2Java command -implClass option for more details.
The following table summarizes 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 |
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.
The following is a brief description of each combination.
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.
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.
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.
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.
Mapping of standard XML types from Java types
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.
Generation of wsdl:types 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>
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
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.
Identifier mapping
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.
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 |
Many XML types are mapped directly to Java types. See the JAX-RPC specification for a description of these mappings.
Mapping the XML types defined in the wsdl:types section
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) {...} }
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.
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) ...
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.
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) ...
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 |
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.
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 WebSphere Application Server runtime use the information in the WSDL file to ensure that the SOAP message is properly serialized and deserialized.
DOCUMENT versus RPC, LITERAL versus ENCODED
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 allowed 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 concepts
Web Services-Interoperability Basic Profile
Related tasks
Developing Web services applications
Related reference
Java2WSDL command
WSDL2Java command
Multipart WSDL best practices
Web services: Resources for learning