JAXB is a Java framework that generates Java classes from an XML DTD or schema. It allows Java objects to be converted to and from XML. The document discusses what JAXB is, how it works, and how to customize the generated Java classes through a binding schema. Key points include: JAXB generates classes specific to an XML DTD, it requires a DTD or schema as input, and a binding schema can customize how classes are generated to map XML elements to Java properties.

1. Jan 21, 2016
JAXB
Java Architecture for XML Binding

2. What is JAXB?
 JAXB is Java Architecture for XML Binding
 SAX and DOM are generic XML parsers
 They will parse any well-structured XML
 JAXB creates a parser that is specific to your DTD
 A JAXB parser will parse only valid XML (as defined by your
DTD)
 DOM and JAXB both produce a tree in memory
 DOM produces a generic tree; everything is a Node
 JAXB produces a tree of Objects with names and attributes as
described by your DTD

3. Advantages and disadvantages
 Advantages:
 JAXB requires a DTD

Using JAXB ensures the validity of your XML
 A JAXB parser is actually faster than a generic SAX parser
 A tree created by JAXB is smaller than a DOM tree
 It’s much easier to use a JAXB tree for application-specific code
 You can modify the tree and save it as XML
 Disadvantages:
 JAXB requires a DTD

Hence, you cannot use JAXB to process generic XML (for example, if
you are writing an XML editor or other tool)
 You must do additional work up front to tell JAXB what kind of tree
you want it to construct

But this more than pays for itself by simplifying your application
 JAXB is new: Version 1.0 dates from Q4 (fourth quarter) 2002

4. How JAXB works
 JAXB takes as input two files: your DTD and a binding
schema (which you also write)
 A binding schema is an XML document written in a “binding
language” defined by JAXB (with extension .xjs)
 A binding schema is used to customize the JAXB output
 Your binding schema can be very simple or quite complex
 JAXB produces as output Java source code which you
compile and add to your program
 Your program will uses the specific classes generated by JAXB
 Your program can then read and write XML files
 JAXB also provides an API for working directly with XML
 Some examples in this lecture are taken from the JAXB User’s guide,
http://java.sun.com/xml/jaxb/docs.html

5. A first example
 The DTD: <!ELEMENT book (title, author, chapter+) >
<!ELEMENT title (#PCDATA) >
<!ELEMENT author (#PCDATA)>
<!ELEMENT chapter (#PCDATA) >
 The schema: <xml-java-binding-schema>
<element name="book" type="class" root="true" />
</xml-java-binding-schema>
 The results: public Book(); // constructor
public String getTitle();
public void setTitle(String x);
public String getAuthor();
public void setAuthor(String x);
public List getChapter();
public void deleteChapter();
public void emptyChapter();
Note 1: In these slides
we only show the class
outline, but JAXB
creates a complete
class for you
Note 2: JAXB constructs
names based on yours,
with good capitalization
style

6. Adding complexity
 Adding a choice can reduce the usefulness of the parser
 <!ELEMENT book (title, author, (prologue | preface), chapter+)>
<!ELEMENT prologue (#PCDATA) >
<!ELEMENT preface (#PCDATA) >
 With the same binding schema, this gives:

public Book();
public List getContent();
public void deleteContent();
public void emptyContent();
 An improved binding schema can give better results

7. Improving the binding schema
 <xml-java-binding-schema>
<element name="book" type="class" root="true">
<content>
<element-ref name="title" />
<element-ref name="author” />
<choice property="prologue-or-preface" />
</content>
</element>
</xml-java-binding-schema>
 Result is same as the original, plus methods for the choice:
 public Book(); // constructor
. . .
public void emptyChapter();
public MarshallableObject getPrologueOrPreface();
public void setPrologueOrPreface(MarshallableObject x);

8. Marshalling
 marshal, v.t.: to place or arrange in order
 marshalling: the process of producing an XML
document from Java objects
 unmarshalling: the process of producing a content tree
from an XML document
 JAXB only allows you to unmarshal valid XML
documents
 JAXB only allows you to martial valid content trees
into XML

9. Limitations of JAXB
 JAXB only supports DTDs and a subset of XML
Schemas
 Later versions may support more schema languages
 JAXB does not support the following legal DTD
constructs:
 Internal subsets
 NOTATIONs
 ENTITY and ENTITIES
 Enumerated NOTATION types

10. A minimal binding schema
 A JAXB binding schema is itself in XML
 Start with: <xml-java-binding-schema version="1.0ea">
 The version is optional
 “ea” stands for “early access,” that is, not yet released
 Put in:
<element name="rootName" type="class" root="true" />
for each possible root element
 An XML document can have only one root
 However, the DTD does not say what that root must be
 Any top-level element defined by the DTD may be a root
 The value of name must match exactly with the name in the DTD
 End with: </xml-java-binding-schema>

11. More complex schemata
 JAXB requires that you supply a binding schema
 As noted on the previous slide, this would be
<xml-java-binding-schema version="1.0ea">
<element name="rootName" type="class" root="true" />
</xml-java-binding-schema>
 With this binding schema, JAXB uses its default rule
set to generate your “bindings”
 A binding is an association between an XML element and
the Java code used to process that element
 By adding to this schema, you can customize the
bindings and thus the generated Java code

12. Default bindings, I
 A “simple element” is one that has no attributes and only
character contents:
 <!ELEMENT elementName (#PCDATA) >
 For simple elements, JAXB assumes:
<element name="elementName" type="value"/>
 JAXB will treat this element as an instance variable of the class
for its enclosing element
 This is the default binding, that is, this is what JAXB will assume
unless you tell it otherwise

For example, you could write this yourself, but set type="class"
 For simple elements, JAXB will generate these methods in the
class of the enclosing element:
void setElementName(String x);
String getElementName();
 We will see later how to convert the #PCDATA into some type
other than String

13. Default bindings, II
 If an element is not simple, JAXB will treat it as a class
 Attributes and simple subelements are treated as instance variables
 DTD: <!ELEMENT elementName (subElement1, subElement2) >
<!ATTLIST elementName attributeName CDATA #IMPLIED>
 Binding: <element name="elementName" type="class">
<attribute name="attributeName"/>
<content>
<element-ref name="subElement1" /> <!-- simple element -->
<element-ref name="subElement2" /> <!-- complex element -->
</content>
</element>
 Java: class ElementName extends MarshallableObject {
void setAttributeName1(String x);
String getAttributeName1();
String getSubElement1();
void setSubElement1(String x);
// Non-simple subElement2 is described on the next slide

14. Default bindings, III
 If an element contains a subelement that is defined by a
class, the code generated will be different
 <element name="elementName" type="class">
<content>
<element-ref name="subElement2" />
<!-- Note that "element-ref" means this is a reference to
an
element that is defined elsewhere, not the element
itself -->
</content>
</element>
 Results in:
class ElementName extends MarshallableObject {
SubElement2 getSubElement2();
void setSubElement2(SubElement2 x);
...}
 Elsewhere, the DTD definition for subElement2 will result in:
class SubElement2 extends MarshallableObject { ... }

15. Default bindings, IV
 A simple sequence is just a list of contents, in order, with no
+ or * repetitions
 Example: <!ELEMENT html (head, body) >
 For an element defined with a simple sequence, setters and getters are
created for each item in the sequence
 If an element’s definition isn’t simple, or if it contains
repetitions, JAXB basically “gives up” and says “it’s got
some kind of content, but I don’t know what”
 Example: <!ELEMENT book (title, forward, chapter*)>
 Result:
public Book(); // constructor
public List getContent(); // "general content"--not too useful!
public void deleteContent();
public void emptyContent();

16. Customizing the binding schema
 You won’t actually see these default bindings anywhere--
they are just assumed
 If a default binding is OK with you, don’t do anything
 If you don’t like a default binding, just write your own
 Here’s the minimal binding you must write:
<xml-java-binding-schema>
<element name="rootElement" type="class" root="true" />
</xml-java-binding-schema>
 Start by “opening up” the root element:
<xml-java-binding-schema>
<element name="rootElement" type="class" root="true" >
</element>
</xml-java-binding-schema>
 Now you have somewhere to put your customizations

17. Primitive attributes
 By default, attributes are assumed to be Strings
 <!ATTLIST someElement someAttribute CDATA #IMPLIED>
 class SomeElement extends MarshallableObject {
void setSomeAttribute(String x);
String getSomeAttribute();
 You can define your own binding and use the convert attribute
to force the defined attribute to be a primitive, such as an int:
 <element name="someElement " type="class" >
<attribute name="someAttribute" convert="int" />
</element>
 class SomeElement extends MarshallableObject {
void setSomeAttribute(int x);
int getSomeAttribute();

18. Conversions to Objects, I
 At the top level (within <xml-binding-schema>), add
a conversion declaration, such as:
 <conversion name="BigDecimal" type="java.math.BigDecimal" />

name is used in the binding schema

type is the actual class to be used
 Add a convert attribute where you need it:
 <element name="name" type="value" convert="BigDecimal" />
 The result should be:
 public java.math.BigDecimal getName();
public void setName(java.math.BigDecimal x);
 This works for BigDecimal because it has a
constructor that takes a String as its argument

19. Conversions to Objects, II
 There is a constructor for Date that takes a String as its
one argument, but this constructor is deprecated
 This is because there are many ways to write dates
 For an object like this, you need to supply methods to “parse”
and “print”
 <conversion name="MyDate" type="java.util.Date”
parse="MyDate.parseDate" print="MyDate.printDate"/>
 Your class, MyDate, would extend Date and provide
parseDate and printDate methods

20. Creating enumerations
 <!ATTLIST shirt size (small | medium | large) #IMPLIED> defines an attribute
of shirt that can take on one of a predefined set of values
 A typesafe enum is a class whose instances are a predefined set of values
 To create a typesafe enum for size:
 <enumeration name="shirtSize" members="small medium large">
 <element name="shirt" ...>
<attribute name="size" convert="shirtSize" />
</element>
 You get:
 public final class ShirtSize {
public final static ShirtSize SMALL;
public final static ShirtSize MEDIUM;
public final static ShirtSize LARGE;
public static ShirtSize parse(String x);
public String toString();
}

21. Content models
 The <content> tag describes one of two kinds of content
models:
 A general-content property binds a single property

You’ve seen this before:
<content property="my-content" />

Gives: public List getMyContent();
public void deleteMyContent();
public void emptyMyContent();
 A model-based content property can contain four types of
declarations:

element-ref says that this element contains another element

choice says that there are alternative contents

sequence says that contents must be in a particular order

rest can be used to specify any kind of content

22. Using JAXB
 JAXB is not currently a part of the standard Java distributions
 The steps involved in using JAXB are:
 Download, install, and configure JAXB
 Write a JAXB schema to describe the bindings you want for your XML
 Use JAXB to read the JAXB schema and the XML DTD (or XML
Schema) and produce Java code
 Add the Java code to your program and compile it
 Use the resultant program to:

Read and validate XML input files

Modify the XML tree

Optionally validate and output the modified XML
 Note: Validation is optional and can be performed during unmarshalling
or any time thereafter

23. The End