D Mapping Java Types to XML and WSDL Types

Using Java Null Values in Bottom Up Mapping

It is good practice not to rely on any mapping from Java null values to XML nil values (see also Chapter 1, "Ensuring Interoperable Web Services"). Special care needs to be taken in the RPC case.

• In RPC-literal message format, Null parameter values cannot be mapped to nil values.

• In RPC-encoded message format, SOAP-encoded type values can preserve nil.

• In all cases where a value type (Java Bean) is used as a parameter, you should not use Java null values.

Representing a Java Value Type as a Schema Type

A Java value type can be represented by a schema type. The schema type that corresponds to a Java value type has the following general format.

<complexType name="classname of the value type">
  <sequence>
     ...attributes...
  </sequence>
</complexType>

All Formats

Byte arrays are a special case. The Java type byte[] maps to the XML type xsd:base64Binary for document-literal, RPC-literal, and RPC-encoded formats.

Document-Literal and RPC-Literal Formats

Table D-3 provides examples of how OracleAS Web Services supports arrays with members of supported types in the RPC-literal and document-literal formats. For example, an array containing elements of type int maps to the XML type xsd:int with the minOccurs and maxOccurs attributes. Table D-1 lists the supported type mappings for RPC-literal and document-literal formats.

Multi-dimensional arrays, such as Double[][], are not supported for the document-literal or RPC-literal formats in the current release. However, it is possible to work around this limitation by wrapping the array in a Java value type and then using an array of these value types. "OC4J Support for Java Value Types" describes the requirements on Java value types. Note the restriction on the names for value types described in this section.

RPC-Encoded Format

For the RPC-encoded format, JAX-RPC supports arrays that contain members of supported types. Table D-1 lists the supported types for RPC-encoded.

Example D-1 illustrates how a String[] array is represented in the WSDL. The String[] array is the target of the WSDL construct wsdl:arrayType, where wsdl is the namespace for the WSDL 1.1 schema prefix. This namespace has the following definition.

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

<complexType name="ArrayOfString">
  <complexContent>
    <restriction base="soap-enc:Array">
      <attribute ref="soap-enc:arrayType" wsdl:arrayType="string[]"/>
    </restriction>
  </complexContent>
</complexType>

Example D-2 illustrates the definition of a multidimensional array. The array of strings (ArrayofString[]) defined in the previous example is used in the wsdl:arrayType="tns:ArrayofString[]" attribute (highlighted in bold) to create an array which contains arrays of strings. The tns is a WSDL construct that defines a local namespace.

<complexType name="ArrayOfArrayOfString">
  <complexContent>
    <restriction base="soap-enc:Array">
      <attribute ref="soap-enc:arrayType" wsdl:arrayType="tns:ArrayOfString[]"/>
    </restriction>
  </complexContent>
</complexType>

Limitations on Using Collection and Map Data Types

This section describes the limitations on using Collection and Map data types in OracleAS Web Services.

• Instances of java.lang.Object cannot be used in Collections or Maps because there is no XML schema construct to describe the instances of java.lang.Object.

• If you use instances of non-built in types (such as Beans) in a Collection, then you must generate schemas for them. See "Oracle-Specific Type Support" in the Oracle Application Server Web Services Developer's Guide for more information on this topic.

• In J2SE 5.0, Collections and Maps can be parameterized. For example, Collection<Integer>. However, the code generated by WebServicesAssembler does not support parameterized Collection and Map, because OracleAS Web Services does not preserve parameterized type metadata in the generated schema.

The following limitations apply to Collection and Map data types when you are working with document-literal and RPC-literal message formats.

• Object graph structure is NOT preserved between serialization and deserialization. See "Object Graph" for more information on limitations when working with object graphs.

• Recursive or circular reference structures return an error. This is illustrated in the following code samples.

  // the following lines of code will return an error
  ArrayList a = new ArrayList();
  a.add(a);
  
  

  The following code sample illustrates how Object is not supported as a Collection element.

  // the following lines of code will return an error
  ArrayList a = new ArrayList();
  a.add(new Object());  
  

Definitions for Oracle-Proprietary Collection Data Types

Table D-5 provides more information on how the Oracle-proprietary XML types for collections are defined.

<complexType name="collection">
  <sequence>
    <element name="item" type="anyType" minOccurs="0" maxOccurs="unbounded"/>
  </sequence>
</complexType>

<complexType name="map">
  <sequence>
    <element name="mapEntry" type="owi:mapEntry" 
             minOccurs="0" maxOccurs="unbounded"/>
  </sequence>
</complexType>

<complexType name="mapEntry">
  <sequence>
    <element name="key" type="anyType"/>
    <element name="value" type="anyType"/>
  </sequence>
</complexType>