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 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.
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. 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 JSR 222: Java TM 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 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)
Java long to xml
The javaType binding declaration can be used to customize the binding of an XML schema datatype to a Java datatype. Customizations can involve writing a parse and print method for parsing and printing lexical representations of a XML schema datatype respectively. However, writing parse and print methods requires knowledge of the lexical representations ( XML Schema Part2: Datatypes specification ) and hence may be difficult to write. This class makes it easier to write parse and print methods. It defines static parse and print methods that provide access to a JAXB provider’s implementation of parse and print methods. These methods are invoked by custom parse and print methods. For example, the binding of xsd:dateTime to a long can be customized using parse and print methods as follows:
// Customized parse method public long myParseCal( String dateTimeString ) < java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString); long longval = convert_calendar_to_long(cal); //application specific return longval; >// Customized print method public String myPrintCal( Long longval ) < java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific String dateTimeString = DatatypeConverter.printDateTime(cal); return dateTimeString; >
There is a static parse and print method corresponding to each parse and print method respectively in the DatatypeConverterInterface . The static methods defined in the class can also be used to specify a parse or a print method in a javaType binding declaration. JAXB Providers are required to call the setDatatypeConverter api at some point before the first marshal or unmarshal operation (perhaps during the call to JAXBContext.newInstance). This step is necessary to configure the converter that should be used to perform the print and parse functionality. A print method for a XML schema datatype can output any lexical representation that is valid with respect to the XML schema datatype. If an error is encountered during conversion, then an IllegalArgumentException, or a subclass of IllegalArgumentException must be thrown by the method.
Method Summary