H Mapping Java Types to XML and WSDL Types

This appendix describes the ways in which Oracle Application Server Web Services can map between Java and XML types.

• How OracleAS Web Services Maps Java Types to XML Types

• How OracleAS Web Services Maps Java Primitive Types to XML Types

• How OracleAS Web Services Supports Java Value Types

• How OracleAS Web Services Supports Array Mapping

• How OracleAS Web Services Maps Java Collection Classes to XML Types

• How OracleAS Web Services Supports Java Beans Components

How OracleAS Web Services Maps Java Types to XML Types

Table H-1 describes the mapping between Java data types and XML data types that OracleAS Web Services can perform.

• The Java Type column lists the supported Java types recognized by OracleAS Web Services.

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

How to Use 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. 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.

See Also:

Chapter 1, "Ensuring Interoperable Web Services" for additional discussion on the use of Java null values.

How OracleAS Web Services Maps Java Primitive Types to XML Types

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

Table H-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

How OracleAS Web Services Supports 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 getter and setter 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.

How to Represent 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>

How OracleAS Web Services Supports Array Mapping

The following sections describe the ways in which OracleAS Web Services can map arrays.

• All Message Formats

• Document-Literal and RPC-Literal Formats

• RPC-Encoded Format

All Message 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 H-3 provides examples of how OracleAS Web Services can map 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 H-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 H-4 lists the XML type mapping for byte arrays.

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

See Also:

"How OracleAS Web Services Supports Java Value Types" for a description of 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 defines mappings for arrays that contain members of supported types. Table H-1 lists the supported types for RPC-encoded.

Note:

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

Example H-1 illustrates how WSDL represents a String[] array. 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 H-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 H-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 H-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>

How OracleAS Web Services Maps Java Collection Classes to XML Types

Table H-4 and Table H-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.

See Also:

"Definitions for Oracle Proprietary Collection Data Types" for more information on how these data types are defined.

Note that in OracleAS Web Services, you can nest Collections and Maps 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 H-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 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 H-5 provides more information on how the Oracle proprietary XML types for collections are defined.

Table H-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 H-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 H-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

Mapping J2SE 5.0 Collection and Map Data Types in Version 3.0 EJBs

In J2SE 5.0, the Collection and Map data types can be parameterized, for example List<User> and Map<Integer, Bean>. If you use a parameterized Collection or Map data type in a version 3.0 EJB Web services implementation, and then generate the WSDL for the service at deployment time, then these types will have a distinct representation in the WSDL.

Note:

The mappings of generic types described in this section is valid only for Web services assembled from version 3.0 EJBs, where the WSDL is generated at deployment time.

In the generated WSDL, a parameterized Collection type is represented as a repeated element sequence of the specific item type instead of xsd:anyType. For example, assume that you are assembling a Web service from a version 3.0 EJB that uses the following parameterized Collection type:

ListOfUsers java.util.List<mypackage.User>

Example H-3 illustrates the schema representation of the ListOfUsers type, assuming that the WSDL is generated at deployment time.

Example H-3 Schema Representation of a Parameterized Collection Data Type

...
<complexType name="ListOfUsers">
  <sequence>
    <element maxOccurs="unbounded" minOccurs="0" name="item"
    type="tns:User"/>
  </sequence>
</complexType>
...

Similarly, a parameterized Map type is represented as a repeated element sequence of a specific map entry type. For example, assume that you are assembling a Web service from a version 3.0 EJB that uses the following parameterized Map type:

MapOfIntToBean java.util.Map<java.lang.Integer, mypackage.Bean>

Example H-4 illustrates the schema representation of the MapOfIntToBean type, assuming that the WSDL is generated at deployment time.

Example H-4 Schema Representation of a Parameterized Map Data Type

...
<complexType name="MapOfIntToBean">
  <sequence>
    <element maxOccurs="unbounded" minOccurs="0" name="mapEntry"
    type="tns:MapEntryOfIntToBean"/>
  </sequence>
</complexType>
 
<complexType name="MapEntryOfIntToBean">
  <sequence>
    <element name="key" type="int"/>
    <element name="value" type="tns:Bean"/>
  </sequence>
</complexType>
...

How OracleAS Web Services Supports Java Beans Components

Java beans can have any number of properties. Each property must have a getter and setter method. The properties must belong to supported Java types.