Skip Headers

Oracle® Application Server Advanced Web Services Developer's Guide 10g Release 3 (10.1.3) B25603-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# D Mapping Java Types to XML and WSDL Types

This appendix describes the mappings between Java types and XML types that are supported under Oracle Application Server Web Services.

- Mapping Java Types to XML Types

- Mapping Java Primitive Types to XML Types

- OC4J Support for Java Value Types

- Mapping Support for Arrays

- Mapping Java Collection Classes to XML Types

- Support for Java Beans Components

## Mapping Java Types to XML Types

Table D-1 describes the mapping between Java data types and XMl data types that OracleAS Web Services supports.

- The Java Type column lists the supported Java types.

- The XML Type: RPC-Literal, Document-Literal column lists the mapping between the Java type and the corresponding XML type for RPC-literal and document-literal format.

- The XML Type: RPC-Encoded column lists the mapping between the Java type and the corresponding RPC-encoded format.

For example, `java.lang.String` is mapped to the `xsd:string` XML data type. You should note that not every Java type can be used as a method parameter or return type.

The namespace for the document-literal and RCP-literal formats uses an `xsd` prefix and has the following definition.

`xmlns:xsd="http://www.w3.org/2001/XMLSchema"`

The SOAP 1.1 namespace for the RPC-encoded format uses a `soap-enc` prefix and has the following definition.

`xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding`

Table D-1 Mapping Java Types to XML Types

Java Types | XML Type: RPC-Literal, Document-Literal | XML Type: RPC-Encoded
--- | --- | ---
java.lang.Boolean | xsd:boolean | soap-enc:boolean
java.lang.Byte | xsd:byte | soap-enc:byte
java.lang.Double | xsd:double | soap-enc:double
java.lang.Float | xsd:float | soap-enc:float
java.lang.Integer | xsd:integer | soap-enc:integer
java.lang.Long | xsd:long | soap-enc:long
java.lang.Short | xsd:short | soap-enc:short
java.lang.String | xsd:string | xsd:string
java.math.BigDecimal | xsd:decimal | xsd:decimal
java.math.BigInteger | xsd:int | xsd:int
java.net.URI | xsd:anyURI | xsd:anyURI
java.util.Calendar | xsd:dateTime | xsd:dateTime
java.util.Date | xsd:dateTime | xsd:dateTime
java.xml.QName | xsd:QName | xsd:QName

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

## Mapping Java Primitive Types to XML Types

Table D-2 describes the mapping between Java primitive types and XML types that OracleAS Web Services supports. The types listed in the XML Type column applies to RPC-encoded, RPC-literal, and document-literal formats.

Table D-2 Mapping Java Primitive Types to XML Types

Java Primitive Type | XML Type
--- | ---
boolean | xsd:boolean
byte | xsd:byte
double | xsd:double
float | xsd:float
int | xsd:int
long | xsd:long
short | xsd:short

## OC4J Support for Java Value Types

Java value types can contain a number of attributes. The following list describes the requirements on the Java class corresponding to the Java value type.

- the Java class must have an empty public constructor

- the Java class must not implement `java.rmi.Remote`

- the Java class must contain attributes of supported types

  - an attribute can be a public field that is not `final` or `transient`, or

  - an attribute can be represented by public `get`ter and `set`ter methods

- If the Java class contains a single array-valued attribute (such as `int[]` or `String[]`) then the name of the class must not contain the word "Array". You might want to rename the class to "Ary", "List", or something similar.

### 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>

## Mapping Support for Arrays

The following sections describe the mapping support OracleAS Web Services offers for arrays.

- All Formats

- Document-Literal and RPC-Literal Formats

- RPC-Encoded Format

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

Note: Byte arrays are an exception to the list of supported types. Table D-4 lists the XML type mapping for byte arrays.

Table D-3 Mapping Arrays Containing Java Types to XML Types for Document-Literal and RPC-Literal

Java Type | XML Type: RPC-Literal, Document-Literal | Additional Properties for the XML Type
--- | --- | ---
int[] | xsd:int | minOccurs="0", maxOccurs="unbounded"
String[] | xsd:string | minOccurs="0", maxOccurs="unbounded"

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.

Note: Byte arrays are an exception to the list of supported types. Table D-4 lists the XML type mapping for byte arrays.

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/"`

Example D-1 WSDL Definition of an Array of Strings for the RPC-Encoded Format

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

Example D-2 WSDL Definition of a Multi-Dimensional Array of an Array of Strings

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

## Mapping Java Collection Classes to XML Types

Table D-4 and Table D-5 describe the mapping between Java `Collection` and `Map` data types and the XML types that OracleAS Web Services supports. This is an Oracle-proprietary mapping and may not be compatible with data type support provided by other vendors. "Definitions for Oracle-Proprietary Collection Data Types" provides more information on how these types are defined.

Note that in OracleAS Web Services, you can nest `Collection`s and `Map`s data types. For example, you can specify a `Collection` as an item within a `Collection`.

The Java `Collection` and `Map` data types are supported in RPC-literal, document-literal, and RPC-encoded formats. These data types map to the same XML types for the three formats. The Oracle-proprietary collection types use the following proprietary namespace for RPC-literal and document-literal formats.

`xmlns:owi="http://www.oracle.com/webservices/internal/literal"`

The Oracle-proprietary collection types use the following proprietary namespace for the RPC-encoded format.

`xmlns:owi="http://www.oracle.com/webservices/internal"`

Table D-4 Mapping Java Collection Classes to XML Types

Java Type | Java Class (java.util) | XML Type
--- | --- | ---
Collection classes: | Collection | owi:collection
| List | owi:list
| ArrayList | owi:arrayList
| LinkedList | owi:linkedList
| Stack | owi:stack
| Vector | owi:vector
Set classes: | Set | owi:set
| HashSet | owi:hashSet
| TreeSet | owi:treeSet
Map classes: | Map | owi:map
| HashMap | owi:hashmap
| Hashtable | owi:hashtable
| Properties | owi:properties
| TreeMap | owi:treemap

### 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 `Collection`s or `Map`s 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, `Collection`s and `Map`s 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.

Table D-5 Additional Information about Oracle-Proprietary XML Types

Proprietary XML Type | Additional Information about the XML Type
--- | ---
owi:collection | The following is the XML schema type of the `owi:collection` type for the RPC-literal and document-literal formats. To construct the type definition for the RPC-encoded format, replace `type="anyType"` with an array of type `xsd:anyType`. Example D-1 provides an example of creating an array of a data type.
    <complexType name="collection">
      <sequence>
        <element name="item" type="anyType" minOccurs="0" maxOccurs="unbounded"/>
      </sequence>
    </complexType>
owi:list | a simple extension of `owi:collection`
owi:arrayList | a simple extension of `owi:list`
owi:linkedList | a simple extension of `owi:list`
owi:stack | a simple extension of `owi:list`
owi:vector | a simple extension of `owi:list`
owi:set | a simple extension of `owi:collection`
owi:hashSet | a simple extension of `owi:set`
owi:treeSet | a simple extension of `owi:set`
owi:map | The following is the XML schema type of the `owi:map` type for the RPC-literal and document-literal formats. To construct the type definition for the RPC-encoded format, replace `type="owi:mapEntry`" with an array of `owi:mapEntry`. Example D-1 provides an example of creating an array of a data type.
    <complexType name="map">
      <sequence>
        <element name="mapEntry" type="owi:mapEntry"
                 minOccurs="0" maxOccurs="unbounded"/>
      </sequence>
    </complexType>
The `owi:mapEntry` type used in the preceding code sample has the following definition.
    <complexType name="mapEntry">
      <sequence>
        <element name="key" type="anyType"/>
        <element name="value" type="anyType"/>
      </sequence>
    </complexType>
owi:hashMap | a simple extension of `owi:map`
owi:hashtable | a simple extension of `owi:map`
owi:properties | a simple extension of `owi:map`
owi:treeMap | a simple extension of `owi:map`

## Support for Java Beans Components

Java beans can have any number of properties. Each property must have a `get`ter and `set`ter method. The properties must belong to supported Java types.