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
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../WAS51.ibm.com/webservices/

 

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:

• Not all Java classes and constructs have mappings to WSDL. For example, Java classes that do not comply with the Java bean specification rules might not map to a WSDL construct.

• Some Java classes and constructs have multiple mappings to WSDL. For example, a java.lang.String class can be mapped to either an xsd:string or soapenc:string. The Java2WSDL command chooses one of these mappings, but the WSDL file must be edited if a different mapping is desired.

• There are multiple ways to generate WSDL constructs. For example, the part element in the wsdl:message can be generated with a type or element attribute. The Java2WSDL command makes an informed choice based on the settings of the -style and -use options.

• The WSDL file describes the instance data elements sent in the SOAP message. If you want to modify the names or format used in the message, the WSDL file must be edited. For example, write a bean property value as an attribute instead of an element.

• The WSDL file requires editing if header or attachment support is desired.

• The WSDL file requires editing if a multipart WSDL, one using wsdl:import, is desired.

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

General issues

• Package to namespace mapping

  The JAX-RPC specification does not specify 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 namespace http://webservice.ibm.com.

  The default mapping between XML namespaces and Java package names can be overridden using the -NStoPkg and -PkgtoNS options of the WSDL2Java and Java2WSDL commands.

• Identifier mapping

  Java identifiers are mapped directly to WSDL file and XML identifiers.

  Java bean property names are mapped to the WSDL file and 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 XML identifiers. See the WSDL2Java command -implClass option for more details.

• WSDL construction summary

  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 (1)
  Return	wsdl:output, wsdl:message, wsdl:part (1)
  Throws	wsdl:fault, wsdl:message, wsdl:part (1)
  Primitive types	xsd and soapenc simple types
  Java beans	xsd:complexType
  Java bean properties	Nested xsd:elements of xsd:complexType
  Arrays	JAX-RPC defined array xsd:complexType
  User defined exceptions	xsd:complexType

  Note that The generated WSDL file is affected by the -style and -use options. A wsdl:binding that conforms to the generated wsdl:portType is generated. The style and use constructs of the wsdl:binding are determined from the -style and -use options. A wsdl:service containing a port that references the generated wsdl:binding is generated. The names and values of the wsdl:service are controlled by the Java2WSDL command options.

• Style and use

  Use the -style and -use options to generate different kinds of WSDL files. The four supported combinations are:

  • -style RPC -use ENCODED

  • -style DOCUMENT -use LITERAL

  • -style RPC -use LITERAL

  • -style DOCUMENT -use LITERAL -wrapped false

  The -use LITERAL option affects the generated WSDL file in the following ways:

  • The soap:body elements in the wsdl:binding are specified as use="literal".

  • The soap:fault elements in the wsdl:binding are specified as use="literal".

  • The soap encoded types are not used.

  • The soap encoded array style is not used. The maxOccurs attribute is used to indicate arrays.

  The -use ENCODED option affects the generated WSDL file in the following ways:

  • The soap:body elements in the wsdl:binding are specified as use="encoded" and the encodingStyle is set.

  • The soap:fault elements in the wsdl:binding are specified as use="encoded" and the encodingStyle is set.

  The -style RPC option affects the generated WSDL file in the following ways:

  • The wsdl:part elements use the type attribute to reference XML types.

  • The wsdl:binding is specified as style="rpc".

  The -style DOCUMENT -wrapped false option affects the generated WSDL file in the following ways:

  • The wsdl:part elements use the type attribute to reference simple types. The element attribute is used to reference the root xsd:elements for everything that is not a simple type.

  • The wsdl:binding is specified as style="document".

  The -style DOCUMENT -wrapped true option generates a WSDL file that conforms to the .NET WSDL file format:

  • A request xsd:element is generated for each method in the Service Endpoint Interface as follows...

    • The name of the xsd:element is the same as the name of the wsdl:operation.

    • The xsd:element contains an xsd:sequence that contains xsd:elements defining each parameter.

    • The request wsdl:message references the wrapper xsd:element using a single part...

      • The name of the part is parameters.

      • The element attribute is used to reference the wrapper xsd:element.

  • A response xsd:element is generated for each method in the Service Endpoint Interface as follows...

    • The name of the xsd:element is the same as the name of the wsdl:operation appended with Response

    • The xsd:element contains an xsd:sequence that contains xsd:elements defining the return value.

    • The request wsdl:message references this wrapper xsd:element using a single part.

      • The element attribute is used to reference the wrapper xsd:element.

  • The wsdl:binding is specified as style="document".

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.

• JAX-RPC Java primitive type mapping

  The following table describes the mapping from the Java primitive and standard types to XML standard types. For more information see the JAX-RPC specification.

  Java type	XML type
  int	xsd:int
  long	xsd:long
  short	xsd:short
  float	xsd:float
  double	xsd:double
  boolean	xsd:boolean
  byte	xsd:byte
  byte[]	xsd:base64Binary Note that The default mapping for byte[] is xsd:base64Binary. The data in byte[] is passed over the wire as a text string encoded in the base64 format. An alternative format is xsd:hexBinary. To use the xsd:hexBinary format: Edit the WSDL file and change xsd:base64Binary to xsd:hexBinary.
  java.lang.String	xsd:string
  java.math.BigInteger	xsd:integer
  java.math.BigDecimal	xsd:decimal
  java.util.Calendar	xsd:dateTime
  java.util.Date Note that This mapping is not covered by the JAX-RPC.	xsd:date
  java.lang.Boolean	xsd:boolean xsi:nillable=true
  java.lang.Float	xsd:float xsi:nillable=true
  java.lang.Double	xsd:double xsi:nillable=true
  java.lang.Long	xsd:long xsi:nillable=true
  java.lang.Integer	xsd:int xsi:nillable=true
  java.lang.Short	xsd:short xsi:nillable=true
  java.lang.Byte	xsd:byte xsi:nillable=true

  Note that The java.lang wrapper classes in the last seven lines of the table map to the same XML construct as the corresponding Java primitive type. In addition, the xsi:nillable attribute is generated to indicate that such elements can be null.

• Additional Java class mappings

  In addition to the standard JAX-RPC mapping, the following classes are mapped directly to XML types...

  Java type	XML type
  java.util.Map Note that Any classes that implement java.util.Map are also mapped to apache:Map.	apache:Map
  java.util.Collection Note that Each Java array, except byte[], and every class that implements java.util.Collection is mapped to a JAX-RPC defined soapenc:Array type.	soapenc:Array
  org.w3c.dom.Element	apache:Element
  java.util.Vector	apache:Vector
  java.awt.Image Note that Used for attachment support.	apache:Image
  javax.mail.internet.MimeMultiPart Note that Used for attachment support.	apache:Multipart
  javax.xml.transform.Source Note that Used for attachment support.	apache:Source
  javax.activation.DataHandler Note that Used for attachment support.	apache:DataHandler

Generation of wsdl:types

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

• Java arrays

  Java arrays for the -use ENCODED option, with the exception of byte[], are generated using the following format. See the JAX-RPC specification for more details. Alternative mappings can be found in Table 18.1 of the JAX-RPC specification

  Java...
  
  
    Item[] 
  
  Mapped to: 
  
     
  <xsd:complexType name="ArrayOfItem"> 
  
      <xsd:complexContent>
          <xsd:restriction base="soapenc:Array">
              <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="ns:Item"/> 
          </xsd:restriction>
       </xsd:complexContent
  </xsd:complexType> 
  
  

• JAX-RPC value type and bean mapping

  A Java class that matches the Java value type or bean pattern is mapped to an xsd:complexType. In order for a Java class to be mapped to XML, follow these conditions:

  • The class must have a public default constructor.

  • The class must not implement, directly or indirectly, java.rmi.Remote.

  • Public, non-static, non-final, non-transient fields are mapped. The class can contain other fields and methods, but they are not mapped.

  • If the class follows the Java bean pattern and has public getter and setter methods, the property is mapped.

  Additional mapping rules can be found in the JAX-RPC specification. The following example indicates the mapping for 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>
      
  
  
  

  Inheritance and abstract classes

  The example contains two optional JAX-RPC features that are supported by WebSphere Application Server:

  1. An abstract class is mapped to an xsd:complexType with abstract="true".

  2. An indexed bean property (see the methods for d in Base) are mapped to a nested element specified with maxOccurs="unbounded". This format is similar to an XML array, but the SOAP message is different. An XML array defines an element for the array and nested elements for each item in the array. An element defined with maxOccurs indicates a series of items without the surrounding array wrapper element. Both formats are popular.

• JAX-RPC enumeration class mapping

  Section 4.2.4 of the JAX-RPC specification defines the mapping from an XML enumeration to a Java class. Though not specifically required by the JAX-RPC, the Java2WSDL command performs the reverse mapping. If you have a class that has the same format as a JAX-RPC enumeration class, it is mapped to an XML enumeration.

• Holder classes

  The JAX-RPC specification defines Holder classes in section 4.3.5. A Holder class is used to support in and out parameter passing. Every Holder class implements thejavax.xml.rpc.holders.Holder interface. The Java2WSDL command maps Holder classes to the same XML type as the held type. In addition, references to Holder classes affect the generation of wsdl:messages.

• Exception classes

  If a class extends the exception, java.lang.Exception, it is mapped to an xsd:complexType similar to the Java bean mapping. The getter methods of the exception are mapped as nested xsd:elements of the xsd:complexType. See section 5.5.5 of the JAX-RPC specification for more details.

  You need to generate implementation specific exception classes by invoking the WSDL2Java command on the resulting WSDL file.

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

• Generation of root elements

  If the Java2WSDL command generates an xsd:complexType or xsd:simpleType for a parameter reference, a corresponding xsd:element is also generated. The xsd:element has the same name as the xsd:complexType/xsd:simpleType and uses the type attribute to reference the xsd:complexType/xsd:simpleType. The wsdl:message part can use the element attribute or the type attribute to reference the xsd:element or type. This choice is determined by the -style and -use options.

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.

• Generation of the wsdl:portType

  The name of the wsdl:portType is the name of the class unless overridden by the -portTypeName option.

• Generation of wsdl:operation

  A wsdl:operation generates for each public method in the interface that throws the exception, java.rmi.RemoteException.

  • The name of the wsdl:operation is the name of the method.

  • The wsdl:operation has a parameterOrder attribute, which defines the order of the parameters in the signature. Specifically, the parameterOrder lists the order of the parts of the request or response wsdl:messages.

  • The wsdl:operation has a nested wsdl:input element that references the request wsdl:message using the message attribute.

  • The wsdl:operation has a nested wsdl:output element that references the response wsdl:message using the message attribute.

  • The wsdl:operation has a nested wsdl:fault element that references the default wsdl:message using the message attribute.

  See sections 5.5.4 and 5.5.5 of the JAX-RPC specification for more information.

• Generation of wsdl:message

  Generating the wsdl:message is directly related to the -style and -use options. The following is the default mapping (-style RPC -use ENCODED):

  • A wsdl:message is created to represent the request.

    • A wsdl:part representing each parameter is added to the wsdl:message.

      • The wsdl:part has the same name as the parameter.

      • The wsdl:part uses the type attribute to locate the XML type of the parameter.

  • A wsdl:message is created to represent the response:

    • A wsdl:part representing the method return is created.

      • The wsdl:part has the same name as the method with Return appended.

        Note that The name of the part is not specified by the JAX-RPC and is typically not checked by SOAP engines.

      • The wsdl:part has the same name as the parameter.

      • The wsdl:part uses the type attribute to locate the XML type of the parameter.

      • A wsdl:part is created for each parameter that is a Holder.

      • The wsdl:part has the same name as the parameter.

      • A wsdl:message is created to represent the fault if the operation has a wsdl:fault.

      • A wsdl:part representing the fault is created.

      • The wsdl:part has the same name as the exception.

      • The wsdl:part uses the type attribute to locate the complexType representing the exception.

  The same mapping is used as described if you use the -style RPC and -use LITERAL options. It is also valid to use the wsdl:part element attribute instead of the type attribute to reference the XML schema. If you use the -style DOCUMENT -wrapped false and -use LITERAL options, the same mapping is used as described except the wsdl:part element attribute is used to reference the XML schema. If the XML schema is a primitive type, like xsd:string, the type attribute is used to reference the XML type. The -style DOCUMENT, -wrapped true and -use LITERAL options result in completely different mappings for the request and response messages. For example...

  • A request xsd:element is generated for each method in the Service Endpoint Interface.

    • The name of the xsd:element is the same as the name of the wsdl:operation.

    • The xsd:element contains an xsd:sequence that contains xsd:elements defining each parameter.

    • The request wsdl:message references the wrapper xsd:element using a single part.

      • The name of the part is parameters.

      • The element attribute is used to reference the wrapper xsd:element.

  • A response xsd:element is generated for each method in the Service Endpoint Interface.

    • The name of the xsd:element is the same as the name of the wsdl:operation appended with Response.

    • The xsd:element contains an xsd:sequence that contains xsd:elements defining the return value.

    • The request wsdl:message references this wrapper xsd:element using a single part.

      • The element attribute is used to reference the wrapper xsd:element.

• Generation of wsdl:binding

  Generate a wsdl:binding with a name defined by the Java2WSDL -bindingName command.

  • The wsdlsoap:binding style attribute is set to rpc if you use the -style RPC option; otherwise it is set to document.

  • A wsdl:operation generates for each wsdl:operation defined in the wsdl:portType.

  • Each wsdl:operation has corresponding wsdl:input, wsdl:output and wsdl:fault elements.

  • The wsdl:input, wsdl:output and wsdl:fault elements each contain a wsdlsoap:body element.

  • The wsdlsoap:body use attribute is set to literal or encoded according to the -use argument. Set the encodingStyle attribute to http://schemas.xmlsoap.org/soap/encoding/ when use is encoded.

• Generation of the wsdl:service

  Generate a wsdl:service with a name defined by the Java2WSDL -serviceElement command. For example...

  • The wsdl:service contains a port with a name defined by the Java2WSL -servicePortName command.

  • The port references the generated wsdl:binding with the binding attribute.

  • The port contains a wsdlsoap:address element with a

  • The location attribute is set to the value of the Java2WSDL -location command.

 

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 of namespace to package

  The JAX-RPC does not specify the mapping of XML namespaces to Java package names. The 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../WAS51.ibm.com becomes a Java package with the name com.ibm.websphere.

  The default mapping of XML namespace to Java package disregards the context-root. If two namespaces are the same up until the first slash, they map to the same Java package. For example, the XML namespaces http../WAS51.ibm.com/foo and http../WAS51.ibm.com/bar map to the Java package com.ibm.websphere. The default mapping between XML namespaces and Java package names can be overridden using the -NStoPkg and -PkgtoNS options of 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 section 20 of the JAX-RPC specification for the rules to map an XML name to a Java identifier.

  The mapping rules attempt to follow accepted Java coding conventions. Class names always begin with an uppercase letter. Method names begin with a lowercase letter. The WSDL2Java command generates metadata in the _Helper class so that the values are serialized or deserialized using the XML names specified in the WSDL file.

• Java construction summary

  WSDL and XML	Java
  xsd:complexType (struct) Note that The xsd:complexType can also represent a Java exception if referenced by a wsdl:message for a wsdl:fault .	Java Bean Class Note that The classes, _Helper, _Ser, and _Deser, generate for each Java bean class. These implementation classes aid serialization and deserialization.
  nested xsd:element/xsd:attribute	Java bean property
  xsd:complexType (array)	Java array
  xsd:simpleType (enumeration)	JAX-RPC enumeration class
  xsd:complexType (wrapper)The method parameter signature typically is determined by the wsdl:message. However, if the WSDL file is a .NET wrapped style, the method parameter signature is determined by the wrapper xsd:element	Service Endpoint Interface method parameter signature If a parameter is out or inout, a Holder class generates.
  --	--
  wsdl:messageThe method parameter signature typically is determined by the wsdl:message. However, if the WSDL file is a .NET wrapped style, the method parameter signature is determined by the wrapper xsd:element	Service Endpoint Interface method signature If a parameter is out or inout, a Holder class generates.
  wsdl:portType	Service Endpoint Interface
  wsdl:operation	Service Endpoint Interface method
  wsdl:binding	Stub Note that The Stub and ServiceLocator classes are implementation specific.
  wsdl:service	Service Interface and ServiceLocator Note that The Stub and ServiceLocator classes are implementation specific.
  wsdl:port	Port accessor method in Service Interface

Mapping standard XML types

• JAX-RPC simple XML types mapping

  The following mappings are XML types to Java types. For more information about these mappings, see section 4.2.1 of the JAX-RPC specification.

  XML type	Java type
  xsd:string	java.lang.String
  xsd:integer	java.math.BigInteger
  xsd:int Note that If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.	int
  xsd:long Note that If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.	long
  xsd:short Note that If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.	short
  xsd:decimal	java.math.BigDecimal
  xsd:float Note that If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.	float
  xsd:double Note that If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.	double
  xsd:boolean Note that If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.	boolean
  xsd:byte Note that If an element with this type has the xsi:nillable attribute set to true, it is mapped to the Java wrapper class of the primitive type.	byte
  xsd:dateTime	java.util.Calendar
  xsd:date Note that This mapping is not supported by the JAX-RPC.	java.util.Date
  xsd:base64Binary	byte[]
  xsd:hexBinary	byte[]
  --	--
  soapenc:base64	byte[]
  soapenc:base64Binary	byte[]
  soapenc:string	java.lang.String
  soapenc:boolean	java.lang.Boolean
  soapenc:float	java.lang.Float
  soapenc:double	java.lang.Double
  soapenc:decimal	java.math.BigDecimal
  soapenc:int	java.lang.Integer
  soapenc:integer Note that This mapping is not supported by the JAX-RPC.	java.math.BigInteger
  soapenc:short	java.lang.Short
  soapenc:long Note that This mapping is not supported by the JAX-RPC.	java.lang.Long
  soapenc:byte	java.lang.Byte

• JAX-RPC optional simple XML type mapping

  The WSDL2Java command supports the following JAX-RPC optional simple XML types.

  XML type	Java type
  xsd:qname	javax.xml.namespace.QName

• JAX-RPC xsd:anyType mapping

  The WSDL2Java command maps an xsd:anyType to a java.lang.Object. This is an optional feature of the JAX-RPC specification. The xsd:anyType can be used to store any XML type other than the XML primitive type. An xsd:anyType is always serialized along with an xsi:type that specifies the actual type.

• Additional supported mappings

  The following mappings are also supported by the WSDL2Java command. These mappings are not defined by the JAX-RPC specification.

  XML type	Java type
  apache:PlainText Note that For MIME attachments.	java.lang.String
  apache:Map	java.util.Map
  apache:Element	org.w3c.dom.Element
  apache:Vector	java.util.Vector
  apache:Image Note that For MIME attachments.	java.awt.Image
  apache:Multipart Note that For MIME attachments.	javax.mail.internet.MimeMultipart
  apache:Source Note that For MIME attachments.	javax.xml.transform.Source
  apache:octetStream Note that For MIME attachments.	javax.activation.DataHandler
  apache:DataHandler Note that For MIME attachments.	javax.activation.DataHandler

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 xsd:complexType to Java bean

  The most common mapping is from an xsd:complexType to a Java bean class.

  • Standard Java bean mapping

    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) {...}  
    
      }
    
    
    

  • Methods equals() and hashCode()

    The generated Java bean classes contain an implementation of the equals() method. The generation of this method is outside the JAX-RPC specification. The equals() method returns true if equals() is true for each contained bean property. The implementation accounts for self-referencing loops. This version of the equals() method is typically more useful than the "identity" equals provided by java.lang.Object.

    A corresponding hashCode() method is also generated in the Java bean class.

  • Properties and indexed properties

    In the standard Java bean mapping example, the nested xsd:element for property a is mapped to a Java bean property. In addition, the WSDL2Java command maps a nested xsd:element with maxOccurs > 1 to a Java bean indexed property.

  • Attributes

    The WSDL2Java command also supports the xsd:attribute element, as shown in the following example.

    Attribute a is mapped as a Java bean property, which is exactly the same mapping as a nested xsd:element. Implementation specific metadata is generated in the Sample2_Helper class to ensure that property a is serialized and deserialized as an attribute, and not as a nested element. For example

    XML...
    
    <xsd:complexType name="Sample2">  
            <xsd:sequence>  
                <xsd:attribute name="a" type="xsd:string"/>
            </xsd:sequence>
    </xsd:complexType>
    
      
    Java:  
    
    public class Sample2 {  
         // ..  
         public Sample2() {}  
    
         // Bean Property a  
         public String getA()             {...}  
         public void   setA String(value) {...}  
      }
          
    
    
    

  • Qualified versus unqualified names

    The WSDL2Java command supports the elementForm and attributeForm schema attributes.

    This support is not specified in the JAX-RPC specification. These attributes are used to indicate whether an element or attribute is serialized and deserialized with a qualified or unqualified name. The default setting for elementForm is qualified and the default setting for attributeForm is unqualified. These settings do not affect the Java bean class that is generated, but the information is captured in the _Helper class metadata.

  • Extension and the abstract attribute

    The WSDL2Java command supports extension of an xsd:complexType through the xsd:extension element. This support is required by the JAX-RPC specification.

    The WSDL2Java command supports the abstract attribute. This feature is listed as optional by the JAX-RPC specification.

    The following example shows the accepted use of the extension and abstract constructs. WAS uses the extension and abstract constructs to support polymorphism

    XML: 
    
    <xsd:complexType name="Base" abstract="true">  
        <xsd:sequence>
            <xsd:element name="a" type="xsd:int"/>
        </xsd:sequence>
    </xsd:complexType>  
    
    <xsd:complexType name="Derived">
        <xsd:complexContent> 
            <xsd:extension base="ns:Base">
                <xsd:sequence> 
                    <xsd:element name="b" type="xsd:int"/>
                </xsd:sequence>
            </xsd:extension>
        </xsd:complexContent>
    </xsd:complexType>
    
    Java:  
       public abstract class Base {  
          // ...  
          public Base() {}  
    
          public int getA() {...}  
          public void setA(int a) {...}  
       }  
    
       public class Derived extends Base {  
          // ...  
          public Derived() {}  
    
          public int getB() {...}  
          public void setB(int b) {...}  
       }  
     
       
        
     
     
    
    
    

  • Support for xsd:any

    The WSDL2Java command supports xsd:anyelement, which is different than xsd:anyType. This feature is not defined within the JAX-RPC specification and is subject to change.

    If an <xsd:any/> element is defined within xsd:sequence or xsd:all group, SOAP values that do match one of the xsd:elements are stored in the Java bean. Values can be accessed from the Java bean using the get_any() and set_any() methods.

• Mapping of xsd:element

  An xsd:element is a construct that has a name or name attribute, and a type defined by a complexType or primitive type. There are two different kinds of xsd:elements:

  • Root: Defined directly underneath the schema elements and referenced by other constructs.

  • Nested: Nested underneath group elements and are not referenced by other constructs.

  Root elements are referenced by the WSDL file constructs, especially if the WSDL file is used to describe a literal service. Typically, root elements and types have the same names, which is allowed in the schema language. Under most circumstances the WSDL2Java command can produce Java artifacts without name collisions.

  • Four ways to reference a type

    There are four ways that a nested or root xsd:element can reference a type...

    • Use the type attribute:

      This is the most common way to reference a type...

      <xsd:element name="one" type="ns:myType"/> 
      

      The WSDL2Java command recognizes the type attribute as a reference to a complexType or simpleType named, myType. The WSDL2Java command generates a Java type based on the characteristics of myType. Support for the type attribute is required by the JAX-RPC specification.

    • Use the ref attribute: For example...

      <xsd:element ref="ns:myElement"/> 
      

      The WSDL2Java command recognizes the ref attribute as a reference to another root element named myElement. The name of the element is obtained from the referenced element, such as myElement. The type of the element is the type of the referenced element. The WSDL2Java command generates a Java type based on the characteristics of the referenced type. The ref attribute is an optional feature of the JAX-RPC specification.

    • Use no attribute...

      For example

      <xsd:element name="three"/>  
      
      

      When you do not use an attribute, the WSDL2Java command recognizes a reference to the xsd:anyType as defined by the XML schema specification. The xsd:anyType is an optional type of the JAX-RPC specification.

    • Use an anonymous type:

      For example

      <xsd:element name="four">
              <xsd:complexType>
                  <xsd:sequence>
                      <xsd:element name="foo" type="xsd:string"/>
                  </xsd:sequence>
              </xsd:complexType>
          </ xsd:element>
       
      

      When you use an anonymous type, the WSDL2Java command recognizes a reference to the type defined within the element.

      Note that The complexType does not have a name. The WSDL2Java command generates a Java type based on the characteristics of this type. Since the anonymous type does not have a name, the WSDL2Java command uses the name of the container element, which can result in collisions with defined types and other anonymous types. The WSDL2Java command automatically detects and renames classes to avoid collisions. Support for anonymous types is not defined by the JAX-RPC specification, however using anonymous types is common.

      Note that An xsd:attribute is like an xsd:element; it contains a name and refers to a type. An xsd:attribute can refer to its type with the type attribute or using an anonymous type.

  • Element specific attributes

    Some attributes can be applied to xsd:elements and not to XML types.

    The maxOccurs attribute indicates the maximum number of occurrences of the element in the SOAP message. The default value is 1. If the value is greater than 1, or unbounded, the WSDL2Java command maps the construct to a Java array or bean indexed property. Metadata is also generated to properly serialize and deserialize a series of elements versus a normal XML array. The maxOccurs attribute is an optional feature of the JAX-RPC specification.

    The minOccurs attribute indicates the minimum number of occurrences of the element in the SOAP message. The default value is 1. The xsi:nillable attribute indicates whether the element can have a nil value. The minOccurs and xsi:nillable settings affect how a null value is serialized in a SOAP message. If minOccurs=0, the null value is not serialized. If xsi:nillable=

    true, the value is serialized with the xsi:nil=true attribute.

• Mapping of xsd:complexType to Java array

  The WSDL2Java command maps the following three kinds of XML formats to Java arrays

  XML...
  
  <xsd:element name="array1" type="soapenc:Array"/>
  
  Java:  
  
  Object[] array1;  
  

  XML: 
  
  <xsd:complexType name="arrayOfInt">
      <xsd:complexContent>
          <xsd:restriction base:"soapenc:Array">
              <xsd:attribute ref:"soapenc:arrayType" wsdl:arrayType="xsd:int[]"/>  
          </xsd:restriction> 
          </xsd:complexContext>
      </xsd:complexType>
  
   <xsd:element name="array2" type="ns:arrayOfInt"/>
  
  Java:  
  
    int[] array2; 
  

XML: 

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

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

Java:  

  int[] array3;

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>

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>

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

Literal Instance...

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