Fonts and colors Times New Roman “quotes” Trebuchet "quotes" yellow blue pink green violet

JAXB Java Architecture for XML Binding

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

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 is due Q4 (fourth quarter) 2002

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,

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

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

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);

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

Limitations of JAXB DTDs are the only schema language currently supported –Later versions should support more schema languages DTDs don’t support namespaces, so neither does JAXB –Again, this is likely to change with future releases JAXB does not support the following legal DTD constructs: –Internal subsets –NOTATIONs –ENTITY and ENTITIES –Enumerated NOTATION types

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:

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

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

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 {... }

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();

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

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 ();

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

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 parse and print methods xxx

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(); }

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

Using JAXB