Skip Headers
Oracle® Fusion Middleware Getting Started With JAX-WS Web Services for Oracle WebLogic Server
11g Release 1 (10.3.6)

Part Number E13758-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Using JAXB Data Binding

This chapter describes how to use Java Architecture for XML Binding (JAXB) data binding.

This chapter includes the following topics:

Overview of Data Binding Using JAXB

With the emergence of XML as the standard for exchanging data across disparate systems, Web service applications need a way to access data 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.

JAX-WS uses JAXB, described at http://jcp.org/en/jsr/detail?id=222, to manage all of the data binding tasks. Specifically, JAXB binds Java method signatures and WSDL messages and operations and allows you to customize the mapping while automatically handling the runtime conversion. This makes it easy for you to incorporate XML data and processing functions in applications based on Java technology without having to know much about XML.

The following figure shows the JAXB data binding process.

Figure 5-1 Data Binding With JAXB

Description of Figure 5-1 follows
Description of "Figure 5-1 Data Binding With JAXB"

As shown in the previous figure, the JAXB data binding process consists of the following tasks:

You can use the JAXB binding language to define custom binding declarations or specify JAXB annotations to control the conversion of data between XML and Java.

This following sections describe:

Developing the JAXB Data Binding Artifacts

The steps to develop the JAXB data binding artifacts using WebLogic Server depend on whether you are starting from a Java class file or a WSDL.

Please note, when invoking the jwsc, wsdlc, or clientgen Ant tasks described in these procedures:

For more information about the jwsc, wsdlc, or clientgen Ant tasks, see "Ant Task Reference" in WebLogic Web Services Reference for Oracle WebLogic Server.

Standard Data Type Mapping

WebLogic Web services support a full set of built-in XML Schema, Java, and SOAP types, as specified by the JAXB 2.0 (JSR 222) specification at http://jcp.org/en/jsr/detail?id=222, 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 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.

The following sections describe the built-in and user-defined data types that are supported by JAXB:

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.

When using 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 alphabetically 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 Java Data Type (lower case indicates a primitive data type)

anySimpleType (for xsd:element of this type)

java.lang.Object

anySimpleType (for xsd:attribute of this type)

java.lang.String

base64Binary

byte[]

boolean

boolean

byte

byte

date

java.xml.datatype.XMLGregorianCalendar

dateTime

javax.xml.datatype.XMLGregorianCalendar

decimal

java.math.BigDecimal

double

double

duration

javax.xml.datatype.Duration

float

float

g

java.xml.datatype.XMLGregorianCalendar

hexBinary

byte[]

int

int

integer

java.math.BigInteger

long

long

NOTATION

javax.xml.namespace.QName

QName

javax.xml.namespace.QName

short

short

string

java.lang.String

time

java.xml.datatype.XMLGregorianCalendar

unsignedByte

short

unsignedInt

long

unsignedShort

int


The following example, borrowed from the JAXB specification, shows an example of the default XML-to-Java binding.

XML Schema
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="purchaseOrder" type="PurchaseOrderType"/>
<xsd:element name="comment" type="xsd:string"/>
<xsd:complexType name="PurchaseOrderType">
     <xsd:sequence>
          <xsd:element name="shipTo" type="USAddress"/>
          <xsd:element name="billTo" type="USAddress"/>
          <xsd:element ref="comment" minOccurs="0"/>
          <xsd:element name="items" type="Items"/>
     </xsd:sequence>
     <xsd:attribute name="orderDate" type="xsd:date"/>
</xsd:complexType>
<xsd:complexType name="USAddress">
     <xsd:sequence>
          <xsd:element name="name" type="xsd:string"/>
          <xsd:element name="street" type="xsd:string"/>
          <xsd:element name="city" type="xsd:string"/>
          <xsd:element name="state" type="xsd:string"/>
          <xsd:element name="zip" type="xsd:decimal"/>
     </xsd:sequence>
<xsd:attribute name="country" type="xsd:NMTOKEN" fixed="US"/>
</xsd:complexType>
<xsd:complexType name="Items">
     <xsd:sequence>
          <xsd:element name="item" minOccurs="1" maxOccurs="unbounded">
               <xsd:complexType>
                    <xsd:sequence>
                         <xsd:element name="productName" type="xsd:string"/>
                         <xsd:element name="quantity">
                              <xsd:simpleType>
                                   <xsd:restriction base="xsd:positiveInteger">
                                        <xsd:maxExclusive value="100"/>
                                   </xsd:restriction>
                              </xsd:simpleType>
                         </xsd:element>
                         <xsd:element name="USPrice" type="xsd:decimal"/>
                         <xsd:element ref="comment" minOccurs="0"/>
                         <xsd:element name="shipDate" type="xsd:date"
                              minOccurs="0"/>
                    </xsd:sequence>
                    <xsd:attribute name="partNum" type="SKU" use="required"/>
               </xsd:complexType>
          </xsd:element>
     </xsd:sequence>
</xsd:complexType>
<!-- Stock Keeping Unit, a code for identifying products -->
<xsd:simpleType name="SKU">
     <xsd:restriction base="xsd:string">
          <xsd:pattern value="\d{3}-[A-Z]{2}"/>
     </xsd:restriction>
</xsd:simpleType>
</xsd:schema>
Default Java Binding
import javax.xml.datatype.XMLGregorianCalendar; import java.util.List;
public class PurchaseOrderType {
     USAddress getShipTo(){...} 
     void setShipTo(USAddress){...}
     USAddress getBillTo(){...} 
     void setBillTo(USAddress){...}
     /** Optional to set Comment property. */
     String getComment(){...} 
     void setComment(String){...}
     Items getItems(){...}
     void setItems(Items){...}
     XMLGregorianCalendar getOrderDate() 
     void setOrderDate(XMLGregorianCalendar)
};
public class USAddress {
     String getName(){...} 
     void setName(String){...}
     String getStreet(){...} 
     void setStreet(String){...}
     String getCity(){...} 
     void setCity(String){...}
     String getState(){...} 
     void setState(String){...}
     int getZip(){...} 
     void setZip(int){...}
     static final String COUNTRY="USA";
};
public class Items {
     public class ItemType {
          String getProductName(){...} 
          void setProductName(String){...}
          /** Type constraint on Quantity setter value 0..99.*/
          int getQuantity(){...} 
          void setQuantity(int){...}
          float getUSPrice(){...} 
          void setUSPrice(float){...}
          /** Optional to set Comment property. */
          String getComment(){...} 
          void setComment(String){...}
          XMLGregorianCalendar getShipDate();
          void setShipDate(XMLGregorianCalendar);
          /** Type constraint on PartNum setter value "\d{3}-[A-Z]{2}".*/
          String getPartNum(){...} void setPartNum(String){...}
     };
     /** Local structural constraint 1 or more instances of Items.ItemType.*/
     List<Items.ItemType> getItem(){...}
}
public class ObjectFactory {
     // type factories
     Object newInstance(Class javaInterface){...}
     PurchaseOrderType createPurchaseOrderType(){...}
     USAddress createUSAddress(){...}
     Items createItems(){...}
     Items.ItemType createItemsItemType(){...}
     // element factories
JAXBElement<PurchaseOrderType>createPurchaseOrder(PurchaseOrderType){...}
     JAXBElement<String> createComment(String value){...}
}

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

The following table lists alphabetically the supported Java data types and their equivalent XML Schema 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) XML Schema Data Type

boolean

boolean

byte

byte

double

double

float

float

long

long

int

int

javax.activation.DataHandler

base64Binary

java.awt.Image

base64Binary

java.lang.Object

anyType

java.lang.String

string

java.math.BigInteger

integer

java.math.BigDecimal

decimal

java.net.URI

string

java.util.Calendar

dateTime

java.util.Date

dateTime

java.util.UUID

string

javax.xml.datatype.XMLGregorianCalendar

anySimpleType

javax.xml.datatype.Duration

duration

javax.xml.namespace.QName

Qname

javax.xml.transform.Source

base64Binary

short

short


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.

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.

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>

java.lang.Object

<xsd:any[]>

java.lang.Object

<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 Java User-defined 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>

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


Customizing Java-to-XML Schema Mapping Using JAXB Annotations

If required, you can override the default binding rules for Java-to-XML Schema mapping using JAXB annotations. Table 5-5 summarizes the JAXB mapping annotations that you can include in your JWS file to control how the Java objects are mapped to XML. Each of these annotations are available with the javax.xml.bind.annotation package, described at http://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/package-summary.html.

Table 5-5 JAXB Mapping Annotations

Annotation

Description

@XmlAccessorType

Specifies whether fields or properties are mapped by default. See Specifying Default Serialization of Fields and Properties (@XmlAccessorType Annotation).

@XmlElement

Maps a property contained in a class to a local element in the XML Schema complex type to which the containing class is mapped. See Mapping Properties to Local Elements (@XmlElement).

@XMLMimeType

Associates the MIME type that controls the XML representation of the property with a textual representation, such as image/jpeg. See Specifying the MIME Type (@XmlMimeType Annotation).

@XmlRootElement

Maps a top-level class to a global element in the XML Schema that is used by the WSDL of the Web service. See Mapping a Top-level Class to a Global Element (@XmlRootElement).

@XmlSeeAlso

Binds other classes when binding the current class. See Binding a Set of Classes (@XmlSeeAlso).

@XmlType

Maps a class or enum type to an XML Schema type.See Mapping a Value Class to a Schema Type (@XmlType).


The default mapping of Java objects to XML Schema for the supported built-in and user-defined types are listed in the following sections:

Example of JAXB Annotations

The following provides an example of the JAXB annotations.

@XmlRootElement(name = "ComplexService", namespace ="http://examples.org")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "basicStruct", propOrder = {
    "intValue",
    "stringArray",
    "stringValue"
)
public class BasicStruct {
    protected int intValue;
    @XmlElement(nillable = true)
    protected List<String> stringArray;
    protected String stringValue;
    public int getIntValue() {
        return intValue;
    }
    public void setIntValue(int value) {
        this.intValue = value;
    }
    public List<String> getStringArray() {
        if (stringArray == null) {
            stringArray = new ArrayList<String>();
        }
        return this.stringArray;
    }

    public String getStringValue() {
        return stringValue;
    }
    public void setStringValue(String value) {
        this.stringValue = value;
    }
}

Specifying Default Serialization of Fields and Properties (@XmlAccessorType Annotation)

The @XmlAccessorType annotation specifies whether fields or properties are mapped by default. The annotation can be specified for the following Java program elements:

  • Package

  • Top-level class

The @XmlAccessorType can be specified with the @XmlType (see Mapping a Value Class to a Schema Type (@XmlType)) and @XmlRootElement (see Mapping a Top-level Class to a Global Element (@XmlRootElement)) annotations.

The following table lists the optional element that can be passed to the @XmlAccessorType annotation.

Table 5-6 Optional Element for @XMLAccessorType Annotation

Element Description

value

Specifies XMLAccessType.value, where value can be one of the following values:

  • FIELD—Fields are bound to XML.

  • PROPERTY—JavaBean properties (getter/setter pairs) are bound to XML.

  • PUBLIC_MEMBER—Public fields and JavaBean properties are bound to XML. This is the default.

  • NONE—Neither fields nor JavaBean properties are bound to XML.


For more information, see the javax.xml.bind.annotation.XmlAccessorType Javadoc at http://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/XmlAccessorType.html. An example is provided in Example of JAXB Annotations.

Mapping Properties to Local Elements (@XmlElement)

The @XmlElement annotation maps a property contained in a class to a local element in the XML Schema complex type to which the containing class is mapped. The annotation can be specified for the following Java program elements:

  • JavaBean property

  • Non-static, non-transient field

The following table lists the annotation elements that can be passed to the @XmlElement annotation.

Table 5-7 Optional Element Summary for @XMLElement Annotation

Element Description

name

Local name of the XML element that represents the property of a JavaBean. This element defaults to the JavaBean property name.

namespace

Namespace of the XML element that represents the property of a JavaBean. By default, the namespace is derived from the namespace of the containing class.

nillable

Customize the element declaration to be nillable.


For more information, see the javax.xml.bind.annotation.XmlElement Javadoc at http://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/XmlElement.html.

Specifying the MIME Type (@XmlMimeType Annotation)

The @XmlMimeType annotation specifies the MIME type that controls the XML representation of the property. The annotation can be specified for data types, such as Image or Source, that are bound to the xsd:base64Binary binary in XML.

The following table lists the required element that can be passed to the @XmlMimeType annotation.

Table 5-8 Required Element for @XMLMimeType Annotation

Element Description

value

Specifies the textual representation of the MIME type, such as image/jpeg, text/xml, and so on.


For more information, see the javax.xml.bind.annotation.XmlMimeType Javadoc at http://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/XmlMimeType.html.

Mapping a Top-level Class to a Global Element (@XmlRootElement)

The @XmlRootElement annotation maps a top-level class to a global element in the XML Schema that is used by the WSDL of the Web service. The annotation can be specified for the following Java program elements:

  • Top-level class

  • Enum type

The @XmlRootElement can be specified with the @XmlType (see Mapping a Value Class to a Schema Type (@XmlType)) and @XmlAccessorType (see Specifying Default Serialization of Fields and Properties (@XmlAccessorType Annotation)) annotations.

The following table lists the optional elements that can be passed to the @XmlRootElement annotation.

Table 5-9 Optional Elements for @XmlRootElement Annotation

Element Description

name

Local name of the XML element. This element defaults to the class name.

namespace

Namespace of the XML element. By default, the namespace is derived from the package of the class.


For more information, see the javax.xml.bind.annotation.XmlRootElement Javadoc at http://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/XmlRootElement.html. An example is provided in Example of JAXB Annotations.

Binding a Set of Classes (@XmlSeeAlso)

The @XmlSeeAlso annotation binds a list of classes when binding the current class. The following table lists the optional element that can be passed to the @XMLRootElement annotation.

Table 5-10 Optional Element for @XmlSeeAlso Annotation

Element Description

value

List of classes that JAXB uses when binding the current class.


Mapping a Value Class to a Schema Type (@XmlType)

The @XmlType annotation maps a class or enum type to an XML Schema type. The type can be a simple or complex type. The annotation can be specified for the following Java program elements:

  • Top-level class

  • Enum type

The @XmlType can be specified with the @XmlRootElement (see Mapping a Top-level Class to a Global Element (@XmlRootElement)) and @XmlAccessorType (see Specifying Default Serialization of Fields and Properties (@XmlAccessorType Annotation)) annotations.

The following table lists the optional elements that can be passed to the @XmlType annotation.

Table 5-11 Optional Elements for @XmlType Annotation

Element Description

name

Name of the XML Schema type to which the class is mapped.

namespace

Name of the target namespace of the XML Schema type. By default, the target namespace to which the package containing the class is mapped.

propOrder

List of JavaBean property names defined in a class. The list defines an order for the XML Schema elements when the class is mapped to an XML Schema complex type. Each name in the list is the name of a Java identifier of the JavaBean property. All of the JavaBean properties must be listed.


For more information, see the javax.xml.bind.annotation.XmlType Javadoc at http://download.oracle.com/javaee/5/api/javax/xml/bind/annotation/XmlType.html. An example is provided in Example of JAXB Annotations.

Customizing XML Schema-to-Java Mapping Using Binding Declarations

Due to the distributed nature of a WSDL, you cannot always control or change its contents to meet the requirements of your application. For example, the WSDL may not be owned by you or it may already be in use by your partners, making changes impractical or impossible.

If directly editing the WSDL is not an option, you can customize how the WSDL components are mapped to Java objects by specifying custom binding declarations. You can use binding declarations to control specific features, as well, such as asynchrony, wrapper style, and so on, and to control the JAXB data binding artifacts that are produced by customizing the XML Schema.

You can define binding declarations in one of the following ways:

The binding declarations are semantically equivalent regardless of which method you choose.

Custom binding declarations are associated with a scope, as shown in the following figure.

Figure 5-2 Scopes for Custom Binding Declarations

Description of Figure 5-2 follows
Description of "Figure 5-2 Scopes for Custom Binding Declarations"

The following table describes the meaning of each scope.

Table 5-12 Scope for Custom Binding Declarations

Scope Definition

Global scope

Describes customization values with global scope. Specifically:

  • For JAX-WS binding declarations, describes customization values that are defined as part of the root element, as described in Specifying the Root Element.

  • For JAXB annotations, describes customization values that are contained within the <globalBindings> binding declaration. Global scope values apply to all of the schema elements in the source schema as well as any schemas that are included or imported.

Schema scope

Describes JAXB customization values that are contained within the <schemaBindings> binding declaration. Schema scope values apply to the elements in the target namespace of a schema.

Note: This scope applies for JAXB binding declarations only.

Definition scope

Describes JAXB customization values that are defined in binding declarations of a type definition or global declaration. Definition scope values apply to elements that reference the type definition or global declaration.

Note: This scope applies for JAXB binding declarations only.

Component scope

Describes customization values that apply to the WSDL or schema element that was annotated.


Scopes for custom binding declarations adhere to the following inheritance and overriding rules:

The following sections describe how to create custom binding declarations and describe the standard custom binding declarations:

For more information about using custom binding declarations, see:

Creating an External Binding Declarations File

Create an external binding declarations file that contains all binding declarations for a specific WSDL or XML Schema document. Then, pass the binding declarations file to the <binding> child element of the wsdlc, jwsc, or clientgen Ant task.

The following sections describe:

Creating an External Binding Declarations File Using JAX-WS Binding Declarations

The following sections describe how to specify the root and child elements of the JAX-WS binding declarations file. For information about the custom binding declarations that you can define, see JAX-WS Custom Binding Declarations.

Specifying the Root Element

The jaxws:bindings declaration is the root of all other binding declarations and defines the location of the WSDL file and the namespace to which the XML Schema conforms: http://java.sun.com/xml/ns/jaxws.

The format of the root declaration is as follows:

<jaxws:bindings
    wsdlLocation="uri_of_wsdl"
    jaxws:xmlns="http://java.sun.com/xml/ns/jaxws">

uri_of_wsdl specifies the URI of the WSDL file.

The package, wrapper style, and asynchronous mapping customizations, defined in Table 5-5, can be globally defined as part of the root binding declaration in the external customization file. Global bindings apply to the entire scope of the wsdl:definition in the WSDL referenced by the wsdlLocation attribute.

The following provides an example of the root binding element that defines the package name, wrapper style, and asynchronous mapping customizations.

<jaxws:bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL"
  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
    <package name="example.webservices.simple.simpleservice">
    <enableWrapperStyle>true</enableWrapperStyle>
    <enableAsyncMapping>false</enableAsyncMapping>
</jaxws:bindings>
Specifying Child Elements

The root jaxws:bindings element can contain child elements. You specify the WSDL node that is being customized by passing an XPath expression in the node attribute.

An XML Schema inlined inside a compiled WSDL file can be customized by using standard JAXB bindings. For more information, see "XML Schema Customization" in JAX-WS WSDL Customizations at http://jax-ws.java.net/nonav/2.1.2/docs/customizations.html. For information about the custom JAXB binding declarations that you can define, see JAXB Custom Binding Declarations.

For example, the following example defines the package name as examples.webservices.complex.complexservice for the wsdl:definitions node of the WSDL document.

<jaxws:bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL
  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
  <jaxws:bindings node="wsdl:definitions" 
            xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <jaxws:package name="examples.webservices.simple.simpleservice"/>
</bindings>

Creating an External Binding Declarations File Using JAXB Binding Declarations

The JAXB binding declarations file is an XML document that conforms to the XML Schema for the following namespace: http://java.sun.com/xml/ns/jaxb. The following sections describe how to specify the root and child elements of the JAXB binding declarations file. For information about the custom binding declarations that you can define, see JAXB Custom Binding Declarations.

Specifying the Root Element

The jaxb:bindings declaration is the root of all other binding declarations.The format of the root declaration is as follows:

<jaxb:bindings
    schemaLocation="uri_of_schema">

uri_of_schema specifies the URI of the XML Schema file.

Specifying Child Elements

The root jaxb:bindings element can contain child elements. You specify the schema node that is being customized by passing an XPath expression in the node attribute.

For example, the following example defines the package name as examples.webservices.simple.simpleservice.

<jaxb:bindings
   schemaLocation="simpleservice.xsd">
   <jaxb:bindings node="//xs:simpleType[@name='value1']">
       <jaxb:package name="examples.webservices.simple.simpleservice"/>
   </jaxb:bindings>
</jaxb:bindings>

Embedding Binding Declarations

You can embed binding declarations in a WSDL file using one of the following methods:

Embedding JAX-WS or JAXB Binding Declarations in the WSDL File

You can embed a binding declaration in the WSDL file using the jaxws:bindings element as a WSDL extension. For information about the custom binding declarations that you can define, see JAX-WS Custom Binding Declarations.

For example, the following example defines the class name as SimpleService for the SimpleServiceImpl service endpoint interface (or port).

<wsdl:portType name="SimpleServiceImpl">
     <jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
            <jaxws:class name="SimpleService"/>
     </jaxws:bindings>
</wsdl:portType>

If this binding declaration had not been specified, the class name of the service endpoint interface would be set to the wsdl:portType name—SimpleServiceImpl—by default.

An XML Schema inlined inside a compiled WSDL file can be customized by using standard JAXB bindings. For more information, see "XML Schema Customizations" in JAX-WS WSDL Customizations, which is available at http://jax-ws.java.net/nonav/2.1.2/docs/customizations.html. For information about the custom JAXB binding declarations that you can define, see JAXB Custom Binding Declarations.

Embedding JAXB Binding Declarations in the XML Schema

You can embed a JAXB custom declaration within the <appinfo> element of the XML Schema, as illustrated below.

<xs:annotation>
    <xs:appinfo>
        <binding declaration>
    </xs:appinfo>
</xs:annotation>

For example, the following defines the package name for the schema:

<schema xmlns="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.w3.org/2001/XMLSchema"
    xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
    jaxb:version="2.0">
    <annotation>
        <appinfo>
           <jaxb:schemaBindings>
            <jaxb:package name="example.webservices.simple.simpleservice"/>
           </jaxb:schemaBindings>
        </appinfo>
    </annotation>
</schema>

JAX-WS Custom Binding Declarations

The following table summarizes the typical JAX-WS customizations. For a complete list of JAX-WS custom binding declarations, see JAX-WS WSDL Customization at http://jax-ws.java.net/nonav/2.1.2/docs/customizations.html.

Table 5-13 JAX-WS Custom Binding Declarations

Customization Description

Package name

Use the jaxws:package binding declaration to define the package name.

If you do not specify this customization, the wsdlc Ant task generates a package name based on the targetNamespace of the WSDL. This data binding customization is overridden by the packageName attribute of the wsdlc, jwsc, or clientgen Ant task. For more information, see "wsdlc" in the WebLogic Web Services Reference for Oracle WebLogic Server.

This binding declaration can be specified as part of the root binding element, as described in Creating an External Binding Declarations File, or on the wsdl:definitions node, as shown in the following example:

<bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  wsdlLocation=
  "http://localhost:7001/simple/SimpleService?WSDL"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="wsdl:definitions" 
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <package name="example.webservices.simple.simpleService"/>
</bindings>

Wrapper-style rules

Use the jaxws:enablesWrapperStyle binding declaration to enable or disable the wrapper style rules that control how the parameter types and return types of a WSDL operation are generated.

This binding declaration can be specified as part of the root binding element, as described in Creating an External Binding Declarations File, or on one of the following nodes:

  • wsdl:definitions—Applies to all wsdl:operations of all wsdl:portType attributes.

  • wsdl:portType—Applies to all wsdl:operations in the wsdl:portType.

  • wsdl:operation—Applies to the wsdl:operation only.

The following example disables the wrapper style rules for the wsdl:definitions node:

<bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="wsdl:definitions" 
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <enableWrapperStyle>
       false
    </enableWrapperStyle>
</bindings>

Asynchrony

Use the jaxws:enableAsycMapping binding declaration to instruct the clientgen Ant task to generate asynchronous polling and callback operations along with the normal synchronous methods when it compiles a WSDL file.

This binding declaration can be specified as part of the root binding element, as described in Creating an External Binding Declarations File, or on one of the following nodes:

  • wsdl:definitions—Applies to all wsdl:operations of all wsdl:portType attributes.

  • wsdl:portType—Applies to all wsdl:operations in the wsdl:portType.

  • wsdl:operation—Applies to the wsdl:operation only.

The following example disables asynchronous polling and callback operations:

<bindings
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
wsdlLocation="http://localhost:7001/simple/SimpleService?WSDL"
  xmlns="http://java.sun.com/xml/ns/jaxws">
  <bindings node="wsdl:definitions" 
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <enableAsyncMapping>
       false
    </enableAsyncMapping>
</bindings>

Provider

Use the jaxws:provider binding declaration to mark the part as a provider interface. This binding declaration can be specified as part of the wsdl:portType. This binding declaration applies when you are developing a service starting from a WSDL file.

Class name

Use the jaxws:class binding declaration to define the class name. This binding declaration can be specified for one of the following nodes:

  • wsdl:portType—Defines the interface class name.

  • wsdl:fault—Defines fault class names.

  • soap:headerfault—Defines exception class names.

  • wsdl:service—Defines the implementation class names.

The following example defines the class name for the implementation class.

<bindings node="wsdl:definitions/wsdl:service[@name='SimpleService']">
    <class name="myService"></class> 
</bindings>

Method name

Use the jaxws:method binding declaration to customize the generated Java method name of a service endpoint interface or the port accessor method in the generated Service class.

The following example defines the Java method name for the wsdl:operation EchoHello.

<bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
    <method name="Greeting"></method> 
</bindings>

Java parameter name

Use the jaxws:parameter binding declaration to customize the parameter name of generated Java methods. This declaration can be used to change the method parameter of a wsdl:operation in a wsdl:portType.

The following example defines the Java method name for the wsdl:operation echoHello.

<bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
    <parameter part="definitions/message[@name='EchoHello']/
    part[@name='parameters']" element="hello"
    name="greeting"/> 
</bindings>

Javadoc

Use the jaxws:javadoc binding declaration to specify Javadoc text for a package, class, or method.

For example, the following defines Javadoc at the method level.

<bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
    <method name="Hello">
       <javadoc>Prints hello.</javadoc>
    </method> 
</bindings>

Handler chain

Use the javaee:handlerchain binding declaration to customize or add handlers. The inline handler must conform to the handler chain configuration defined in the Web Services Metadata for the Java Platform specification (JSR-181) at http://www.jcp.org/en/jsr/detail?id=181.


JAXB Custom Binding Declarations

The following table lists the typical JAXB customizations.

Note:

The following table only summarizes the JAXB custom binding declarations, to help get you started. For a complete list and description of all JAXB custom binding declarations, see the JAXB specification (http://jcp.org/en/jsr/detail?id=222) or "Customizing JAXB Bindings" in the Java EE 5 Tutorial.

Table 5-14 JAXB Custom Binding Declarations

Customization Description

Global bindings

Use the <globalBindings> binding declaration to define binding declarations with global scope (see Figure 5-2).

You can specify attributes and elements to the <globalBindings> binding declaration. For example, the following binding declaration defines:

  • collectionType attribute that specifies a type class, myArray, that implements the java.util.List interface and that is used to represent all lists in the generated implementation.

  • generateIsSetMethod attribute to generate the isSet() method corresponding to the getter and setter property methods.

  • javaType element to customize the binding of an XML Schema atomic datatype to a Java datatype (built-in or application-specific).

<jaxb:globalBindings
    collectionType ="java.util.myArray"
    generateIsSetMethod="false">
    <jaxb:javaType name="java.util.Date"
        xmlType="xsd:date"
    </jaxb:javaType>
</jaxb:globalBindings>

Schema bindings

Use the <schemaBindings> binding declaration to define binding declarations with schema scope (see Figure 5-2).

For an example, see the description of "Package name" in this table.

Package name

Use the <package> element of the <schemaBindings> binding declaration (see Table 5-12) to define the package name for the schema.

If you do not specify this customization, the wsdlc Ant task generates a package name based on the targetNamespace of the WSDL. This data binding customization is overridden by the packageName attribute of the wsdlc, jwsc, or clientgen Ant task. For more information, see "wsdlc" in the WebLogic Web Services Reference for Oracle WebLogic Server.

For example, the following defines the package name for all JAXB classes generated from the simpleservice.xsd file:

<jaxb:bindings
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   schemaLocation="simpleservice.xsd"
   node="/xs:schema">
   <jaxb:schemaBindings>
      <jaxb:package name="examples.jaxb"/>
   </jaxb:schemaBindings>
</jaxb:bindings>

The following shows how to define the package name for an imported XML Schema:

<jaxb:bindindgs
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    node="//xs:schema/xs:import[@namespace='http://examples.webservices.org/complexservice']">
    <jaxb:schemaBindings>
        <jaxb:package name="examples.jaxb"/>
        </jaxb:schemaBindings>
    </jaxb:bindings>

Class name

Use the <class> binding declaration to define the class name for a schema element.

The following example defines the class name for an xsd:complexType:

<xs:complexType name="ComplexType">
    <xs:annotation><xs:appinfo>
           <jaxb:javadoc>This is my class.</jaxb:javadoc>
       </jaxb:class>
    </xs:appinfo></xs:annotation>
</xs:complexType>

Java property name

Use the <property> binding declaration to define the property name for a schema element.

The following example shows how to define the Java property name:

<jaxb:bindindgs
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    node="//xs:schema/">
    <jaxb:schemaBindings>
        <jaxb:property generateIsSetMethod="true"/> 
    </jaxb:schemaBindings>
</jaxb:bindings>

Java datatype

Use the <javaType> binding declaration to customize the binding of an XML Schema atomic datatype to a Java datatype (built-in or application-specific).

For example, see Global bindings (above).

Javadoc

Use the <javadoc> child element of the <class> or <property> binding declaration to specify Javadoc for the element.

For example:

<xs:complexType name="ComplexType">
    <xs:annotation><xs:appinfo>
<jaxb:class name="MyClass"> 
           <jaxb:javadoc>This is my class.</jaxb:javadoc>
       </jaxb:class>
    </xs:appinfo></xs:annotation>
</xs:complexType>