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:
- Bind —Binds XML Schema to schema-derived JAXB Java classes, or value classes. Each class provides access to the content via a set of JavaBean-style access methods (that is, get and set). Binding is managed by the JAXB schema compiler.
- Unmarshal —Converts the XML document to create a tree of Java program elements, or objects, that represents 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.
This following sections describe:
- 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.
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.
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.
Please note, when invoking the jwsc , wsdlc , or clientgen Ant tasks described in these procedures:
- You must specify the type=»JAXWS» attribute to generate a JAX-WS Web Service and JAXB binding artifacts. For jwsc , you specify the type attribute as part of the child element.
- You can optionally specify the 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.
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 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.