5 Understanding Data Binding

The following sections provide information about data binding and the data types (both built-in and user-defined) that are supported:

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 https://jax-rpc.dev.java.net, 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 https://jax-rpc.dev.java.net.

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 runtime 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;
 }