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. Figure 5-1 Data Binding With JAXB

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.

 

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 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 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> javax.xml.soap.SOAPElement
<xsd:any[]> javax.xml.soap.SOAPElement[]
<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

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.

Table 5-5 JAXB Mapping Annotations
Annotation Description
@XmlAccessorType 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:

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.

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

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.

 

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.

 

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.

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

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.

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

Scopes for Custom Binding Declarations

The following table describes the meaning of each scope.

Table 5-12 Scopes 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.

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.

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

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 “Ant Task Reference” in the WebLogic Web Services Reference. 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)

 

JAXB Custom Binding Declarations

The following table lists the typical JAXB customizations.

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 or “Customizing JAXB Bindings” in the Sun 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 sestter 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 Package name.
Package name Use the <package> element of the <schemaBindings> binding declaration 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 “Ant Task Reference” in the WebLogic Web Services Reference. 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:class name="MyClass"> 

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