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:

  • Bind—Binds XML Schema to schema-derived JAXB Java classes, or value classes. Each class provides access to the content via a set of JavaBean-style access methods (that is, get and set). Binding is managed by the JAXB schema compiler.

  • Unmarshal—Converts the XML document to create a tree of Java program elements, or objects, that represent the content and organization of the document that can be accessed by your Java code. In the content tree, complex types are mapped to value classes. Attribute declarations or elements with simple types are mapped to properties or fields within the value class and you can access the values for them using get and set methods. Unmarshalling is managed by the JAXB binding framework.

  • Marshal—Converts the Java objects back to XML content. In this case, the Java methods that are deployed as WSDL operations determine the schema components in the wsdl:types section. Marshalling is managed by the JAXB binding framework.

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.

WebLogic Server provides two data binding and JAXB providers:

  • EclipseLink MOXy, the default in this release of WebLogic Server, is a fully compliant JAXB implementation. In addition to offering the standard JAXB features, EclipseLink MOXy provides useful extensions, such as the ability to use an external metadata file to configure the equivalent of JAXB annotations without modifying the Java source it refers to, and XPath based mapping. The JAXB enhancements can be used in the annotations on a service endpoint interface (SEI) or one of the value types used by the SEI. Users of JAXB in standalone mode can also take advantage of these features.

    Some of the additional extensions offered by EclipseLink MOXy include:

    • Extensions for mapping JPA entities to XML

    • Bidirectional mapping

    • Virtual properties

    • Ability to bootstrap from metadata and generate in-memory domain classes (Dynamic MOXy)

    For a web service, the EclipseLink MOXy extensions can be leveraged on the server side only, and only in the Java to WSDL scenario, in which the SEI and value types can use the extended EclipseLink functionality. For more information about these extensions and EclipseLink MOXy, see The EclipseLink MOXy (JAXB) User's Guide at http://wiki.eclipse.org/EclipseLink/UserGuide/MOXy.

    No configuration is required to use the EclipseLink MOXy providers.

  • Glassfish RI JAXB, which is the default Glassfish JAXB implementation, and was the default JAXB offering in WebLogic Server in previous releases. The Glassfish RI JAXB proprietary features will not work with EclipseLink MOXy. If desired, you can enable the Glassfish RI JAXB data binding and JAXB providers at the server or application level. For more information, see Using the Glassfish RI JAXB Data Binding and JAXB Providers.

The following sections describe how to use JAXB data binding with WebLogic Server and how to configure the Glassfish RI JAXB providers if desired:

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:

  • You must specify the type="JAXWS" attribute to generate a JAX-WS web service and JAXB binding artifacts. For jwsc, you specify the type attribute as part of the <jws> child element.

  • You can optionally specify the <binding> child element to specify a customizations file that contains JAX-WS and JAXB data binding customizations. For information about creating a customizations file, see Customizing XML Schema-to-Java Mapping Using Binding Declarations. If no customizations are required, JAXB uses the standard built-in and user-defined data type mappings described in Standard Data Type Mapping.

Standard Data Type Mapping

WebLogic web services support a full set of built-in XML Schema, Java, and SOAP types, as specified by the JSR 222: JavaTM Architecture for XML Binding (JAXB) 2.0 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://docs.oracle.com/javase/8/docs/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 and annotated fields are bound to XML.

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

  • NONE—Only annotated fields and properties are bound to XML.

For more information, see the javax.xml.bind.annotation.XmlAccessorType Javadoc at http://docs.oracle.com/javase/8/docs/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://docs.oracle.com/javase/8/docs/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://docs.oracle.com/javase/8/docs/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://docs.oracle.com/javase/8/docs/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://docs.oracle.com/javase/8/docs/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:

  • Create an external binding declarations file that contains all binding declarations for a specific WSDL or XML Schema document. See Creating an External Binding Declarations File.

    Note:

    If customizations are required, Oracle recommends this method to maintain flexibility by keeping the customizations separate from the WSDL or XML Schema document.

  • Embed binding declarations within the WSDL or XML Schema document. See Embedding Binding Declarations.

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:

  • Inheritance—Customization values are inherited from the top down. For example, a WSDL element (JAX-WS) in a component scope inherits a customization value defined in global scope. A schema element (JAXB) in a component scope inherits a customization value defined in global, schema, and definition scopes.

  • Overriding—Customization values are overridden from the bottom up. For example, a WSDL element (JAX-WS) in a component scope overrides a customization value defined in global scope. A schema element (JAXB) in a component scope overrides a customization value defined in definition, schema, and global scopes.

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 WSDL Customization at https://javaee.github.io/metro-jax-ws/doc/user-guide/release-documentation.html#users-guide-wsdl-customization. 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 Customization" in Standard Customizations, which is available at https://javaee.github.io/metro-jax-ws/doc/user-guide/release-documentation.html#standard-customizations. 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 WSDL Customization at https://javaee.github.io/metro-jax-ws/doc/user-guide/release-documentation.html#users-guide-wsdl-customization.

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

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>

Using the Glassfish RI JAXB Data Binding and JAXB Providers

The Glassfish RI JAXB data binding and JAXB providers provide the standard Glassfish JAXB implementation, and were the default JAXB providers in previous WebLogic Server releases. If desired, you can restore the Glassfish RI providers, either globally on the server, or on a per application basis.

Note that the JAXB data binding provider and the JAXB provider are two distinct entities, although both use EclipseLink MOXy as the default. The JAXB data binding provider is used by the web services tooling and runtime, and performs tasks such as WSDL generation from a Java endpoint, as in the JWS task, and the runtime marshalling and unmarshalling of the contents of the SOAP message. The JAXB provider, on the other hand, specifies which JAXBContext provider to use for all other JAXB-related tasks. Although the JAXB provider configuration does apply to some of the web services tooling, such as Java class generation from WSDL/schema files, it includes all other JAXB usage as well. These two providers can be configured independently. For example, you could retain EclipseLink MOXy for data binding, but revert to the Glassfish RI JAXB provider for other JAXB tasks.

The data binding and JAXB providers are configured using the following Java Service Provider Interface (SPI) files in ORACLE_HOME/oracle_common/modules/com.oracle.webservices.wls.wls-ws-metainf-services-impl.jar:

  • META-INF/services/com.sun.xml.ws.spi.db.BindingContextFactory

  • META-INF/services/javax.xml.bind.JAXBContext

Note:

In 12.1.2.0, the providers were located in ORACLE_HOME/oracle_common/modules/com.oracle.webservices.wls.wls-ws-metainf-services_2.0.0.0.jar. In 12.1.1.0, the providers were located in WL_HOME/server/lib/weblogic.jar.

Global and application-level configuration is described in the following sections.

Configuring Global Server-Level Data Binding and JAXB Providers

The following jar file is provided in the WebLogic Server distribution to simplify the task of overriding the default data binding configuration:

modules/databinding.override.jar

This jar file is not included in the classpath by default. To restore the Glassfish RI data binding and JAXB provider settings, edit the WebLogic Server start script to prepend this jar file to the classpath.

For the tooling and client, you can apply this jar file globally to Ant scripts or to another build environment.

Note that the modules/databinding.override.jar file overrides both the data binding provider and the JAXB provider. If you desire to override one of these providers, but not both, you can do so by creating a simple jar file containing only the service provider entry that you want to override, and putting this first in the classpath.

For example, to configure only the Glassfish RI JAXB provider:

  1. Create a file named META-INF/services/javax.xml.bind.JAXBContext that contains a single entry for the Glassfish RI JAXB provider:

    com.sun.xml.bind.v2.ContextFactory

  2. Create a jar file, for example jaxb_override.jar, and add the file created in Step 1.

  3. Prepend this jar file to the classpath to use the Glassfish JAXB provider.

The same procedure applies if you want to configure only the Glassfish RI data binding provider. In this case, however, name the file you create in Step 1 META-INF/services/com.sun.xml.ws.spi.db.BindingContextFactory containing a single entry for the Glassfish RI data binding provider:

com.sun.xml.ws.db.glassfish.JAXBRIContextFactory.

Note:

Configuring the data binding provider may affect other behavior in addition to runtime data binding. For example, WebLogic Server generates its WSDL at runtime using the data binding provider. Conversely, some runtime SOAP faults are produced by invoking the JAXB provider directly.

As an alternative to placing the override jar file in the classpath, you can edit the Java system properties directly. For more information, see Configuring Java System Properties for JAXB.

Configuring Application-Level Data Binding and JAXB Providers

To configure the data binding and JAXB providers for a single Web application, you can use the filtering loading mechanism provided by WebLogic Server. This mechanism allows the system classpath search to be bypassed when looking for specific application classes and resources that are on the application classpath. Specifically, you use the <prefer-application-resources> tag in the weblogic-application.xml file for the application EAR or build-out directory.

For example, to configure the Glassfish RI data binding provider for an application:

  1. Edit the weblogic-application.xml file to include an entry for the data binding resource, as shown in the following example:

    <prefer-application-resources> <resource-name>META-INF/services/com.sun.xml.ws.spi.db.BindingContextFactory</resource-name>
    </prefer-application-resources>
    
  2. Create a file named META-INF/services/com.sun.xml.ws.spi.db.BindingContextFactory containing an entry for the desired provider, in this case, com.sun.xml.ws.db.glassfish.JAXBRIContextFactory.

  3. Add the file created in step 2 to the build-out directory, or add it as an entry in the EAR file.

Use the same procedure to configure the Glassfish RI JAXB provider using the values appropriate for the JAXB provider. Specifically, add the resource name META-INF/services/javax.xml.bind.JAXBContext to the weblogic-application.xml file and set the provider name in the file to com.sun.xml.bind.v2.ContextFactory.

For more information about the filtering loading mechanism in WebLogic Server, see Filtering Loader Mechanism in Tuning Performance of Oracle WebLogic Server.

Configuring Java System Properties for JAXB

You can configure the Java system properties to revert to the Glassfish RI providers and to configure the default EclipseLink MOXy providers if you had previously reverted.

Note:

In certain situations, it can be difficult to propagate the system properties to an indirectly invoked Java instance, such as a client forked from an Ant task. In these situations, it is important to ensure that the environment you are using propagates the properties.

To configure the Glassfish RI data binding and JAXB providers, set the Java system properties as shown in Table 5-15.

Table 5-15 Java System Property Settings for Glassfish RI Providers

Set this Java system property . . . To this value . . .

com.sun.xml.ws.spi.db.BindingContextFactory

com.sun.xml.ws.db.glassfish.JAXBRIContextFactory

javax.xml.bind.JAXBContext

com.sun.xml.bind.v2.ContextFactory

To configure the default EclipseLink MOXy providers, set the Java system properties as shown in Table 5-16.

Table 5-16 Java System Property Settings for EclipseLink MOXy Providers

Set this Java system property . . . To this value . . .

com.sun.xml.ws.spi.db.BindingContextFactory

com.sun.xml.ws.db.toplink.JAXBContextFactory

javax.xml.bind.JAXBContext

org.eclipse.persistence.jaxb.JAXBContextFactory