Getting Started With WebLogic Web Services Using JAX-WS

Using JAXB Data Binding

The following sections provide information about using JAXB data binding:

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 Java Architecture for XML Binding (JAXB) 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.

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.

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

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.

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.

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.

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.

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:

The @XmlAccessorType can be specified with the @XmlType and @XmlRootElement annotations.

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

For more information, see the javax.xml.bind.annotation.XmlAccessorType Javadoc. 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:

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

For more information, see the javax.xml.bind.annotation.XmlElement Javadoc.

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.

For more information, see the javax.xml.bind.annotation.XmlMimeType Javadoc.

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:

The @XmlRootElement can be specified with the @XmlType and @XmlAccessorType annotations.

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

For more information, see the javax.xml.bind.annotation.XmlRootElement Javadoc. 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.

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:

The @XmlType can be specified with the @XmlRootElement and @XmlAccessorType annotations.

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

For more information, see the javax.xml.bind.annotation.XmlType Javadoc. 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.

The following table describes the meaning of each scope.

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-13, 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. 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. 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.

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

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

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

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

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

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

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

JAXB Custom Binding Declarations

The following table lists the typical JAXB customizations.

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

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

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

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

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