Best Practices for Interoperable XML Databinding with JAXB

Best Practices for Interoperable XML Databinding with JAXB Martin Grebac, SW Engineering Manager, Oracle (Project METRO)


The following is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.


Program Agenda

§ Quick intro

§ Why? The Reasoning

§ General Limitations & W3C approach

§ Common-sense approach –  Complexities to avoid –  The safe intersection –  Examples


Quick Intro

To fill a shape with an image.

1.  Use existing picture box, DO NOT delete and create new picture box.

2.  Right click on the shape. 3.  At the bottom of the submenu select

“Format Shape” 4.  Select “Fill” at the top of the “Format Shape”

dialog box. 5.  Select “Picture or Texture fill” from the options. 6.  And select “File” under the “Insert from” option. 7.  Navigate to the file you want to use and

select “Insert” 8.  On the “Format” tab, in the Size group, click on

“Crop to Fill” in the Crop tool and drag the image bounding box to the desired size

9.  DELETE THIS INSTRUCTION NOTE WHEN NOT IN USE


Wikipedia

“XML data binding refers to a means of representing information in an XML document as an object in computer memory.”

<Item ItemNumber="2"> <Part PartNumber="456"> <Description> bla bla…</Description> <Price>13.27</Price> </Part> <Quantity>5</Quantity> </Item>

Item ItemNumber: 2 Quantity: 5

Part PartNumber: 456 Description: bla bla … Price: 13.27


XML DataBinding – Where to Find

§ Direct –  Direct use of JAXB or other Databinding APIs

§  Indirect –  Web Services, JAX-WS, Jersey, REST, …

§ Based on grammar (XML Schema, DTD, RelaxNG, …) –  Classes usually represent the schema structures –  Instances represent content of XML document –  Schema feature set is large


WHY? - The Reasoning










Number of XML Databinding frameworks

§ Axis §  .NET §  IBM RAD § Mono § gSOAP2 § Castor § WCF §  JAXB § XBinder

§ SOAP4R § Spring § Castor § Xbinder § Xfire § ZSI § XMLBeans § PHP § ADB

§ …


Common XML Databinding Framework Limitations § Round-trip limitations

–  Sibling Order –  Physical Structure –  Comments and Processing Instructions –  XML Declaration

§ Feature limitations –  Incomplete schema support –  Transformations –  Document Fragment support


Common XML Databinding Framework Limitations § Round-trip limitations

–  Sibling Order –  Physical Structure –  Comments and Processing Instructions –  XML Declaration

§ Feature limitations –  à Incomplete schema support –  Transformations –  Document Fragment support


Do you start from schema? XML Schema


Do you start from schema?

XML Document

XML Schema


Do you start from schema?

XML Document

Databinding /

Web Service framework 1

Objects

XML Schema

Limited support


Or do you start from classes?

XML Document

Databinding /


Databinding /

Web Service framework

1

Objects

Objects

XML Schema

Limited support

Databinding /


Objects

Limited support



Objects



XML Document

Databinding

/ Web Service framework

1

Objects



XML Document

Databinding


1

Objects

XML Schema



XML Document

Databinding /


Databinding /


1

Objects

Objects

XML Schema

Limited support



XML Document

Databinding /


Databinding /


1

Objects

Objects

XML Schema

Limited support

Databinding /


Objects

Limited support


Number of XML Databinding frameworks

§ Axis §  .NET §  IBM RAD § Mono § gSOAP2 § Castor § WCF §  JAXB § XBinder

§ SOAP4R § Spring § Castor § Xbinder § Xfire § ZSI § XMLBeans § PHP § ADB

§ …


LOOKS PRETTY BAD …










LOOKS PRETTY BAD … … I’M DEPRESSED.










LOOKS PRETTY BAD … … I’M DEPRESSED. NOW WHAT?










Now what? The W3C Approach










W3C – The Ultimate Response

§ Basic XML Schema Patterns for Databinding ~80 –  http://www.w3.org/TR/xmlschema-patterns/ –  set of rules – “patterns” –  conforming schemas shall claim best interoperable databinding –  does not constrain the datamodel, e.g. primitive type representation

§ Advanced XML Schema Patterns for Databinding ~220 –  these are known to *not* be well supported by some databinding

frameworks/tools –  http://www.w3.org/2002/ws/databinding/edcopy/advanced/advanced.html


W3C – Examples <xs:schema />

<xs:schema elementFormDefault=“qualified”/>

@XmlSchema(elementFormDefault=XmlNsForm.QUALIFIED)

package mypkg;

<xs:schema elementFormDefault=“unqualified”/>

@XmlSchema(elementFormDefault=XmlNsForm.UNQUALIFIED)

package mypkg;


W3C – Examples <xs:schema />

<xs:schema attributeFormDefault=“unqualified”/>

@XmlSchema(attributeFormDefault=XmlNsForm.UNQUALIFIED)

package mypkg;

<xs:schema attributeFormDefault=“qualified”/>

@XmlSchema(attributeFormDefault=XmlNsForm.QUALIFIED)

package mypkg;


W3C – Examples

<xs:annotation>

<xs:documentation>State Name</xs:documentation>

</xs:annotation>

<xs:annotation>

<xs:documentation>State Name</xs:documentation>

<xs:appinfo>Application Information</xs:appinfo>

</xs:annotation>


W3C – Examples §  id=“1” §  import/include rules §  <xs:element name=“globalEl” type=“xs:string”>

§  abstract==“false” §  …

§  <xs:element name="non-Identifier-Name“>

§  abstract==“true”

§  minOccurs / maxOccurs

§  …


Databinding interoperability

§ Framework Language Passed Skip Fail –  A Java 401 185 77 –  B Java 455 71 77 –  C Java 531 0 72 –  D C# 483 61 59 –  E Ruby 262 23 318 –  F Python 211 89 303 –  G C 548 1 54 –  H PHP 467 71 65 –  I C++ 465 38 100 –  J Java 448 33 122 –  K Java 499 58 46 –  …

(source: http://www.w3.org/2002/ws/databinding/edcopy/report/basic.html)


Common-Sense Approach










Common-Sense Approach (JAXB view)










Common Sense Alternative

§ No long list of patterns to keep in mind or check against § Keep It Short & Simple § Works both ways

–  Java à Schema –  Schema à Java –  Project based decision


Avoid problematic primitive types

anySimpleType

decimal float double

integer

long nonPositiveInteger nonNegativeInteger

int negativeInteger unsignedLong positiveInteger

short unsignedInt

byte unsignedShort

unsignedByte

§ Boolean / boolean § Byte / byte § Short / short § Integer / int § Long / long § Double / double § BigInteger*


.NET Mapping

§ System.Boolean § System.SByte § System.Int16 § System.Int32 § System.Int64 § System.Double § System.UInt64*

anySimpleType

decimal float double

integer

long nonPositiveInteger nonNegativeInteger

int negativeInteger unsignedLong positiveInteger

short unsignedInt

byte unsignedShort

unsignedByte


Be Explicit. Use @XmlSchemaType

@XmlElement

@XmlSchemaType(name=“xs:long”)

public Long lng;

@XmlElement

@XmlSchemaType(name=“xs:anyUri”)

public java.net.URI uri;


Dates

java.xml.datatype.XmlGregorianCalendar

.NET: String

Java: public XmlGregorianCalendar orderDate;

XSD:<xs:element name=“orderDate” type=“xs:anySimpleType”/>

java.util.Date

java.util.Calendar


Be Explicit

§  If direct date mapping required, still use XmlGregorianCalendar

@XmlSchemaType(name=“dateTime”)

public XMLGregorianCalendar orderDate;

§ XSD: <xs:element name=“orderDate” type=“xs:dateTime”/> §  .NET: System.DateTime


Avoid Anonymous types <xsd:complexType name="PurchaseOrderType">

<xs:element name=“…” type=“ns:SomeOtherType”/>

@XmlType()

@XmlType(name=“SomeOtherType”)

<xsd:complexType name="PurchaseOrderType">

…

<xsd:complexType> …

@XmlType(name=“”)


Avoid Mixed Content of Any Type

<ex:notMixed>

<ex:notMixedElement>Stuff</ex:notMixedElement>

</ex:notMixed>

<ex:mixed>

<ex:element1>string</ex:element1>mixed content

<ex:element2>string</ex:element2>

mixed content

</ex:mixed>

@XmlMixed


Avoid Mixed Content of Any Type @XmlElement(name = “var1")

protected short var1;

@XmlElement(name = “var2")

protected double var2;

…

@XmlElementRefs({

@XmlElementRef(name = “var1", type = JAXBElement.class),

@XmlElementRef(name = “var2", type = JAXBElement.class),

})

@XmlMixed

protected List<Serializable> content;


Avoid substitution groups

<element name="global" type="string"

<element name="global-1" type="string" substitutionGroup="tns:global"/>

<element name="global-2" type="string" substitutionGroup="tns:global"/>


Don’t Rely on Type Inheritance – by restriction <xs:complexType name=“parentType">

<xs:sequence>

<xs:element name=“e1" type="xs:integer" minOccurs="0" maxOccurs="1"/>

<xs:element name=“e2" type="xs:string" nillable="true" />

</xs:sequence>

<xs:attribute name=“a1" type="xs:date" use="optional" />

</xs:complexType>

<xs:complexType name=“childType"><xs:complexContent>

<xs:restriction base=“parentType">

<xs:sequence>

<xs:element name=“e1" type="xs:integer" minOccurs="1" />

<xs:element name=“e2" type="xs:string" nillable="false" />

</xs:sequence>

<xs:attribute name=“a1" type="xs:date" use="required" />

</xs:restriction>

</xs:complexContent></xs:complexType>


Common Sense Alternative

§ Think about datatypes § Be explicit § Use XMLGregorianCalendar § Avoid anonymous types § Avoid mixed content! § Avoid substitution groups § Do not rely on inheritance by restriction


KEEP IT


KEEP IT

SIMPLE


Common Sense Alternative §  http://jaxb.java.net §  http://blogs.oracle.com/mgrebac §  http://download.oracle.com/docs/cd/E17802_01/webservices/webservices/reference/

tutorials/wsit/doc/WSITTutorial.pdf §  http://www.w3.org/TR/xmlschema-patterns/ §  http://www.w3.org/2002/ws/databinding/edcopy/advanced/advanced.html §  http://www.w3.org/2002/ws/databinding/patterns/6/09/ §  http://msdn.microsoft.com/en-us/library/ff842400%28d=printer%29.aspx §  http://www.infoq.com/articles/schema-for-ws-part1 §  http://msdn.microsoft.com/en-us/netframework/gg413252 §  http://www.ibm.com/developerworks/xml/library/ws-tip-j2eenet2/index.html §  http://www.ibm.com/developerworks/java/library/ws-tip-j2eenet3/index.html


Q

A & &


The preceding is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.

Best Practices for Interoperable XML Databinding with JAXB

Software

Transcript of Best Practices for Interoperable XML Databinding with JAXB