Mapping between Java language, WSDL and XML


This topic contains the mappings between the XML technologies, including XML Schema, WSDL and SOAP, supported by WAS. Most of these mappings are specified by the JAX-RPC specification.


Notational conventions

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

Namespace prefix Namespace
ns user defined namespace
wasws http../


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.


<xsd:complexType name="arrayOfInt">
        <xsd:restriction base:"soapenc:Array">
                <xsd:element name="item" type="xsd:int" maxOccurs="unbounded"/>

 <xsd:element name="array3" type="ns:arrayOfInt"/>


  int[] array3;

  • Mapping of xsd:simpleType enumeration

    The WSDL2Java command maps the following XML enumeration to a JAX-RPC specified enumeration class. See section 4.2.4 of the JAX-RPC specification for more details

    <xsd:simpleType name="EyeColorType">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="brown"/>
            <xsd:enumeration value="green"/>
            <xsd:enumeration value="blue"/> 

  • Mapping of xsd:complexType to exception class

    If a complexType is referenced in a wsdl:message for a wsdl:fault, the complexType is mapped to a class that extends the exception, java.lang.Exception. This mapping is similar to the mapping of a complexType to a Java bean class, except a full constructor is generated, and only getter methods are generated. See section 4.3.6 of the JAX-RPC specification for more details.

  • Other mappings

    The WSDL2Java command supports the mapping of xsd:simpleType and xsd:complexTypes that extend xsd:simpleTypes. These constructs are mapped to Java bean classes. The simple value is mapped to a Java bean property named, value. This is an optional feature of the JAX-RPC specification.

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

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

                <a xsi:type="xsd:string">ABC</a>
                <element attribute is not allowed in rpc/encoded mode> 
    DOCUMENT/LITERAL  wrapped: 
    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 that Deserialization produces a single instance of the info class for the encoded case and two instances are created for the literal case

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

    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

    <element name="foo" type="ns:ArrayOfString"/> 
    Literal Instance...
    <element name="foo" maxOccurs="unbounded" type="xsd:string"/> 
    Literal Instance...


    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.


    See Also

    Developing Web services based on Web Services for J2EE
    Java2WSDL command
    WSDL2Java command
    Multipart WSDL best practices
    Web services: Resources for learning