5 Understanding Data Binding

This chapter describes the data binding and the data types (both built-in and user-defined) that are supported for WebLogic Web services using Java API for XML-based RPC (JAX-RPC).

This chapter includes the following topics:

Overview of Data Binding
Supported Built-In Data Types
Supported User-Defined Data Types

Overview of Data Binding

With the emergence of XML as the standard for exchanging data across disparate systems, Web service applications need a way to access documents that are in XML format directly from the Java application. Specifically, the XML content needs to be converted to a format that is readable by the Java application. Data binding describes the conversion of data between its XML and Java representations.

As in previous releases, WebLogic Web services support a full set of built-in XML Schema, Java, and SOAP types, as specified by the JAX-RPC specification, described at http://java.net/projects/jax-rpc/, that you can use in your Web service operations without performing any additional programming steps. Built-in data types are those such as integer, string, and time.

Additionally, you can use a variety of user-defined XML and Java data types, including Apache XmlBeans (in package org.apache.xmlbeans), as input parameters and return values of your Web service. User-defined data types are those that you create from XML Schema or Java building blocks, such as <xsd:complexType> or JavaBeans. The WebLogic Web services Ant tasks, such as jwsc and clientgen, automatically generate the data binding artifacts needed to convert the user-defined data types between their XML and Java representations. The XML representation is used in the SOAP request and response messages, and the Java representation is used in the JWS that implements the Web service.

Note:

As of WebLogic Server 9.1, using XMLBeans 1.x data types (in other words, extensions of com.bea.xml.XmlObject) as parameters or return types of a WebLogic Web service is deprecated. New applications should use XMLBeans 2.x data types.

If a Web service uses XMLBeans that are compiled with the -noupa option, then -Dweblogic.wsee.bind.setCompileNoUpaRule=true flag is required to be set in the WebLogic server startup script to ensure the Web service deploys successfully.Otherwise, deployment will fail with the following error: cos-nonambig: Content model violates the unique particle attribution rule.

Supported Built-In Data Types

The following sections describe the built-in data types supported by WebLogic Web services and the mapping between their XML and Java representations. As long as the data types of the parameters and return values of the back-end components that implement your Web service are in the set of built-in data types, WebLogic Server automatically converts the data between XML and Java.

If, however, you use user-defined data types, then you must create the data binding artifacts that convert the data between XML and Java.WebLogic Server includes the jwsc and wsdlc Ant tasks that can automatically generate the data binding artifacts for most user-defined data types. See Supported User-Defined Data Types for a list of supported XML and Java data types.

XML-to-Java Mapping for Built-in Data Types

The following table lists the supported XML Schema data types (target namespace http://www.w3.org/2001/XMLSchema) and their corresponding Java data types.

For a list of the supported user-defined XML data types, see Java-to-XML Mapping for Built-In Data Types.

Table 5-1 Mapping XML Schema Built-in Data Types to Java Data Types

XML Schema Data Type	Equivalent Java Data Type (lower case indicates a primitive data type)
boolean	boolean
byte	byte
short	short
int	int
long	long
float	float
double	double
integer	java.math.BigInteger
decimal	java.math.BigDecimal
string	java.lang.String
dateTime	java.util.Calendar
base64Binary	byte[]
hexBinary	byte[]
duration	java.lang.String
time	java.util.Calendar
date	java.util.Calendar
gYearMonth	java.util.Calendar
gYear	java.util.Calendar
gMonthDay	java.util.Calendar
gDay	java.util.Calendar
gMonth	java.util.Calendar
anyURI	java.net.URI
NOTATION	java.lang.String
token	java.lang.String
normalizedString	java.lang.String
language	java.lang.String
Name	java.lang.String
NMTOKEN	java.lang.String
NCName	java.lang.String
NMTOKENS	java.lang.String[]
ID	java.lang.String
IDREF	java.lang.String
ENTITY	java.lang.String
IDREFS	java.lang.String[]
ENTITIES	java.lang.String[]
nonPositiveInteger	java.math.BigInteger
nonNegativeInteger	java.math.BigInteger
negativeInteger	java.math.BigInteger
unsignedLong	java.math.BigInteger
positiveInteger	java.math.BigInteger
unsignedInt	long
unsignedShort	int
unsignedByte	short
Qname	javax.xml.namespace.QName

Java-to-XML Mapping for Built-In Data Types

For a list of the supported user-defined Java data types, see Supported Java User-Defined Data Types.

Table 5-2 Mapping Java Data Types to XML Schema Data Types

Java Data Type (lower case indicates a primitive data type)	Equivalent XML Schema Data Type
int	int
short	short
long	long
float	float
double	double
byte	byte
boolean	boolean
char	string (with facet of length=1)
java.lang.Integer	int
java.lang.Short	short
java.lang.Long	long
java.lang.Float	float
java.lang.Double	double
java.lang.Byte	byte
java.lang.Boolean	boolean
java.lang.Character	string (with facet of length=1)
java.lang.String	string
java.math.BigInteger	integer
java.math.BigDecimal	decimal
java.util.Calendar	dateTime
java.util.Date	dateTime
byte[]	base64Binary
javax.xml.namespace.QName	Qname
java.net.URI	anyURI
javax.xml.datatype.XMLGregorianCalendar	anySimpleType
javax.xml.datatype.Duration	duration
java.lang.Object	anyType
java.awt.Image	base64Binary
javax.activation.DataHandler	base64Binary
javax.xml.transform.Source	base64Binary
java.util.UUID	string

Supported User-Defined Data Types

The tables in the following sections list the user-defined XML and Java data types for which the jwsc and wsdlc Ant tasks can automatically generate data binding artifacts, such as the corresponding Java or XML representation, the JAX-RPC type mapping file, and so on.

If your XML or Java data type is not listed in these tables, and it is not one of the built-in data types listed in Supported Built-In Data Types, then you must create the user-defined data type artifacts manually.

Supported XML User-Defined Data Types

The following table lists the XML Schema data types supported by the jwsc and wsdlc Ant tasks and their equivalent Java data type or mapping mechanism.

For details and examples of the data types, see the JAX-RPC specification at http://java.net/projects/jax-rpc/.

Table 5-3 Supported User-Defined XML Schema Data Types

XML Schema Data Type	Equivalent Java Data Type or Mapping Mechanism
`<xsd:complexType>` with elements of both simple and complex types.	JavaBean
`<xsd:complexType>` with simple content.	JavaBean
`<xsd:attribute>` in `<xsd:complexType>`	Property of a JavaBean
Derivation of new simple types by restriction of an existing simple type.	Equivalent Java data type of simple type.
Facets used with restriction element.	Facets not enforced during serialization and deserialization.
`<xsd:list>`	Array of the list data type.
Array derived from `soapenc:Array` by restriction using the `wsdl:arrayType` attribute.	Array of the Java equivalent of the `arrayType` data type.
Array derived from `soapenc:Array` by restriction.	Array of Java equivalent.
Derivation of a complex type from a simple type.	JavaBean with a property called `_value` whose type is mapped from the simple type according to the rules in this section.
`<xsd:anyType>`	java.lang.Object
<xsd:any>	`javax.xml.soap.SOAPElement` or `org.apache.xmlbeans.XmlObject`
<xsd:any[]>	`javax.xml.soap.SOAPElement[]` or `org.apache.xmlbeans.XmlObject[]`
<xsd:union>	Common parent type of union members.
`<xsi:nil>` and `<xsd:nillable>` attribute	Java `null` value. If the XML data type is built-in and usually maps to a Java primitive data type (such as `int` or `short`), then the XML data type is actually mapped to the equivalent object wrapper type (such as `java.lang.Integer` or `java.lang.Short`).
Derivation of complex types	Mapped using Java inheritance.
Abstract types	Abstract Java data type.

Supported Java User-Defined Data Types

The following table lists the Java user-defined data types supported by the jwsc and wsdlc Ant tasks and their equivalent XML Schema data type.

Table 5-4 Supported User-Defined Java Data Types

Java Data Type	Equivalent XML Schema Data Type
JavaBean whose properties are any supported data type.	`<xsd:complexType>` whose content model is a `<xsd:sequence>` of elements corresponding to JavaBean properties.
Array and multidimensional array of any supported data type (when used as a JavaBean property)	An element in a `<xsd:complexType>` with the `maxOccurs` attribute set to `unbounded`.
`java.lang.Object` Note: The data type of the run-time object must be a known type.	`<xsd:anyType>`
Apache XMLBeans (that are inherited from `org.apache.xmlbeans.XmlObject` only) Note: The Web service that uses an Apache XMLBeans data type as a return type or parameter must be defined as `document-literal-wrapped` or `document-literal-bare`.	See Apache XMLBeans at `http://xmlbeans.apache.org/index.html`.
`java.util.Collection`	Literal Array
`java.util.List`	Literal Array
`java.util.ArrayList`	Literal Array
`java.util.LinkedList`	Literal Array
`java.util.Vector`	Literal Array
`java.util.Stack`	Literal Array
`java.util.Set`	Literal Array
`java.util.TreeSet`	Literal Array
`java.utils.SortedSet`	Literal Array
`java.utils.HashSet`	Literal Array

Note:

The following user-defined Java data type, used as a parameter or return value of a WebLogic Web service in Version 8.1, is no longer supported: JAX-RPC-style enumeration class.

Additionally, generics are not supported when used as a parameter or return value. For example, the following Java method cannot be exposed as a public operation:

public ArrayList<String> echoGeneric(ArrayList<String> in) {
     return in;
 }