5 Using JAXB Data Binding
This chapter describes how to use Java Architecture for XML Binding (JAXB) data binding.
This chapter includes the following topics:
Overview of Data Binding Using JAXB
With the emergence of XML as the standard for exchanging data across disparate systems, Web service applications need a way to access data that are in XML format directly from the Java application. Specifically, the XML content needs to be converted to a format that is readable by the Java application. Data binding describes the conversion of data between its XML and Java representations.
JAX-WS uses JAXB, described at http://jcp.org/en/jsr/detail?id=222 , to manage all of the data binding tasks. Specifically, JAXB binds Java method signatures and WSDL messages and operations and allows you to customize the mapping while automatically handling the runtime conversion. This makes it easy for you to incorporate XML data and processing functions in applications based on Java technology without having to know much about XML.
The following figure shows the JAXB data binding process.
Figure 5-1 Data Binding With JAXB
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. 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. 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 for Oracle WebLogic Server .
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 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 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
anySimpleType (for xsd:element of this type)
anySimpleType (for xsd:attribute of this type)