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, Web Services Description Language (WSDL) and SOAP that are 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.
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/ |
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 information for the WSDL2Java command -implClass option to learn more.
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 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: 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.
The WSDL2Java command generates Java classes using information described in the WSDL file.
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.
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.
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.
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.
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.
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".
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>