5 Using 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.
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
andset
). 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—Describes how to develop the JAXB data binding artifacts using WebLogic Server.
-
Standard Data Type Mapping—Describes the standard built-in and user-defined data types that are supported.
-
Customizing Java-to-XML Schema Mapping Using JAXB Annotations—Describes how you can control and customize the Java-to-XML Schema mapping using JAXB annotations in the JWS file.
-
Customizing XML Schema-to-Java Mapping Using Binding Declarations—Describes how you can control and customize the XML Schema-to-Java mapping using binding declarations that are defined in a separate file or embedded inline.
-
Using the Glassfish RI JAXB Data Binding and JAXB Providers—Describes the global server-level and application-level procedures required to configure the Glassfish RI JAXB Data Binding and JAXB providers instead of the default EclipseLink MOXy JAXB providers.
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.
-
Start from Java: Using this programming model, you create the Java classes. At run-time, JAXB marshals the Java objects to generate the XML content which is then packaged in a SOAP message and sent as a web service request or response.
To control the Java-to-XML mapping, you include JAXB annotations in your JWS file, as described in Customizing Java-to-XML Schema Mapping Using JAXB Annotations. If no customizations are required, JAXB uses the standard built-in and user-defined data type mapping as described in the following sections: Java-to-XML Mapping for Built-In Data Types and Supported Java User-Defined Data Types.
For more information about this programming model, see Developing WebLogic Web Services Starting From Java: Main Steps.
-
Start from WSDL: Using this programming model, the XML Schemas exist and JAXB unmarshals the XML document to generate the Java objects.
To control the XML-to-Java mapping, you can define custom binding declarations within the WSDL or XML Schema, or in an external file, as described in Customizing XML Schema-to-Java Mapping Using Binding Declarations. If no customizations are required, the standard built-in and user-defined data type mapping as described in the following sections: XML-to-Java Mapping for Built-in Data Types and Supported XML User-Defined Data Types.
For more information about this programming model, see Developing WebLogic Web Services Starting From a WSDL File: Main Steps.
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. Forjwsc
, 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) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|
|
JavaBean |
|
JavaBean |
|
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. |
|
Array of the list data type. |
Array derived from |
Array of the Java equivalent of the |
Array derived from |
Array of Java equivalent. |
Derivation of a complex type from a simple type. |
JavaBean with a property called |
|
|
|
|
|
|
|
Common parent type of union members. |
|
Java If the XML data type is built-in and usually maps to a Java primitive data type (such as |
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. |
|
Array and multidimensional array of any supported data type (when used as a JavaBean property) |
An element in a |
Note: The data type of the runtime object must be a known type. |
|
|
Literal Array |
|
Literal Array |
|
Literal Array |
|
Literal Array |
|
Literal Array |
|
Literal Array |
|
Literal Array |
|
Literal Array |
|
Literal Array |
|
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 |
---|---|
|
Specifies whether fields or properties are mapped by default. See Specifying Default Serialization of Fields and Properties (@XmlAccessorType 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. See Mapping Properties to Local Elements (@XmlElement). |
|
Associates the MIME type that controls the XML representation of the property with a textual representation, such as |
|
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). |
|
Binds other classes when binding the current class. See Binding a Set of Classes (@XmlSeeAlso). |
|
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 |
---|---|
|
Specifies
|
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 |
---|---|
|
Local name of the XML element that represents the property of a JavaBean. This element defaults to the JavaBean property name. |
|
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. |
|
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 |
---|---|
|
Specifies the textual representation of the MIME type, such as |
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 |
---|---|
|
Local name of the XML element. This element defaults to the class name. |
|
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 |
---|---|
|
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 of the XML Schema type to which the class is mapped. |
|
Name of the target namespace of the XML Schema type. By default, the target namespace to which the package containing the class is mapped. |
|
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 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:
|
Schema scope |
Describes JAXB customization values that are contained within the 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:
-
WSDL Customization at
https://javaee.github.io/metro-jax-ws/doc/user-guide/release-documentation.html#users-guide-wsdl-customization
-
"Customizing XML Schema to Java Representation Binding" in the JAXB specification at
http://jcp.org/en/jsr/detail?id=222
.
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:
-
Embed a JAX-WS or JAXB binding declaration in the WSDL file using the jaxws:bindings
element as a WSDL extension. See Embedding JAX-WS or JAXB Binding Declarations in the WSDL File. -
Embed a JAXB binding declaration in the XML Schema as part of an
<appinfo>
element. See Embedding JAXB Binding Declarations in the XML Schema.
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 If you do not specify this customization, the 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 <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 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:
The following example disables the wrapper style rules for the <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 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:
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 |
Class name |
Use the
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 The following example defines the Java method name for the <bindings node="wsdl:definitions/wsdl:portType[@name='SimpleServiceImpl']/wsdl:operation[@name='EchoHello']">
<method name="Greeting"></method>
</bindings> |
Java parameter name |
Use the The following example defines the Java method name for the <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 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 |
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 You can specify attributes and elements to the
<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 For an example, see the description of "Package name" in this table. |
Package name |
Use the If you do not specify this customization, the For example, the following defines the package name for all JAXB classes generated from the <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 The following example defines the class name for an <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 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 For example, see Global bindings (above). |
Javadoc |
Use the 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:
-
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
-
Create a jar file, for example
jaxb_override.jar
, and add the file created in Step 1. -
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:
-
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>
-
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
. -
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 . . . |
---|---|
|
|
|
|
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 . . . |
---|---|
|
|
|
|