1. 29-Jun-15 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 http://java.sun.com/xml/jaxb/docs.html

5. A first example The DTD: The 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 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 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: The version is optional “ea” stands for “early access,” that is, not yet released Put in: 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:

11. More complex schemata JAXB requires that you supply a binding schema As noted on the previous slide, this would be 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: For simple elements, JAXB assumes: 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 set ElementName (String x); String get ElementName (); 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: Binding: Java: class ElementName extends MarshallableObject { void set AttributeName1 (String x); String get AttributeName1 (); String get SubElement1 (); void set SubElement1 (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 Results in: class ElementName extends MarshallableObject { SubElement2 get SubElement2 (); void set SubElement2 ( 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: 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: 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: Start by “opening up” the root element: Now you have somewhere to put your customizations

17. Primitive attributes By default, attributes are assumed to be Strings class SomeElement extends MarshallableObject { void set SomeAttribute (String x); String get SomeAttribute (); You can define your own binding and use the convert attribute to force the defined attribute to be a primitive, such as an int : class SomeElement extends MarshallableObject { void set SomeAttribute (int x); int get SomeAttribute ();

18. Conversions to Objects, I At the top level (within ), add a conversion declaration, such as: name is used in the binding schema type is the actual class to be used Add a convert attribute where you need it: The result should be: public java.math.BigDecimal get Name (); public void set Name (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” Your class, MyDate, would extend Date and provide parseDate and printDate methods

20. Creating enumerations 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 : 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 tag describes one of two kinds of content models: A general-content property binds a single property You’ve seen this before: 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