A JAXB Tutorial

Wolfgang Laun
Thales Rail Signalling Solutions GesmbH

1 Introduction 1.1 About JAXB 1.2 Overview 1.3 Hello World 2 Writing an XML Schema for JAXB 2.1 XML Schema Types 2.2 JAXB Examples 2.2.1 Defining an Integer Range Type 2.2.2 Numeric Types 2.2.3 Defining a String with Length Limits 2.2.4 Defining a String Type Restricted By Pattern 2.2.5 Date and Time 2.2.6 Binary Data 2.2.7 Defining a List of Integers 2.2.8 Defining Other Lists 2.2.9 Defining an Enumeration 2.2.10 Defining a Type Union 2.2.11 Defining Types for XML Elements Without Content 2.2.12 Defining Types for XML Elements With Content 2.2.12.1 Content: A Value 2.2.12.2 Content: An Ordered Set of Elements 2.2.12.3 Content: An Unordered Set of Elements 2.2.12.4 Content: Alternative Elements 2.2.12.5 Content: A Homogeneous List of Elements 2.2.12.6 Content: A Mixed List of Elements 2.2.12.7 Mixed Content 2.2.12.8 No Value 2.2.13 Defining Subtypes 2.2.14 Substitution Groups 2.2.15 Referring to Another XML Element 2.2.16 Elements With Any Type 2.2.16.1 DOM Elements 2.2.16.2 Another Content Tree as Element 2.2.17 Image Data 2.3 Hints on Writing XML Schemas 2.3.1 Don't Use Anonymous Types 2.3.2 Common Schema Definitions 2.3.3 A Note on Groups 2.3.4 Conserving Compatibility 2.3.5 Spurious Classes 2.3.6 Avoid Unnecessary JAXBElement<?> 3 Unmarshalling and Using the Data 3.1 Unmarshalling 3.2 Using the Element Tree 3.3 Validation 3.4 Validation Event Handling 3.5 The JAXB Context 4 Building and Marshalling an XML Document 4.1 The Object Factory 4.2 Assembling Document Tree Nodes 4.3 Assembling Data with Links (ID, IDREF) 4.3.1 One Element per Identification

4.3.2 Preserving Object Identity 4.4 Last Resort: Assembling a Java Object 4.5 Calling marshal 5 Customizing 5.1 Reasons for Customizing 5.2 Defining Package Names 5.3 Overriding Names 5.4 Adding Documentation 5.5 Interning Strings 5.6 Overriding the Datatype 5.6.1 Replacing the Conversions 5.6.2 Replacing a Simple Type 6 JAXB Annotations 6.1 How a Schema Mapping Is Implemented 6.2 A Survey Of JAXB Annotations 6.2.1 Top-level Elements: XmlRootElement 6.2.2 Annotation for Classes: XmlType 6.2.3 Annotations for the Schema: XmlSchema 6.2.4 The Object Factory: XmlRegistry, XmlElementDecl 6.2.5 Controlling Element Selection: XmlAccessorType, XmlTransient 6.2.6 Class Inclusion: XmlSeeAlso 6.2.7 Annotations for Fields 6.2.7.1 The Annotation XmlElement 6.2.7.2 The Annotation XmlList 6.2.7.3 Class Fields as Attributes: XmlAttribute 6.2.7.4 Mapping a Class to Simple Content or Simple Type: XmlValue 6.2.7.5 Collecting Unspecified Attributes: XmlAnyAttribute 6.2.7.6 Collecting Unspecified Elements: XmlAnyElement 6.2.7.7 Wrapping Repeated Elements: XmlElementWrapper 6.2.7.8 Annotations for Mixed Content: XmlElementRef, XmlMixed 6.2.8 Annotations for Enums: XmlEnum, XmlEnumValue 6.2.9 Type Adapters: XmlJavaTypeAdapter 6.2.10 Type Mapping: XmlSchemaType 6.2.11 Annotations for Object References: XmlID, XmlIDREF

which contain attributes and the content as instance variables and refer to child elements by object references.util. Schemas written in the XML Schema Language can describe structural relationships and data types. with a very high level of distinctiveness.1 About JAXB JAXB is an acronym derived from Java Architecture for XML Binding. The application can then navigate through the tree in memory to access the data it needs. In many of these cases it is possible to circumnavigate the problem by adding binding declarations to direct the schema compiler in some specific way to achieve a successful binding. Unmarshalling an XML document with the appropriate JAXB method also results in a tree of objects. The most convenient way to obtain the Java type information describing the node elements is by compiling an XML schema. an attribute.0 on contain bug fixes and minor additions. etc.List. JAXB also supports marshalling and unmarshalling for SAX. provides methods for unmarshalling a document from various sources as well as for marshalling a content tree to various destinations. Versions from 2. the Simple API for XML. DOM data. usually written in the W3C XML Schema Language. as compared to version 1.1 Introduction 1. is contained in objects of a single type. providing significant benefits as compared to previously available methods such as the one following the Document Object Model (DOM). The resulting set of classes defines the types required for accessing elements. As of the time of this writing (March 2009) JAXB is available as version 2. using the JAXB Binding Compiler xjc. In the DOM approach. JAXB uses Java's annotations for augmenting the generated classes with additional information that bridges the gap between what is decribed by an XML schema and the information available (via Java's reflection mechanisms) from a set of Java class definitions. with individual node objects containing an element. attributes and other content in a typesafe way. It constitutes a convenient framework for processing XML documents. It should be noted that the XML Schema language is capable of defining XML structures that cannot be bound by a schema compiler. however.) 1. supported with the code generated by the Binding Compiler.1. The scalar datatypes of the XML Schema Language are mapped to Java data types. linked according to the XML document's structure.2 Overview The chapter Writing an XML Schema for JAXB discusses how JAXB represents the . a CDATA section. with the significant difference being that the nodes in this tree correspond to XML elements. was a big step ahead and has brought JAXB to a mature level. Version 2. Values are invariably provided as strings. Lists of values and certain element groupings are mapped to Java's java. the parser creates a tree of objects that represents the content and organization of data in the document. Adding such annotations to existing Java classes prepares them for being used by JAXB's runtime.10. (JAXB version 1 should not be used any more. The JAXB runtime library.

-. Some of these features are: -.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www. Customizing discusses the various options for augmenting and modifying schema information.w3.Some features rely on specific implementations of JAXB.3 Hello World We'll stick with the tradition and use a sort of "Hello World" XML document to illustrate the typical scenario for creating the Java classes and their use to marshal a document. Much of what can be done with JAXB is not covered here. Chapters Unmarshalling and Using the Data and Building and Marshalling an XML Document describe how to convert XML document data into a content tree and vice versa. The XML Schema on hello. influencing several aspects of the generated Java code.The XML Schema compiler xjc may be extended with plugins . -.xsd defines the structure of our document.0"> <xsd:element name="Greetings" type="GreetingListType"/> <xsd:complexType name="GreetingListType"> <xsd:sequence> <xsd:element name="Greeting" type="GreetingType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="GreetingType"> <xsd:sequence> <xsd:element name="Text" type="xsd:string"/> </xsd:sequence> . We'll not discuss any details in this subsection. it's just here to give you the overall picture. <?xml version="1. The examples illustrate how a schema should be written to produce easy-to-use Java code.org/2001/XMLSchema" xmlns:jxb="http://java.com/xml/ns/jaxb" jxb:version="2.various XML Schema language constructs in Java.sun. The intention of this tutorial is to provide you with examples and guidelines for the essential features of JAXB. 1. The chapter JAXB Annotations presents the most important JAXB annotations and examples using them on hand-written Java classes. each of which contains a greeting (such as "Hello world") and an attribute for registering the language of the salutation. which is to contain a series of salutations. which derives a schema from a set of Java classes. A good place for digging up remarkable tricks is the archives of Kohsuke Kawaguchi's Blog.The XML Schema generator schemagen.obviously an area for experts.

Finally. Here's a sequence of these calls: .createGreetingListType().. Marshaller m = jc. m. xjc -p hello hello..marshal( gl. } public void marshal() { try { JAXBElement<GreetingListType> gl = of. } } } The constructor uses a method from the object factory to create an object of the document's top level XML element type. public Hello(){ of = new ObjectFactory(). String l ){ GreetingType g = of.add( g ).createGreetings( grList ).bind. with a call to marshal. The class Hello shows how to use them.util. import hello.*.*. grList.e. } catch( JAXBException jbe ){ // . private GreetingListType grList. and the resulting XML document is written to the standard output stream.setLanguage( l ). public class Hello { private ObjectFactory of. GreetingListType. JAXBContext jc = JAXBContext. g.. i.newInstance( "hello" ). import javax. the list is wrapped in its XML element. defining the package name hello for the generated classes.<xsd:attribute name="language" type="xsd:language"/> </xsd:complexType> </xsd:schema> Now we can call the JAXB schema compiler.xml. The make method adds another salutation with its text element and the language attribute. } public void make( String t. grList = of.out ).setText( t ).createGreetingType(). System.createMarshaller(). g.getGreeting().*. import java.xsd This generates several classes in the subdirectory hello.

you</Text> </Greeting> </Greetings> . madame". h. you". for better readability. formatted. <?xml version="1. madame</Text> </Greeting> <Greeting language="en"> <Text>Hey. The output is shown below.0" encoding="UTF-8" standalone="yes"?> <Greetings> <Greeting language="fr"> <Text>Bonjour.make( "Hey. h. h.marshal().make( "Bonjour. "fr" ).Hello h = new Hello(). "en" ).

An XML element of some complex type may have child elements or attributes or both. with the intent of defining one or more hierarchical types defining XML documents. booleans. structure (or record) and union. and to define a pattern for a string type. the schema's element grouping facilites <xsd:all>. with xsd as the namespace identifier. A good introduction to the XML Schema language is the XML Schema Part 0: Primer. i. list. which are available to set lower or upper bounds for values or string lengths.org/2001/XMLSchema" xmlns:jxb="http://java.0"> 2. to enumerate all legal values. xs) identifier must be bound to the URI identifying the XML Schema language. such as lists or maps. If used. JAXB uses enumerations restricting strings to define an enum type. Please notice that the tags of schema elements are presented in the qualified form. Only by using these features will you receive the full benefit of JAXB.) Data structuring concepts are expressed by using the complex type construct of the schema language.sun.w3.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.. Type information deals with the definition of structure. The XML Schema Language offers a rich set of features to achieve the required structuring and typing. are ignored by the Schema Compiler. (Section Validation explains how to enable facet checking. Although all data in XML is text. dates and times.e.com/xml/ns/jaxb" jxb:version="2. <xsd:union>. the composition of document nodes.. We'll discuss schema structuring and typing concepts in more detail in the next section. to limit the precision. however. Both is done in the schema element of the XML schema: <?xml version="1. strings. where examples of XML Schema language constructs are related to the Java code that the JAXB compiler uses for their representation. provided by the World Wide Web Consortium (W3C). This is done by adding so-called facets. <xsd:choice> and <xsd:sequence> in combination with repetition limit attributes let you define XML structures that are the equivalent of the classic concepts of array. and for references and other XML constructs. The XML Schema language provides the elementary data types for numbers.2 JAXB Examples This chapter discusses various XML Schema constructs and how they are bound by . also the jxb namespace prefix must be bound. it should generally not be defined as String in the Java classes derived from a schema.g. Other facets. URIs. This (or some other name. For child elements. e. and the classification of scalar (or list) values for content and attributes.1 XML Schema Types A schema describes data types. User-defined data types can be derived from any elementary type by adding one or more restrictions.2 Writing an XML Schema for JAXB 2. which will not only take care of all the necessary conversions to or from the textual representation in XML but also with the transformation of XML structures to Java data patterns.

// . disappointing anwer is that there is no such code. to the marshaller or unmarshaller used for handling your data. we . limiting permissible values to the range 1 to 255. you might ask.. 2. 2. required = true) protected int group. } // . created from your XML schema. the resulting Java code is generally shown without the annotations. the root of the tree is given by xsd:decimal. Doing away with fractional digits. <xsd:simpleType name="GroupType"> <xsd:restriction base="xsd:int"> <xsd:minInclusive value="1"/> <xsd:maxInclusive value="255"/> </xsd:restriction> </xsd:simpleType> A simple type restricting xsd:int will not result in a separate Java class being generated. According to the XML Schema definition..1 Defining an Integer Range Type The XML Schema snippet shown below defines an integer type.2. like in this class derived from a schema type where an element has an attribute with name Group and type GroupType: public class ElementType { // .validation. Leaving double and float aside. JAXB expects you to request detailed validation explicitly by passing a javax..math. We'll discuss this in the section on Validation. you'll see simple get and set methods. There is one Java type providing just that: java. For brevity and clarity.the JAXB schema compiler xjc. this data type represents decimal numbers with an unspecified range of fractional and total digits. perhaps.2. } Where is. @XmlAttribute(name = "Group".. public int getGroup() { return group.2 Numeric Types The schema language features a multi-tiered type hierarchy of built-in numeric datatypes. } public void setGroup(int value) { this.group = value. the code that ensures that the integer value is between the bounds? The short and.. We'll discuss them briefly in this subsection. If you peek into one of these class definitions.Schema object.. The JAXB compiler will simply fall back to int (or Integer) in all the places where GroupType is used.xml.BigDecimal.

public class NumericZooType { protected protected protected protected protected BigDecimal decimal. The non-negative types comprise xsd:nonNegativeInteger and the unsigned variations of the binary integer types. another one for their obscure cousins. Java provides null as a convenient value for this abstract nil value . i.math. the Java code generated by JAXB does not reflect any of this.BigInteger must be used. from xsd:unsignedLong down to xsd:unsignedByte. and therefore this type maps to java. it has to be represented by java. hence java.. JAXB reverts to simple types. e. there is no fitting simple type.math. Exceptions result from the property nillable being set to true for an element or attribute. BigInteger integer. This adds another value to the set of possible values. long _long. . the tree branches off into a hierarchy of non-negative integers. The following schema snippet contains a selection of the types discussed so far. <xsd:complexType name="NumericZooType"> <xsd:sequence> <xsd:element name="decimal" type="xsd:decimal"/> <xsd:element name="integer" type="xsd:integer"/> <xsd:element name="long" type="xsd:long"/> <xsd:element name="int" type="xsd:int" default="42"/> <xsd:element name="short_nil" type="xsd:short" nillable="true"/> <xsd:element name="byte" type="xsd:byte" default="13" nillable="true"/> <xsd:element name="nonNegative" type="xsd:nonNegativeInteger"/> <xsd:element name="unsignedLong" type="xsd:unsignedLong"/> <xsd:element name="unsignedInt" type="xsd:unsignedInt"/> </xsd:sequence> </xsd:complexType> And here is the resulting Java code. With xsd:unsignedInt. using the smallest type capable of holding all values.. nil. the non-positive integers and the traditional line of integer types representing the typical two's complement ranges. The types long down to byte are normally mapped to Java's eponymous simple types. which still has an unspecified number of digits.BigInteger. Since xsd:nonNegativeInteger is defined as a restriction of xsd:integer. Short shortNil. indicating that the element or attribute is simply absent. int _int. Although both types can be constrained using facets to delimit the number of digits or the value range. xsd:unsignedShort and xsd:unsignedByte. short for xsd:unsignedByte.g. too. simplified for better readability. Below the integer type.arrive at xsd:integer.math.but only for descendants of Object.BigInteger.e. For xsd:unsignedLong.

// .decimal = value. of course. limiting string lengths to the range 1 to 3. JAXB simply generates the type suitable for the base type of the restriction. public BigDecimal getDecimal() { return decimal. BigInteger unsignedLong. schema designers who just want to express a simple integer counter (with a moderate upper limit) are not at all pleased when one of the "Big" types crops up in the generated Java code.counter = value.. } 2. For some element such as counter. where a simple type is defined as a restriction of the built-in type xsd:int. } Well. public int getCounter() { return counter. } public void setDecimal(BigDecimal value) { this. <xsd:element name="counter" type="CounterType"/> No separate Java class is generated for CounterType. long unsignedInt.2.. Although applications dealing with monetary quantities prosper on BigDecimal. the question is: can you retain the more convenient simple types while defining suitable value range limits? The answer is yes. BigInteger nonNegative.protected protected protected protected Byte _byte. it's quite a zoo indeed. protected int counter. <xsd:simpleType name="CounterType"> <xsd:restriction base="xsd:int"> <xsd:minInclusive value="0"/> </xsd:restriction> </xsd:simpleType> .. } public void setCounter(int value) { this. So.3 Defining a String with Length Limits The XML Schema snippet shown below defines a string type.. and it's demonstrated in the schema snippet shown below. } // All other getters and setters follow the same pattern. <xsd:simpleType name="ShortNameType"> <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> .

<xsd:simpleType name="DirType"> <xsd:restriction base="xsd:string"> <xsd:pattern value="[LR]*"/> </xsd:restriction> </xsd:simpleType> The syntax for regular expressions in pattern facets provides the basics for repetition.5 Date and Time JAXB binds all three of the schema types xsd:date.2. We'll illustrate this with a simple example for marshalling date and time. xsd:time and xsd:dateTime to XMLGregorianCalendar. Java's own java.lang. alternatives and grouping. The XML schema snippet shown below defines an element containing sub-elements with xsd:date and xsd:time. The example below defines a type for strings of arbitrary length consisting of 'L' and 'R' only. (Do not confuse this with java.util. protected XMLGregorianCalendar time. no Java class is required for DirType. But creating any of these values isn't quite so simple because XMLGregorianCalendar is an abstract class. 2.2.xml. . public XMLGregorianCalendar getDate() { return date.<xsd:maxLength value="3"/> </xsd:restriction> </xsd:simpleType> Again. It should be noted that a regular expression is always matched against the entire string value.) There is a convenient set of methods for getting at the various components such as year or day or minute. and the length restriction isn't checked unless you request it.4 Defining a String Type Restricted By Pattern A string type may also be restricted by a pattern facet. this simple type doesn't warrant a class definition of its own. Once more. 2. This class is in the package javax.GregorianCalendar.datatype.String is used. <xsd:complexType name="DateTimeType"> <xsd:sequence> <xsd:element name="Date" type="xsd:date"/> <xsd:element name="Time" type="xsd:time"/> </xsd:sequence> </xsd:complexType> The generated class contains the usual getters and setters: public class DateTimeType { protected XMLGregorianCalendar date.

SECOND ).time = value.MONTH ).YEAR ). ObjectFactory of = new ObjectFactory(). It's the class DatatypeFactory that provides the methods with which we can create the XMLGregorianCalendar objects.} public void setDate(XMLGregorianCalendar value) { this. GregorianCalendar now = new GregorianCalendar().get( Calendar. // Obtain a DatatypeFactory instance.newXMLGregorianCalendarTime( now.get( Calendar. now.newXMLGregorianCalendarDate( now.get( Calendar. XMLGregorianCalendar gcDate = df. } public void setTime(XMLGregorianCalendar value) { this. DatatypeConstants. // Create a DateTimeType element for the current time and date.get( Calendar. meta.setDate( gcDate ). You may have noticed the null argument in the method constructing an XMLGregorianCalendar with the time. It is.HOUR_OF_DAY ). XMLGregorianCalendar gcTime = df. This indicates that we don't care about fractions of seconds. } } However.MINUTE ).date = value. however. // Insert sub-elements into the DateTimeType element. // Create an XMLGregorianCalendar with the current date. some work remains to be done before we can call either setter.newInstance().FIELD_UNDEFINED ). DatatypeFactory df = DatatypeFactory.createDateTimeType(). // Create an XMLGregorianCalendar with the current time. meta. now. null.FIELD_UNDEFINED ). The XML element produced by this code will look like this: . not possible to omit seconds entirely.get( Calendar. now. DateTimeType meta = of. now.setTime( gcTime ).get( Calendar.DAY_OF_MONTH ). // no fraction DatatypeConstants. } public XMLGregorianCalendar getTime() { return time.

7 Defining a List of Integers To obtain a simple type that can be used for XML element values as well as for attribute values consisting of a simple series of values. A sample schema declaration is shown below. for inclusion in an XML file.data = ((byte[]) value).<DateTime> <Date>2008-07-23</Date> <Time>18:42:24</Time> </DateTime> You should notice that the date and time representations follow ISO 8601. use an xsd:list. All conversions are handled by JAXB. <xsd:simpleType name="NumberListType"> <xsd:list itemType="xsd:int"/> </xsd:simpleType> The Java type used for this schema type will be List<Integer>.2. Its type and the type for passing the binary data is byte[]. Using NumberListType as an attribute . 2. The XML Schema datatype to use in this case is xsd:hexBinary.6 Binary Data Data that has no "natural" representation with printable characters must.2. } } 2. The simple technique for this consists in converting the binary byte values to their hexadecimal representations. public byte[] getData() { return data. so again no Java class has to be generated for this simple type. } public void setData(byte[] value) { this. public class BinaryType { protected byte[] data. as shown below. <xsd:complexType name="BinaryType"> <xsd:sequence> <xsd:element name="data" type="xsd:hexBinary"/> </xsd:sequence> </xsd:complexType> The Java class produced by JAXB contains a convenient pair of getter and setter methods for accessing the instance variable (called data) that stores the binary data. still be represented in printable characters.

2. The XML representation would be a list of values of that type."/>.2. ..dangerous! --> </xsd:simpleType> To be on the safe side. 2.9 Defining an Enumeration If you want a data type that enumerates discrete values you should use a restriction of the schema type xsd:string. don't use anything like <xsd:simpleType name="StringListType"> <xsd:list itemType="xsd:string"/> <!-. } // . <xsd:simpleType name="IXLType"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="eStwA"/> <xsd:enumeration value="eStwS"/> <xsd:enumeration value="SpDrL"/> <xsd:enumeration value="SpDrS"/> <xsd:enumeration value="VGS80"/> </xsd:restriction> </xsd:simpleType> The JAXB compiler generates a Java enum. There is no corresponding setter which means that all additions or deletions of list elements have to be made on the "live" list.. public List<Integer> getNumbers() { if (numbers == null) { numbers = new ArrayList<Integer>(). separated by white space. enumerating all the values as you would in a Java enum type.. Below is the (somewhat shortened) Java code.. use a complex type that contains a sequence of string elements.numbers. And right here is a potential catch: what if one of these values contains a blank? Therefore..8 Defining Other Lists You can use any other atomic simple type definition or built-in primitive datatype in <xsd:list itemType=". protected List<Integer> numbers. } The code in the getter method ensures that the List<Integer> is created.. } return this. unless you can be very sure that your strings are free from spaces or any other white space.2. but the names of the enum constants are transformed so that they conform to the style commonly accepted in the Java community.. // .or child type results in an instance variable and a getter method in the parent class: public class ListsType { // ..

VGS_80("VGS80"). } public String value() { return value. </xsd:restriction> </xsd:simpleType> The generated enum class will now contain enum constant names that exactly match the original strings. private final String value.. you may resort to an explicit specification of the binding. and method value may now simply call name() to obtain the stringified . as shown below. SP_DR_S("SpDrS"). E_STW_S("eStwS"). eStwS. SP_DR_L("SpDrL"). <xsd:simpleType name="IXLType"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="eStwA"/> <xsd:annotation><xsd:appinfo> <jxb:typesafeEnumMember name="eStwA"/> </xsd:appinfo></xsd:annotation> . IXLType(String v) { value = v. public String value() { return name(). SpDrL. VGS80. } . public enum IXLType { eStwA. for each enum constant name... } There is no need now to store the XML representations along with each enum constant.public enum IXLType { E_STW_A("eStwA"). } } If you want to use the original identifiers as enum constant names.. SpDrS.

2. 2. public class RouteType { protected Integer pos. <xsd:complexType name="RouteType"> <xsd:attribute name="Pos" type="xsd:int" use="optional" default="1"/> <xsd:attribute name="Dir" type="DirType" use="required"/> </xsd:complexType> The compiler generates a class RouteType with getters and setters for the attributes. } else { return pos. there is no convenient way of expressing unions of simple types. even if they do not have content. 2. <xsd:simpleType name="SpeedOrNumberType"> <xsd:union> <xsd:simpleType> <xsd:restriction base="xsd:int"> </xsd:restriction> </xsd:simpleType> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:pattern value="+?d+"/> </xsd:restriction> </xsd:simpleType> </xsd:union> </xsd:simpleType> In Java. The JAXB compiler simply inserts Java's String type wherever the union type is used and leaves it up to the application programmer to handle the rest.pos = value.11 Defining Types for XML Elements Without Content Types for XML elements are constructed using xsd:complexType. public int getPos() { if (pos == null) { return 1. protected String dir. Try to avoid xsd:union. The snippet below defines a simple element with two attributes and no sub-elements. .value. } } public void setPos(Integer value) { this.2.10 Defining a Type Union A simple type may also be constructed as a union of two or more simple types.

The xsd:element defines the XML tag.. } public void setDir(String value) { this. and it consists of the declaration of an instance variable.12 Defining Types for XML Elements With Content 2. Let's look at an XML element with a value of some type. except for list types. simply because there is no such element. //. Method getPos takes care of supplying the default value if the variable is null.dir = value. This is defined by a schema construct like this: <xsd:element name="Quantity" type="xsd:int"/> This does not define another type... such an element cannot be part of yet another type definition describing the structure of an enclosing element. } } The absence of a value for the optional attribute Pos is represented by an object where the instance variable pos remains at null. An element definition like this may also be provided for specifying the root element of an XML document. a getter method (here: int getQuantity()) and. a setter method (here: void setQuantity(int value)). So. or even a combination of both. Obviously. or one or more subordinate elements. i. this element itself and its siblings. the one describing the containing element.} public String getDir() { return dir. so that an example of this XML element is bound to look like this: <Quantity>144</Quantity> The Java code resulting from such an embedded element definition is part of some class definition. from any stand-alone element definition that looks like this <xsd:element name="Doc" type="DocType"/> you may expect the generated class ObjectFactory to contain public class ObjectFactory { private final static QName _Doc_QNAME = new QName("". 2. "Doc").2. but it may occur as some part of a complex type definition that describes the structure and attributes of the containing element. The code generated for a stand-alone element definition can be found in the class ObjectFactory which is generated along with all the classes derived from your schema's type definitions.12.2. public JAXBElement<DocType> createDoc(DocType value) { .1 Content: A Value The content of an XML element may be some value.e.

null.12..2 Content: An Ordered Set of Elements The schema element xsd:sequence defines that the enclosed set of elements should occur in the given order and according to the specified minimum and maximum repetition counts..y = value.) The following complex type defines a set of two coordinates. <xsd:complexType name="PointType"> <xsd:sequence> <xsd:element name="X" type="xsd:int"/> <xsd:element name="Y" type="xsd:int"/> </xsd:sequence> </xsd:complexType> The resulting Java code is straightforward.2. public int getX() { return x.3 Content: An Unordered Set of Elements Content consisting of a set of elements that may occur in any order within its parent . DocType. value). } public int getY() { return y. } (We'll have a closer look at the other methods in this factory class in the section The Object Factory.return new JAXBElement<DocType>(_Doc_QNAME. public class PointType { protected int x. The following subsections describe the structuring facilities of the XML Schema language for defining element content. (The default for both is 1.x = value.12. 2.class. } } 2.2. } public void setY(int value) { this. } public void setX(int value) { this.) Notice that you are not restricted to a single document root element. } // . protected int y.

2. soup. a severe restriction: the maxOccurs may not have a value greater than 1. but you may omit all courses except for the main dish. the getters for the optional child elements may return null to distinguish "not present" from any possible value. <xsd:complexType name="DinnerType"> <xsd:all> <xsd:element name="Starter" type="xsd:string" minOccurs="0"/> <xsd:element name="Soup" type="xsd:string" minOccurs="0"/> <xsd:element name="Entree" type="xsd:string"/> <xsd:element name="Dessert" type="xsd:string" minOccurs="0"/> </xsd:all> </xsd:complexType> The generated Java conforms to the structure of a JavaBean: public class LunchType { protected protected protected protected String String String String starter. however.XML element can be defined by using the schema element xsd:all. public String getStarter() { return starter.2. } public void setStarter( String value ) { this..(more getters and setters) } Here. entree. <xsd:complexType name="CommType"> <xsd:choice> <xsd:element name="SMS" type="xsd:string"/> <xsd:element name="MMS" type="xsd:string"/> <xsd:element name="Email" type="xsd:string"/> </xsd:choice> </xsd:complexType> Although only one out of the three elements will actually be present. Here is the definition for an XML element describing the courses of a dinner which does not permit repetitions of any course..12.starter = value. the generated Java class provides instance variables and getters and setters for all alternatives.4 Content: Alternative Elements The schema element xsd:choice lets you define a type for an XML element which has a content of exactly one element from a given set of alternatives. dessert. . There is. } // .

Object oriented languages have no unions because a set of alternative structures is meant to be implemented by a set of subclasses. we make use of the optional attributes minOccurs and maxOccurs. nothing in the generated code that will keep you from calling more than one setter. public class PolygonType { protected List<PointType> points. or a fixed number. may contain any number of elements. The definition of an unbounded list with at least two elements is given below..) <xsd:complexType name="PolygonType"> <xsd:sequence> <xsd:element name="Points" type="PointType" minOccurs="2" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> The resulting Java code does not express the required minimum of two points in a polygon. a java. (PointType is shown in subsection Content: An Ordered Set of Elements. Therefore the generated code will always be as simple as the one shown below. } // . protected String mms.2.(more getters and setters) } Although a handful of unused references isn't all that expensive. Various combinations are possible. public String getSMS() { return sms. and for all similar element lists. 2. Also. There is.util.12. using such a class may easily lead to errors that are hard to track down. protected String email. public List<PointType> getPoints() { if (points == null) { . permitting the definition of a list that may be empty.public class CommType { protected String sms.. Here. } public void setSMS(String value) { this. for instance.sms = value. This topic is discussed in the section Defining Subtypes.5 Content: A Homogeneous List of Elements To define an element where some sub-element occurs repeatedly. a Java class like this just doesn't have a nice feeling about it.List is used.

lang. 2. therefore. public class MixType { protected List<Object> textOrNumberOrPoint.2. and you could remove or even clear to delete elements.util. Other possibilities are java.Object will do.6 Content: A Mixed List of Elements To define an element type where the element should have a content consisting of a mixed list of elements use the schema element xsd:choice with the attribute maxOccurs="unbounded" or some value greater than 1.12. } } Note well that this technique does not retain an indication of the XML tag in the objects created during unmarshalling as long as the types of the choices are distinct.List may be applied to the returned value.Serializable.points = new ArrayList<PointType>(). The list can be added to one by one. adds another point. Sometimes only java.points. With all of these possibilities there is just no need for a setter for the entire list. } return this. } } The Javadoc documentation (omitted here) emphasizes that getPoints returns a reference to the actual list while making sure that the list is created.Most importantly. or you may use addAll for bulk additions. 9 ) ).add( new PointType( 4. . public List<Object> getTextOrNumberOrPoint() { if (textOrNumberOrPoint == null) { textOrNumberOrPoint = new ArrayList<Object>().getPoints(). the generic parameter of the List object must refer to some superclass of all the element types. Obviously.textOrNumberOrPoint.) <xsd:complexType name="MixType"> <xsd:choice maxOccurs="unbounded"> <xsd:element name="Text" type="xsd:string"/> <xsd:element name="Number" type="xsd:int"/> <xsd:element name="Point" type="PointType"/> </xsd:choice> </xsd:complexType> The generated Java class has an instance variable for a mixed list of such elements. or a user-defined type from which all the types in the choice set have been derived by subclassing. } return this. (Using xsd:choice as the sole element within a xsd:sequence would result in the same structure definition and. code like this polygon. in the same Java code.lang. All methods defined in java.

type xsd:string.g. cast o to String and process } else if( o instanceof Integer ){ // . cast o to Point and process } else { throw new IllegalArgumentException( "class " + o..JAXBElement as a container for each of the elements within MixType.bind. cast o to Integer and process } else if( o instanceof Point ){ // . For one thing.getClass() ). } . after the third sub-element. mercifully. The preferred implementation technique is to map element classes to distinct objects created from subclasses of some element handler class hierarchy... Also. the instanceof test avoids the compiler warning.) public class Mix4Type { protected List<JAXBElement<?>> textOrNumberOrPoint.. If we add another element of... the schema definition might then look like this: <xsd:complexType name="Mix4Type"> <xsd:choice maxOccurs="unbounded"> <xsd:element name="Text" type="xsd:string"/> <xsd:element name="Number" type="xsd:int"/> <xsd:element name="Point" type="PointType"/> <xsd:element name="Token" type="xsd:string"/> </xsd:choice> </xsd:complexType> Now the JAXB compiler is forced to use an artificial construct of type javax. (Notice that the agglomeation of the list field's name stops.: for( Object o: mix.getTextOrNumberOrPoint() ){ if( o instanceof String ){ // . The class Mix4Type reflects this by the generic list type being <JAXBElement<?>>.xml.You must distinguish individual elements by testing a list element with the instanceof operator. Section Using the Element Tree contains a detailed example illustrating this approach. say. we can produce a more significant error message in the exception we throw in the final else branch. public List<JAXBElement<?>> getTextOrNumberOrPoint() { if (textOrNumberOrPoint == null) { textOrNumberOrPoint = new ArrayList<JAXBElement<?>>(). } } It's a good idea to use a third test to guard against the class not being one of the three expected ones. e. Writing lengthy if statement cascades like this isn't considered to be good object oriented style. even though a failure of the cast would show that something went wrong.

where parts of a paragraph's text value might have some specific property such as boldface or italic.return this. (process) } else if( //. we define a schema for our very simple text markup language. Here is an example written in some simple markup similar to HTML: <P> <B>Mixed content</B> lets you embed <I>child elements</I> into the value of an element.2..equals( Tag ) ){ Integer number = (Integer)je. if( "Text". <xsd:complexType name="ChunkType" mixed="true"> <xsd:choice maxOccurs="unbounded"> <xsd:element name="B" type="ChunkType"/> <xsd:element name="I" type="ChunkType"/> <xsd:element name="U" type="ChunkType"/> </xsd:choice> </xsd:complexType> . and an unbounded repetition of choices as child elements.. in italics or underlined.. The complex type ChunkType has its attribute mixed set to true since we'll want to have plain text as well.getName(). These stretches are best represented as children of the paragraph element.. where the tag and the value are retrieved from the container of type JAXBElement<?>. // . to be rendered in boldface. a pass through the list would have to be changed as shown below..7 Mixed Content Mixed content lets you embed child elements into the value of an element. See section Using the Element Tree for a better way of dealing with tags to distinguish between elements. (process) } else if( "Number".. </P> To see how JAXB handles mixed content.. // ..getValue(). (other alternatives) } } Again.getLocalPart(). One example for the natural application of mixed content would be the representation of text.getValue(). } } Consequently.getTextOrNumberOrPoint() ){ String tag = je. the cascading if statements aren't exactly the bee's knees. 2. We'll have chunks of text that may be used as an entire paragraph as well as part of a paragraph. for( JAXBElement je: mix.textOrNumberOrPoint.equals( Tag ) ){ String text = (String)je. // .12.

ChunkType chunk = (ChunkType)((JAXBElement)s).print( (String)s ). public List<Serializable> getContent() { if (content == null) { content = new ArrayList<Serializable>(). System.content. I and U.print( ":" + tag + ")" ). } return this.getContent() ){ if( s instanceof String ){ System. } } The documentation JAXB generates is kind enough to inform us that the elements in the list returned by getContent are either of type String or of type JAXBElement<ChunkType>. public List<ChunkType> getP() { if (p == null) { p = new ArrayList<ChunkType>(). The generic list type now happens to be java. this is the wrapper class JAXB uses whenever elements have to be distinguished by their tags.Serializable. private static void dumpChunk( ChunkType c ){ for( Serializable s: c.getValue(). we did use ChunkType with B. dumpChunk( chunk ). Having penetrated this slight obfuscation.out.<xsd:complexType name="TextType"> <xsd:sequence> <xsd:element name="P" type="ChunkType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> The generated Java code is somewhat opaque. public class TextType { protected List<ChunkType> p. and. apparently the Swiss army knife for slicing a chunk of text. The content list of a text chunk yields plain and decorated chunks in any order. which is just another way of saying "(almost) anything goes".getName().p.print( "(" + tag + ":" ). } .lang. } } public class ChunkType { protected List<Serializable> content.out. System.getLocalPart(). As we already know. } else { String tag = ((JAXBElement)s). indeed.out. } return this. as ChunkType features just one method getContent. we can now write code to process a text as a list of paragraphs.

. JAXB distinguishes between the three representations by attaching suitable annotations. which can not be omitted. using the empty string as an indication for the absence of a value is. Let's look at the complex type defined like this: <xsd:complexType name="DemoType"> <xsd:sequence> <xsd:element name="A" type="xsd:string"/> <xsd:element name="B" type="xsd:string" minOccurs="0"/> <xsd:element name="C" type="xsd:string" nillable="true"/> </xsd:sequence> </xsd:complexType> Element <A> must be present. Although we are going to discuss annotations in more detail later on..org/2001/XMLSchema-instance.. @XmlElement(name = "C". not a good idea. even though its value could be the empty string. required = true.no element <B> here --> <C xsi:nil="true"/> </demo> The declarations.} } //. in general.8 No Value XML can express the absence of a value in different ways. A better solution is provided by the definition of element <B>. @XmlElement(name = "B") protected String b.) <demo> <A></A> <!-.getP() ){ dumpChunk( c ). but its attribute nillable="true" permits the usage of an XML element that doesn't even contain the empty string but uses the attribute xsi:nil. in accordance with the attribute minOccurs="0".12. Yet another possibility is shown with element <C>.w3. where its absence can be expressed by simply omitting it from its parent element. . required = true) protected String a. However. public class DemoType { @XmlElement(name = "A". } 2.(process a text) TextType text = .. as shown in this valid example for a DemoType element: (The prefix xsi must be bound to http://www. for( ChunkType c: text. the characterless thing.. and the getters and setters for all three fields are identical. we'll have a peek at the crucial ones right now. nillable = true) protected String c.2.

} // . (more getters and setters like this) } 2. The example given below presents the components for defining a simple menu (this time it's for a graphical user interface) where menu entries may come in several flavours: simple items. radio buttons and sub-menus.2. This is based on the schema element xsd:extension which lets you add both child elements and attributes to some elsewhere defined type acting as the base type. <xsd:complexType name="EntryType"> <xsd:attribute name="Text" type="xsd:string"/> </xsd:complexType> <xsd:complexType name="ItemType"> <xsd:complexContent> <xsd:extension base="EntryType"> <xsd:sequence> <xsd:element name="Command" type="xsd:string"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="CheckBoxType"> <xsd:complexContent> <xsd:extension base="ItemType"> <xsd:attribute name="State" type="xsd:boolean"/> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="RadioButtonType"> <xsd:complexContent> <xsd:extension base="ItemType"> <xsd:attribute name="Group" type="xsd:string"/> <xsd:attribute name="State" type="xsd:boolean"/> <xsd:attribute name="Value" type="xsd:string"/> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="MenuType"> . it's still possible to apply the fundamental OO paradigm when designing a schema: inheritance.13 Defining Subtypes Although object orientation isn't a key feature of XML or the XML Schema language. } public void setA(String value) { this...public String getA() { return a. check boxes.a = value.

// . public class EntryType { protected String text..CheckBoxType extends ItemType. again adding some attributes.ItemType adds a command definition to the base type. -.<xsd:complexContent> <xsd:extension base="EntryType"> <xsd:choice maxOccurs="unbounded"> <xsd:element name="Item" type="ItemType"/> <xsd:element name="CheckBox" type="CheckBoxType"/> <xsd:element name="RadioButton" type="RadioButtonType"/> <xsd:element name="Menu" type="MenuType"/> </xsd:choice> </xsd:extension> </xsd:complexContent> </xsd:complexType> The base class EntryType is extended in several ways: -. // . rewards you with a set of class definitions that uses extends wherever we have xsd:extension in the schema. setCommand) } public class CheckBoxType extends ItemType { protected Boolean state.MenuType reflects the recursive structure of menus by being both another subclass of ItemType (so that it may represent cascades) as well as a container for all kinds of menu entries.. A look at the (much abbreviated) code shows the expected inheritance structure. // . setState) } public class RadioButtonType extends ItemType { . setText) } public class ItemType extends EntryType { protected String command.RadioButtonType is another extension of ItemType.(getCommand. Before we look at the generated Java code.. however. we should note that the definition of MenuType isn't quite what an OO aficionado would expect.(getText. one still must explicitly put all the subclasses into the choice list.. The JAXB compiler.. Group is the button group's identification.(isState. -. including itself. -. inheriting the command and adding an attribute for the initial state of the check box. Using just the supertype EntryType in an xsd:sequence would result in very dull menus. and Value defines the string to be used for indicating the selection.. After all the pains taken to establish this little class hierarchy.

// . public class MenuType extends EntryType { protected List<EntryType> itemOrCheckBoxOrRadioButton. The substitution group is headed by the global operand element.2. reverse engineered the common superclass. } return this. <xsd:complexType name="BinopType"> <xsd:sequence> <xsd:element ref="operand"/> <xsd:element ref="operand"/> </xsd:sequence> <xsd:attribute name="operator" type="xsd:string"/> </xsd:complexType> <xsd:element name="operand" type="xsd:string"/> <xsd:element name="constant" type="xsd:string" substitutionGroup="operand"/> <xsd:element name="variable" type="xsd:string" substitutionGroup="operand"/> <xsd:element name="binop" type="BinopType"/> The benefit of this schema definition is that it permits you to create binop elements consisting of any combination of constant and variable elements.protected String group. public class BinopType { protected List<JAXBElement<String>> content.14 Substitution Groups A substitution group lets you write schema structures that reference one element but permit the substitution of any other element from the substitution group in an instance document.(getters and setters) } Finally there is MenuType.itemOrCheckBoxOrRadioButton. The generated Java code shouldn't surprise you. public List<EntryType> getItemOrCheckBoxOrRadioButton() { if (itemOrCheckBoxOrRadioButton == null) { itemOrCheckBoxOrRadioButton = new ArrayList<EntryType>(). protected String value.List<EntryType>. } } 2.. literally. protected Boolean state. A reminder that the list is a mixture is embedded in the name of the getter which is made up from the first three tags. Below is a simple example. which contains a java..util. JAXB has briefly reflected upon the element types bunched into the choice and has. the field content must act as a portmanteau for all possible operand pairs. and that's why we have to be content with a list. . protected String operator. defining a complex type for a binary arithmetic operation. which is referenced from the group members constant and variable.

which should be expressed by the attribute setting abstract="true".out ). is conceptually an abstract type. BinopType bt = of. true ).operator = value. } public void setOperator(String value) { this. } public String getOperator() { return operator.content.createBinop( bt ). This is what we have in the example. The elements of the group may have different types.marshal( jbe.add( op2 ). A typical scenario would be the use of a base type in the head element and various extensions for the other elements. JAXBElement<String> op2 = of.createMarshaller(). either by restriction or by extension. JAXBElement<BinopType> jbe = of.setProperty( Marshaller. } } Creating an element from a substitution group is slightly more complex now because such elements have to be represented by an object from some parameterized JAXBElement<?> class. bt.getContent().14" ).add( op1 ). however. JAXBElement<String> op1 = of.14</constant> <variable>d</variable> </binop> Another example illustrates the usage of a substitution group with complex schema types.public List<JAXBElement<String>> getContent() { if (content == null) { content = new ArrayList<JAXBElement<String>>(). .newInstance( "generated" ).getContent().0" encoding="UTF-8" standalone="yes"?> <binop operator="*"> <constant>3.createVariable( "d" ). but they must be derived from the same base type. m. Marshaller m = ctxt. It is defined as containing one element of ItemType. ObjectFactory of = new ObjectFactory().setOperator( "*" ). bt.createConstant( "3. bt.createBinopType(). And here is the resulting instance document: <?xml version="1. } return this. JAXBContext ctxt = JAXBContext. where ItemType is the base type and BookType and DiskType are the subtypes. System. This type.JAXB_FORMATTED_OUTPUT. This is illustrated in the Java code snippet shown below that demonstrates the assembly of a well-known formula. A PosType element represents a position in an order. m.

org/2001/XMLSchema" xmlns:jaxb="http://java.sun.item"/> </jaxb:schemaBindings> </xs:appinfo> </xs:annotation> <xs:element name="item" type="ItemType"/> <xs:element name="book" type="BookType" substitutionGroup="item"/> <xs:element name="disk" type="DiskType" substitutionGroup="item"/> <xs:complexType name="ItemType" abstract="true"> <xs:sequence> <xs:element name="title" type="xs:string"/> <xs:element name="price" type="xs:int"/> </xs:sequence> </xs:complexType> <xs:complexType name="BookType"> <xs:complexContent> <xs:extension base="ItemType"> <xs:sequence> <xs:element name="pages" type="xs:int"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> <xs:complexType name="DiskType"> <xs:complexContent> <xs:extension base="ItemType"> <xs:sequence> <xs:element name="duration" type="xs:int"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> <xs:complexType name="PosType"> <xs:sequence> <xs:element ref="item"/> <xs:element name="quantity" type="xs:int"/> </xs:sequence> </xs:complexType> <xs:complexType name="OrderType"> <xs:sequence> .0"> <xs:annotation> <xs:appinfo> <jaxb:schemaBindings> <jaxb:package name="acme.<?xml version="1.com/xml/ns/jaxb" jaxb:version="2.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.

protected int quantity. Also. where the wildcard ? is suitably restricted to subtypes of ItemType.. And finally there is createItem.item = ((JAXBElement<? extends ItemType> ) value). } public void setItem(JAXBElement<? extends ItemType> value) { this. // . and its use as the generic type parameter. (getters and setters) } public class PosType { protected JAXBElement<? extends ItemType> item. There are methods returning elements of one of the plain types BookType and DiskType. returning an object whose type is ItemType. Here is the skeleton of this class: . (getters and setters) } public class BookType extends ItemType { protected int pages. // . protected int price. public JAXBElement<? extends ItemType> getItem() { return item... The ObjectFactory provides create methods for a surprisingly large number of elements. (getters and setters) } public class DiskType extends ItemType { protected int duration. parameterized with BookType or DiskType. // .<xs:element name="pos" type="PosType" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:element name="order" type="OrderType"/> </xs:schema> The interesting sections of the generated code are outlined below.... each of which requires an argument of the parameter type. public abstract class ItemType { protected String title.. (more getters and setters) } Once again. we can create an element by calling a method that returns an object of type JAXBElement. We see the abstract base class ItemType with its extensions for books and disks. } // .. element construction is a tad more complicated.

createOrderType().. listPos... DiskType dk = of.setQuantity( 1 ). } public DiskType createDiskType() { . PosType p2 = of. bk.add( p2 ).createItem( bk ) ). } public OrderType createOrderType() { .setQuantity( 2 ). BookType bk = of. .setPrice( 20 )...createDisk( dk ) ). dk. bk. // createDisk p2.public class ObjectFactory { public ObjectFactory() { } public BookType createBookType() { ..createPosType(). } public JAXBElement<ItemType> createItem(ItemType value) { . Some experimenting exhibits that indeed all three can be used: ObjectFactory of = new ObjectFactory().. } public JAXBElement<BookType> createBook(BookType value) { .. PosType p1 = of.setItem( of.setTitle( "The Joy of JAXB" ). List<PosType> listPos = st. } } The table below shows where each of these lements can be used. p1.. // Order two copies of a book. } public JAXBElement<OrderType> createOrder(OrderType value) { .. // createItem for BookType p1.setItem() Looking at this table. } public JAXBElement<DiskType> createDisk(DiskType value) { .setDuration( 50 ). Method createBookType createDiskType createBook createDisk createItem Result Type BookType DiskType JAXBElement<BookType> JAXBElement<DiskType> JAXBElement<ItemType> Use as argument of createBook() createDisk() PosType. bk..add( p1 ).setPrice( 120 ).....setItem() PosType.. // Order a disk.createDiskType(). dk.setItem( of. dk. p2.createPosType(). you may wonder why there are three methods to create an item in a PosType element.createBookType(). listPos.setTitle( "Keyclick Calypso" ). // Create an order OrderType st = of. } public PosType createPosType() { .setItem() PosType.setPages( 832 ).getPos().

JAXBElement<?> jbe = (JAXBElement<?>)u. In spite of the restrictions and the slightly more complex element construction.xml.w3.getQuantity() ).getSimpleName() ).getItem(). System.xml" ) ).println( tag + " " + item.out.getValue(). along with the lengthy namespace declaration.getTitle() + " " + p.JAXBElement<OrderType> jbe = of. System.QName which contains the simple name as well as the namespace prefix.println( item.getName(). substitution groups are an adequate technique for representing object hierarchies.namespace.getItem(). } In addition to using the standard Java technique for determining an object's class we can also extract the tag by calling method getName() on the JAXBElement containing the ItemType object.getValue(). The marshalled XML text shows that the generic element tag item can indeed be instantiated (even though its schema type ItemType is abstract) but at a price: The actual type of the element has to be specified using the XML instance attribute xsi:type="BookType".getPos() ){ ItemType item = p.getClass(). The tag is represented as an object of class javax.0" encoding="UTF-8" standalone="yes"?> <order> <pos> <item xmlns:xsi="http://www. .org/2001/XMLSchema-instance" xsi:type="BookType"> <title>Inside JAXB</title> <price>120</price> <pages>832</pages> </item> <quantity>2</quantity> </pos> <pos> <disk> <title>Keyclick Calypso</title> <price>20</price> <duration>50</duration> </disk> <quantity>1</quantity> </pos> </order> Unmarshalling requires an additional call to get at the value wrapped in a JAXBElement<? extends ItemType>. for( PosType p: order.createOrder( st ).getLocalPart(). The subtype element tagged disk does not require this burden as its tag is unambiguous. String tag = p.out. but common subelements can be accessed via calls of ItemType methods.unmarshal( new FileInputStream( "order. OrderType order = (OrderType)jbe. <?xml version="1.

e. This can be put to good use in several circumstances. we'll now change our schema to employ element linkage. <xsd:complexType name="AirportType"> <xsd:attribute name="LocId" type="xsd:ID" use="required"/> <xsd:attribute name="Name" type="xsd:string" use="required"/> </xsd:complexType> <xsd:complexType name="FlightType"> <xsd:all> <xsd:element name="From" type="xsd:IDREF"/> <xsd:element name="To" type="xsd:IDREF"/> <xsd:element name="Carrier" type="xsd:string"/> <xsd:element name="DepTime" type="xsd:time"/> <xsd:element name="ArrTime" type="xsd:time"/> </xsd:all> <xsd:attribute name="Number" type="xsd:int" use="required"/> </xsd:complexType> <xsd:complexType name="TimetableType"> . An AirportType element is presented only once.2. in full.2. Our first example uses references for factoring out frequently occuring elements. bundling the actual AirportType elements and the list of flights. A naive schema definition would simply have two AirportType sub-elements for each flight: <xsd:complexType name="AirportType"> <xsd:attribute name="LocId" type="xsd:string" use="required"/> <xsd:attribute name="Name" type="xsd:string" use="required"/> </xsd:complexType> <xsd:complexType name="FlightType"> <xsd:all> <xsd:element name="From" type="AirportType"/> <xsd:element name="To" type="AirportType"/> <xsd:element name="Carrier" type="xsd:string"/> <xsd:element name="DepTime" type="xsd:time"/> <xsd:element name="ArrTime" type="xsd:time"/> </xsd:all> <xsd:attribute name="Number" type="xsd:int" use="required"/> </xsd:complexType> Instead of copying an element of class AirportType (biggish. whenever you need linkage in addition to the natural parent-tochild relationship. Our document type should be defined along the lines of TimetableType. aren't they) into all places where it is used. They let you represent references to XML elements. and a reference is inserted for the From and To sub-elements of FlightType where the original element was. Below is a schema snippet defining XML elements dealing with airports and flights. which are scheduled from one airport to another one. i..15 Referring to Another XML Element Among the data types of the XML Schema language there is an inseparable pair of types operating complementary to each other: xsd:ID and xsd:IDREF.

} public Object getTo() { return to.from = value. as the string implementing the XML link.getFrom() The destination's IATA Location Identifier is obtained by ((AirportType)flight. More interesting is the code for the class FlightType: public class FlightType { protected protected protected protected protected protected Object from. to retrieve the origin of some flight. } // . all you'll have to code is (AirportType)flight.to = value. XMLGregorianCalendar arrTime. which we would have used as an airport identification anyway.getTo()). Otherwise you'll just have to use some synthetic key. public Object getFrom() { return from. So. XMLGregorianCalendar depTime..) The resulting Java code for AirportType has the usual JavaBean layout.(more getters and setters) } The elements From and To are now represented as Object references. } public void setTo(Object value) { this. and FlightType has xsd:IDREF as the type for From and To. String carrier. int number. it may very well be possible to compose one from the element's other attributes.. (If there is no attribute that could serve as an identification right away. } public void setFrom(Object value) { this. We'll continue to use the IATA Location Identifier.getLocId() Don't blame JAXB for not making the From and To sub-elements AirportType . Object to.<xsd:sequence> <xsd:element name="Airports" type="AirportType" maxOccurs="unbounded"/> <xsd:element name="Flight" type="FlightType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> The only change required within AirportType is the definition of the attribute Id as xsd:ID.

graphs. Another excellent reason for using references is the representation of linked data structures such as trees. saving you the hassle of establishing this linkage yourself. The example given below is for railway buffs. unmarshalling will automatically create FlightType objects that are actually linked to their airports. There is a good chance that location identifiers and flight identifiers (a concatenation of the carrier id and some number) don't clash. As soon as we begin to think about adding bookings to our XML data. lists or. It demonstrates how a track layout can be represented by linking elements such as sets of points (or switches) and tracks to each other. Notice that by dropping the necessity to have a full-blown XML element for From and To. in general. flight identifiers would have to make their appearance as another class of values for xsd:ID. Nevertheless. but you'd better research this thoroughly before you commit yourself. we could now define this value pair as a couple of attributes.) <xsd:simpleType name="GroupType"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="SWITCH"/> <xsd:enumeration value="TRACK"/> </xsd:restriction> </xsd:simpleType> <xsd:complexType name="ElementType"> <xsd:attribute name="Id" type="xsd:ID" use="required"/> <xsd:attribute name="Group" type="GroupType" use="required"/> <xsd:attribute name="Number" type="xsd:int" use="required"/> <xsd:attribute name="Name" type="xsd:string" use="optional" default=""/> </xsd:complexType> <xsd:complexType name="PointLeftRightType"> <xsd:complexContent> <xsd:extension base="ElementType"> <xsd:attribute name="point" type="xsd:IDREF"/> <xsd:attribute name="left" type="xsd:IDREF"/> <xsd:attribute name="right" type="xsd:IDREF"/> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="EastWestType"> <xsd:complexContent> <xsd:extension base="ElementType"> <xsd:attribute name="east" type="xsd:IDREF"/> <xsd:attribute name="west" type="xsd:IDREF"/> </xsd:extension> . the ones of xsd:IDREF) to be unique across all of your XML document. same thing. and xsd:IDREF is the union of all reference values. The XML type xsd:ID is a universal reference type. Keep in mind that XML requires the values of xsd:ID (or.references. (Signals are omitted for brevity's sake. creating the graph that represents the topology of a shunting yard.

Simply using "null" or "" as an IDREF value will cause problems as soon as the XML is validated. Again. } public void setEast(Object value) { this. perhaps in a category of its own. line tracks? We'll need some sort of replacement for Java's null. One solution that avoids this ambiguity is to use a single artificial element. protected Object west. we select EastWestType for a closer inspection.what do we do with dead-end tracks? Or with tracks that lead out of the shunting yard. } public Object getWest() { return west. One solution would be to define all the link attributes as optional. as the "null" element. public class EastWestType extends ElementType { protected Object east..west = value. i. there is Object as the type used in the getters and setters for the attributes linking to the neighbours. } public void setWest(Object value) { this. public Object getEast() { return east. because. by definition. } } But wait . but this makes it difficult to discriminate an inadvertently dropped element from an intentionally omitted one.e. We extend ShuntingYardType accordingly: <xsd:complexType name="NullType"> <xsd:attribute name="Id" type="xsd:ID" use="required"/> </xsd:complexType> <xsd:complexType name="ShuntingYardType"> <xsd:choice maxOccurs="unbounded"> <xsd:element name="Switch" type="PointLeftRightType"/> <xsd:element name="Track" type="EastWestType"/> <xsd:element name="Null" type="NullType"/> </xsd:choice> .</xsd:complexContent> </xsd:complexType> <xsd:complexType name="ShuntingYardType"> <xsd:choice maxOccurs="unbounded"> <xsd:element name="Switch" type="PointLeftRightType"/> <xsd:element name="Track" type="EastWestType"/> </xsd:choice> </xsd:complexType> From the generated classes. there must be some element where that string is an id value.east = value.

provides a null element that is comfortably distinguishable from all the actual trackside equipment by class as well as by its Id value. <Track Id="TRACK_168" Group="TRACK" Number="168" Name="b101" east="SWITCH_42" west="null"/> <Null Id="null" Group="NULL" Number="0"/> The generic element attributes Group and Number could be set to arbitrary values. In the XML file you would have one extra element..16.lang.if not java. but we might just as well use some null values there. i. Its name is distinction enough.</xsd:complexType> This will give you a class NullType. this is no typesetting accident: this class is indeed empty because it doesn't need any additions to its base class.16 Elements With Any Type 2.. } public void setContent(Object value) { this.content = value. public Object getContent() { return content.2. <xsd:complexType name="BagType"> <xsd:sequence> <xsd:element name="Content" type="xsd:anyType"/> </xsd:sequence> </xsd:complexType> The class that is generated by JAXB shouldn't come as a surprise: public class BagType { protected Object content.2. and one element of that type with an arbitrary Id value . too. } } But what will be the class of the Content . 2.perhaps Id="null" . To see how this is handled in JAXB.lang.Object (which would be . e.g. the Null element as shown below.Object. we define the complex type BagType which is nothing but a wrapper for any content. Here is the Java code JAXB generates for it: public class NullType extends ElementType { } No.e.1 DOM Elements The XML Schema language provides xsd:anyType which is the equivalent of java. it can be envisaged as the base type from which all simple and complex types are derived.

getTagName(). Sun's JAXB currently uses the implementation from Apache's Xerces. like this: <xsd:complexType name="HearsayType"> <xsd:sequence> <xsd:element name="text" type="xsd:string"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="GrapevineType"> <xsd:sequence> <xsd:element name="text" type="xsd:string"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="RumourType"> <xsd:sequence> <xsd:element name="text" type="xsd:string"/> </xsd:sequence> </xsd:complexType> We want any of these nice documents to be envelopped by a container document: <xsd:complexType name="CommType"> <xsd:sequence> <xsd:element name="source" type="xsd:string"/> <xsd:element name="comm" type="xsd:anyType"/> </xsd:sequence> </xsd:complexType> There is no surprise in the classes generated by the JAXB compiler.dom. e.Node.Element.ElementNSImpl.dom..Object.. (The comm subelement of CommType has the type java. if you really have to.16.: Element content = (Element)bag.lang.2. class apache.dom.xerces. Node<List> = content. i.. // .getChildNodes().2 Another Content Tree as Element It's also possible to insert an arbitrary content tree as an element.) So we can write some code to marshal such an XML communication.getContent(). String tag = content.w3c. you can leave the cushy and plushy JAXB environment and continue with traditional DOM processing methods.obtuse).g. We'll assume that we have several document definitions.w3c. which is a subinterface of org..internal..more DOM accesses.e. .the important thing is that it implements org. ObjectFactory of = new ObjectFactory(). 2.dom. then what? Well. If you need to marshal arbitrary content you'll have to create a content tree according to org.w3c. the actual class doesn't really matter . This means that.

The resulting XML text looks like this: <?xml version="1.org/2005/05/xmlmime" schemaLocation="http://www.setComm( hearsay ).w3.2.setText( "Mr.. comm.getComm()..getComm() instanceof HearsayType ){ HearsayType hearsay = (HearsayType)comm. if( comm. // Prepare a JAXBElement. CommType.17 Image Data An element containing a JPEG image has an XML schema definition like this: <?xml version="1. ready for marshalling. Harper does naughty things.</text> </comm> </comm> It should be satsifying to note that JAXB has annotated the comm element with xsi:type="HearsayType" which is going to help a lot during the inverse process. JAXBElement<CommType> je = new JAXBElement<CommType>( qn. JAXBElement<CommType> je = (JAXBElement<CommType>)u..com/know-type" xmlns:xmime="http://www. } else { // .getValue(). CommType comm = (CommType)je. } 2. hearsay." ).org/2005/05/xmlmime"/> .w3. comm ). ).org/2005/05/xmlmime" targetNamespace="http://example.0"?> <xs:schema xmlns:xs="http://www.org/2001/XMLSchema-instance" xsi:type="HearsayType"> <text>Mr.createCommType().w3.unmarshal( f ).(investigate other possibilities).createHearsayType().w3. In fact..0" encoding="UTF-8" standalone="yes"?> <comm> <source>Ms Jones</source> <comm xmlns:xsi="http://www..org/2001/XMLSchema" xmlns:tns="http://example.. HearsayType hearsay = of. QName qn = new QName( "comm" ). The JAXBElement is now ready to be passed to a Marshaller. CommType comm = of.setSource( "Ms Jones" ). all you have to do to get this document unmarshalled into a content tree and to access the nested contents is this: File f = new File( .class. // Let's have some hearsay. comm.com/know-type"> <xs:import namespace="http://www.w3. Harper does naughty things.// Create the container object.

getJPEGPicture(). // Draw it Graphics g = . Image.. Well.3 Hints on Writing XML Schemas 2. it's preferable to define all schema types explicitly.. Image img = bimg..drawImage( img. the resulting Java class will be given the name defined in the schema rather than a name selected by JAXB. Unmarshalling is just as simple. Moreover. To create XML content and to marshal an instance document containing an image you can write code to create an object of type Image and set its reference in the appropriate element of the content tree: BufferedImage bimg = ImageIO. this means that you will be able to re-use the type within your schema.drawImage() with this object as the first argument. // Create the Item element and store the image reference ItemType itemEl = of.<xs:complexType name="ItemType"> <xs:sequence> <xs:element name="JPEGPicture" type="xs:base64Binary" xmime:expectedContentTypes="image/jpeg"/> </xs:sequence> </xs:complexType> <xs:element name="Picture" type="ItemType"/> </xs:schema> The <xs:import> element is not required. For one thing. More importantly. But when you're using JAXB to generate Java classes. -1. and here she is: <<<picture deleted>>> 2. JAXBElement<ItemType> jbe = of. JAXB appears to "know" about this namespace.getScaledInstance( 512.. 0. g.createPicture( itemEl ).. null ). itemEl.3. // Get the image from the content tree. You extract the Image object from its parent element and call Graphics.read( imgFile ). Image img = jbe.. JAXBElement<ItemType> jbe = .createItemType().1 Don't Use Anonymous Types The XML Schema language lets you define XML types anonymously.getValue(). The schema type xs:base64binary is the type best suited for representing image data. anonymous types result in some inner class. Consider the following XML schema snippet: <xsd:complexType name="PurchaseOrderType"> <xsd:sequence> . 0.SCALE_DEFAULT ).setJPEGPicture( img ).

// .(getters and setters) } 2.(getters and setters) public List<PurchaseOrderType. If the documents share common XML types. they should be written once. protected List<PurchaseOrderType. public class PurchaseOrderType { protected AddressType shipTo. } return this. .Item> getItem() { if (item == null) { item = new ArrayList<PurchaseOrderType..<xsd:element name="shipTo" type="AddressType"/> <xsd:element name="billTo" type="AddressType"/> <xsd:element name="item" minOccurs="0" maxOccurs="unbounded"> <xsd:complexType> <xsd:sequence> <xsd:element name="productName" type="xsd:string"/> <xsd:element name="quantity" type="xsd:positiveInteger"/> <xsd:element name="price" type="xsd:decimal"/> </xsd:sequence> <xsd:attribute name="partNum" type="xsd:string" use="required"/> </xsd:complexType> </xsd:element> </xsd:sequence> <xsd:attribute name="orderDate" type="xsd:date"/> </xsd:complexType> The relevant parts of the generated class PurchaseOrderType are presented below..3. // . protected BigInteger quantity. The common definitions could be assembled into a namespace of their own.Item>().item.. and re-used from there wherever they are required. protected BigDecimal price. Note that PurchaseOrderType. protected AddressType billTo. The XML schema snippets given below illustrate this approach. in a separate schema file.2 Common Schema Definitions Different document types (within one project) require different schemas.Item is the somewhat unwieldy name of the class for an order item as it results from an inlined schema type. to avoid any conflicts with type or element names in the schemas where they are used. protected String partNum. } public static class Item { protected String productName. protected XMLGregorianCalendar orderDate..Item> item.

and you may have as many as you like within a single schema. . e.g.0" encoding="utf-8"?> <xsd:schema xmlns:xsd="http://www. The previous schema snippet might be extended with the following element definitions: <xsd:schema ..w3.org/common" schemaLocation="common.org/solarsystem"> <xsd:import namespace="http://astronomy.0" encoding="utf-8"?> <xsd:schema xmlns:xsd="http://www.astronomy.w3.. Any top-level element definition (by some xsd:element schema element) is a candidate for a root element.xsd"/> <xsd:complexType name="MoonType"> <xsd:extension base="ast:BodyType"> </xsd:sequence> <xsd:element name="planet" type="xsd:IDREF"> </xsd:sequence> </xsd:complexType> <xsd:complexType name="PlanetType"> <xsd:extension base="ast:BodyType"> </xsd:sequence> <xsd:element name="moon" type="ss:MoonType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:schema> The schema compiler derives the package names from the URIs given in the namespace definitions.org/common" targetNamespace="http://astronomy.org/2001/XMLSchema" xmlns:ast="http://astronomy.<?xml version="1.org/solarsystem" xmlns:ss="http://astronomy.common and org.org/common"> <xsd:complexType name="BodyType"> </xsd:sequence> <xsd:element name="name" type="xsd:ID"> <xsd:element name="mass" type="xsd:float"> <xsd:element name="radius" type="xsd:float"> </xsd:sequence> </xsd:complexType> </xsd:schema> The definitions from this schema can be used by importing the schema file..org/common" xmlns:ast="http://astronomy.: <?xml version="1. resulting in org. It should also be noted that it is not necessary to have one schema file for each document type.> .solarsystem.org/2001/XMLSchema" targetNamespace="http://astronomy.astronomy..

They let you put a name to a structured group of elements or attributes.3.createMarshaller().astronomy.marshal( jbe. ObjectFactory of = new ObjectFactory(). To insert the elements or attributes in some other place.createPlanet( planet ).out ). Add planets. SolarSystem sol = of. 2. System.. you have the option of making existing XML files compatible with the new version..5 Spurious Classes It's not necessary to define a separate type for a list resulting from a maxOccurs="unbounded" attribute attached to some element if this element occurs in an xsd:sequence group. Marshaller m = context.. //. This may be regretted.marshal( sol. by defining new attributes with use="optional" and providing a default. //. Given the complex type ItemType.<xsd:element name="planet" type="ss:PlanetType"/> <xsd:element name="solarSystem"> <xsd:complexType> <xsd:sequence> <xsd:element name="planet" type="ss:PlanetType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema> Marshalling either element is possible with a marshaller created from the context based on the package org. it is possible to define . 2. m..3 A Note on Groups The XML Schema language provides the constructs xs:group and xs:attributeGroup.3. use the attribute ref=".. respectively. System. // Create a solar system." specifying the group's given name.g..3.out ).createSolarSystem(). Add attributes and moons JAXBElement<PlanetType> jbe = of.4 Conserving Compatibility One of the advantages of XML is that data may be omitted wherever a default is acceptable.createPlanetType().. This feature is useful if your elements have common subsets of elements or attributes. // Create a single planet instance document. If an XML schema is extended. 2. but it does not affect the Java code generated by JAXB's schema compiler xjc. m. since groups or group combinations might provide a basis for adding interface definitions to the generated set of classes.solarsystem. e. PlanetType planet = of.

another type, say ItemListType, as a list of items. <xsd:complexType name="ItemType"> <xsd:sequence> ... </xsd:sequence> </xsd:complexType> <xsd:complexType name="ItemListType"> <xsd:sequence> <xsd:element name="Items" type="ItemType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> Within some other type definition it is equally possible to use either ItemListType, or ItemType with the attribute maxOccurs="unbounded": <xsd:complexType name="WrapItemType"> <xsd:sequence> <xsd:element name="Items" type="ItemType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="WrapItemListType"> <xsd:sequence> <xsd:element name="ItemList" type="ItemListType"/> </xsd:sequence> </xsd:complexType> The code for WrapItemType contains a list of ItemType objects, providing immediate access to the list: public class WrapItemType { protected List<ItemType> items; public List<ItemType> getItems() { if (items == null) { items = new ArrayList<ItemType>(); } return this.items; } } With the additional type definition in the schema you get an additional Java class. public class ItemListType { protected List<ItemType> items; public List<ItemType> getItems() { if (item == null) { item = new ArrayList<ItemType>(); }

return this.item; } } public class WrapItemListType { protected ItemListType itemList; public ItemListType getItemList() { return itemList; } public void setItemList(ItemListType value) { this.itemList = value; } } The additional class layer requires an additional getter call to retrieve an item, e.g., a.getItemList().getItems(). We note that the XML text is verboser, too. The additional type and class requires an additional tag, bracketing the list. <A> <ItemList> <Item>...</Item> <Item>...</Item> ... </ItemList> </A> This isn't required in the simpler variant: <B> <Item>...</Item> <Item>...</Item> ... </B> Notice, however, that having the <ItemList> element in place has some advantages, too. For one thing, even an empty list of items appears visibly, and may evoke some processing triggered by the empty wrapper element. Also, it is now possible to insert a complete item list in one fell swoop into the parent element, since now there is a setItemList setter. This may help when one object tree is assembled from another one. 2.3.6 Avoid Unnecessary JAXBElement<?> Try to avoid JAXBElement<?> as type of list elements. JAXB has to use this auxiliary type for elements if you have a complex element that contains a sequence consisting of elements with different tags but identical types. But you can always create distinct subtypes for each tag, even if the extension does not add anything. This means that, at the price of a few additional empty type definitions in your schema, you can avoid the bother resulting from distiguishing elements retrieved from a list not only by their class but also by their tag.

3 Unmarshalling and Using the Data 3.1 Unmarshalling A simple approach for unmarshalling an XML document consists of the creation of a JAXB context and the call to unmarshal the document. A JAXBContext object provides the entry point to the JAXB API and maintains the binding information between XML and Java. One way of creating a context instance is by calling the static method newInstance with a list of colon separated names of the packages containing the JAXB schema-derived classes. From this context, an Unmarshaller object is obtained, which functions as the driver for processing an XML text to create the equivalent set of Java objects. It offers several unmarshal methods, accepting a wide range of object types as the source for XML text data. The method shown below illustrates this with a single package containing the class of the type defining the top level element of the XML document. public <T> T unmarshal( Class<T> docClass, InputStream inputStream ) throws JAXBException { String packageName = docClass.getPackage().getName(); JAXBContext jc = JAXBContext.newInstance( packageName ); Unmarshaller u = jc.createUnmarshaller(); JAXBElement<T> doc = (JAXBElement<T>)u.unmarshal( inputStream ); return doc.getValue(); } The return value of the call to JAXB's unmarshal is a representation of the root node of the parsed XML document in an instance of JAXBElement<T>. If we're not interested in the tag of the root element we might just as well return the extracted content value. 3.2 Using the Element Tree The javadoc contained within the classes generated from an XML schema documents all the getters for accessing an XML element's attributes and child elements. A good approach is to implement a set of handler classes, one for each schema element type. Its handle method retrieves attributes and child elements, for which it invokes the handle method in turn. This corresponds to a depth-first traversal of the document tree.The example assumes that there is a simple set of schema types: <xsd:complexType name="PersonType"> <xsd:sequence> <xsd:element name="Name" type="NameType"> <xsd:element name="Addr" type="AddrType" minOccurs="0"> <xsd:element name="Child" type="ChildType" minOccurs="0" maxOccurs="unbounded"> </xsd:sequence> <xsd:attribute name="resident" type="xsd:boolean"/> </xsd:complexType> <xsd:complexType name="ChildType"> <xsd:complexContent> <xsd:extension base="PersonType"/>

Let's assume a small change in the definition of PersonType. public abstract void handle( Object o ). static { ourClass2Conv. new AddrHandler() ).put( //.getHandler( obj ). There is one noteworthy complication that arises if subordinate elements have to be distinguished by their tag.class.isResident() ){ process( p. protected void process( Object obj ){ if( obj != null ){ Handler h = ourClass2Conv.put( ourClass2Conv.get( obj.class. } processList( p.</xsd:complexContent> </xsd:complexType> Below is the essential Java code for a handler class hierachy. if( p.class.put( ourClass2Conv. ChildType. ..process( obj ). NameType. new PersonHandler() ).put( ourClass2Conv. } PersonType..getChild ). Note that delegation to some handler for a sub-element or attribute depends on the item having a specific class. AddrType. abstract class Handler { protected static Map<Class<?>.getName() ). } } Not all subclasses of Handler will be quite so simple. new ChildHandler() ). } } } protected <T> void processList( List<T> list ){ for( T obj: list ){ Handler h = this. h.handle( obj ). if( h != null ){ h. new NameHandler() ). } } } class PersonHandler extends Handler { public void handle( Object o ){ PersonType p = (PersonType)o.Handler>().Handler> ourClass2Conv = new HashMap<Class<?>.class. process( p.getClass() ).getAddr() ).

because XML tags need not be unique across the various element types. All we have to do is a slight extension of the generic method processList. 3. you create this schema object by setting up a schema factory for the schema language of your choice. If you want to validate your document before it is unmarshalled. } } Finally. We have seen that the JAXB compiler doesn't care much about these facets as it just translates the basic datatype into one of Java's built-in types. the methods process and handle would have to be extended by an additional String parameter. if the tag is required for processing as well. enabling the programmer to restrict the basic datatypes. that returns a List<JAXBElement<ChildType>>. JAXB lets you request validation by passing an object of the class javax. SchemaFactory sf = SchemaFactory. This is best put into the handler class hosting the list. An additional lookup table mapping tag names to handlers might be required as well. } Handler h = this. h. Don't make such a map global. we now have (in class PersonType) a method getBoyOrGirl(). protected <T> void processList( List<T> list ){ for( T obj: list ){ if( obj instanceof JAXBElement ){ obj = ((JAXBElement<?>)obj).newInstance( XMLConstants.<xsd:complexType name="PersonType"> <xsd:sequence> <xsd:element name="Name" type="xsd:string"/> <xsd:element name="Addr" type="xsd:string" minOccurs="0"/> <xsd:choice minOccurs="0" maxOccurs="unbounded"> <xsd:element name="Boy" type="ChildType"/> <xsd:element name="Girl" type="ChildType"/> </xsd:choice> </xsd:sequence> <xsd:attribute name="resident" type="xsd:boolean"/> </xsd:complexType> To get at a person's children.process( obj ).getValue().xml. Then you create the Schema object by calling the factory's method newSchema: Schema mySchema. to access the JAXBElement object and continue to use its value attribute instead of the object obtained from the list.W3C_XML_SCHEMA_NS_URI ).validation.3 Validation A considerable part of the XML Schema language deals with facets. try { .getHandler( obj ). The value is obtained by a call of the JAXBElement method getName(). First. A meticulous interpretation of these facets for checking that the XML data meets the constraints must be done during a schema validation.Schema to the Unmarshaller object.

mySchema = sf. Implementing classes must provide a single method to catch a ValidationEvent as we've seen it in the previous section.getColumnNumber(). If you'd like to create your own error messages.hasEvents() ){ for( ValidationEvent ve: vec. Make sure to let the user of your program see the exception message so that the problem can be fixed.newSchema( file ).getMessage(). alas. boolean handleEvent( ValidationEvent event ) To register. u.. ValidationEventLocator vel = ve. The best place for checking the event collector is in the finally phrase of the try statement wrapping all of this: if( vec != null && vec. If the XML data validation fails.4 Validation Event Handling The interface javax. an UnmarshalException (from javax. Unmarshaller u = jc.xml." + column + ": " + msg ). you can pass a ValidationEventCollector to the unmarshaller which will store validation events into it so that you can retrieve an event and query its individual attributes.bind) is thrown. } catch( SAXException saxe ){ // ..newInstance( packagePath ). If you want to continue as long as possible. or at least as many as possible but. you'll have to catch all errors with a ValidationEventHandler.createUnmarshaller(). If the calling object is implementing the event handler interface.getEvents() ){ String msg = ve. the Unmarshaller method setEventHandler is called. u. int line = vel.err.setEventHandler( vec ).getLineNumber(). System. } After the Unmarshaller object has been established. } } Now this looks as if the validation process would be kind enough to present you with all the errors in your XML document. as explained in the next section.setSchema( mySchema ). Insert these lines before you call the unmarshal method: ValidationEventCollector vec = new ValidationEventCollector().xml.println( origin + ": " + line + ". int column = vel.getLocator(). JAXBContext jc = JAXBContext. Basically that's all there is to it.ValidationEventHandler is quite simple.(error handling) mySchema = null. we might write: . it appears that the validation process throws an exception as soon as the first deviation is detected.bind. 3. you pass it the schema.

foo. 3. e. however. Each package must contain its own class ObjectFactory or a file named jaxb. the top level classes are sufficient since JAXB will follow. all static references.Foo.foo.newInstance( "some foo:more.index. and therefore this form of newInstance is usually used in connection with schema derived classes. which provides a way of extending the closure of recognized classes. u. such as the types of instance variables.Boo An alternative form of the newInstance method lists all classes that the new context should recognize. For JAXB annotated Java code. either with a hand-written ObjectFactory class or with a jaxb. earlier in this chapter.5 The JAXB Context As we have seen. An ObjectFactory class is generated by the XML schema compiler.Foo Foo # inner class some. . Bar.Boo Foo. recursively.: # package some.foo # class some.newInstance( Foo. Usually.class ). This file simply lists the class names relative to the package where it occurs. Subclasses. JAXBContext ctxt = JAXBContext. (But see the section Class Inclusion: XmlSeeAlso about the annotation XmlSeeAlso.bar" ).) If packages or classes are associated with namespaces.setEventHandler( this ). are not included.index resource file containing a list of the class names to be considered by JAXB. you may use the package path form as well.createUnmarshaller(). an object of the class JAXBContext must be constructed as a starting point for other operations.g.Unmarshaller u = jc. One way is to create a context from a colon separated list of packages. the packages or classes associated with a JAXB context also determine the namespace declarations written as attributes into the top-level element of the generated XML document. JAXBContext ctxt = JAXBContext.class.

</foo> JAXBElement<FooBarType> fooElem = objFact.getFooOrBar(). Here is a schema snippet: <xsd:complexType name="FooBarListType"> <xsd:sequence> <xsd:choice minOccurs="0" maxOccurs="unbounded"> <xsd:element name="foo" type="FooBarType"/> <xsd:element name="bar" type="FooBarType"/> </xsd:choice> </xsd:sequence> </xsd:complexType> The ObjectFactory would now contain several methods for creating a FooBarListType and its offsprings. It's convenient to use the methods of this class because they provide an easy way of creating elements that have to be represented by a JAXBElement<?> object..createModuleType(). // create a "foo" element FooBarType foo = objFact. JAXBElement<RulebaseType> doc = objFact.. A JAXBElement<?> is also required for element sequences containing elements of the same type but with differing tags. A simple element that does not require a JAXBElement<?> wrapper is created by a straightforward method call. Given that the top-level element of a document is represented as a JAXBElement<RulebaseType> with the tag "rulebase".createRulebaseType().createFooBarListType(). one such doument object can be created by code as shown below.(add attributes and components to bar) // Create the element <bar>. // . RulebaseType rulebase = objFact.createFooBarType().add( fooElem ). A possible sequence of calls is shown in the Java code below. // Add it to its parent's list.createRulebase( rulebase ). List<JAXBElement<FooBarType>> fbList = fblElem. // create a "bar" element FooBarType bar = objFact. ObjectFactory objFact = new ObjectFactory(). FooBarListType fblElem = objFact. ... // Add it to its parent's list... ModuleType module = objFact.add( barElem ).createFooBarType(). fbList..</bar> JAXBElement<FooBarType> barElem = objFact.. fbList. // .createFooBarTypeBar( bar ).4 Building and Marshalling an XML Document 4.(add attributes and components to foo) // Create the element <foo>.1 The Object Factory Usually hidden in the middle of the list of the classes derived from the types defined in an XML schema there will be one class called ObjectFactory.createFooBarTypeFoo( foo ).

We'll illustrate these with a skeleton layout for a product order. Sequential orderings that correspond to one of the basic tree traversal orders can be handled with elementary techniques. 4. The frequently used construction method that proceeds from the tree root towards the leaves may be written according to two typical scenarios for the construction of an element. Usually it will be the structure of the input material that advocates some specific approach. If the data isn't arranged in one of the tree traversal orders you could set up two or more "cursors" that point into the emerging tree so that you might add to several places in parallel. insert and fill the elements as you traverse the existing structure. for instance.2 Assembling Document Tree Nodes Neither the methods of the element object factory nor the constructors of the classes derived from the types defined in the XML schema require that you have any of an element's child elements or attributes at the time of the call. the data is in post-order. (The single exception is the set of factory methods creating a JAXBElement<?>. <xsd:complexType name="CustomerType"> <xsd:sequence> <xsd:element name="id" type="xsd:int"/> <xsd:element name="name" type="xsd:string"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="ItemType"> <xsd:sequence> <xsd:element name="id" type="xsd:string"/> <xsd:element name="quantity" type="xsd:int"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="OrderType"> <xsd:sequence> <xsd:element name="customer" type="CustomerType"/> <xsd:element name="items" type="ItemType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> <xsd:element name="folder"> <xsd:complexType> <xsd:sequence> <xsd:element name="orders" </xsd:sequence> </xsd:complexType> type="OrderType" maxOccurs="unbounded"/> . as you can create.You may avoid these complications by subtyping FooBarType into identical types FooType and BarType. If. without any actual XML content. Building the document tree from comparable hierarchical structures is the easiest way. but their arguments may be "empty" element objects.) This gives you maximum freedom to design your tree-building algorithm. you might use a stack to keep assembled XML elements until their parent element becomes eligible for construction.

setName( custName ). the sequence for adding a solitary subordinate element of type X goes like this: Create the subordinate element xElem via a call to factory method createX.getItems().createOrderType().createItemType().. with a call to the getter current.getX(). Make the new element the current element and repeat this process recursively for the new element's offsprings. itemList. we extend this algorithmic outline somewhat: Create the subordinate element xElem via a call to factory method createX.. itemElem.</xsd:element> Assuming that we are about to add the content for a "current" element.qtty ). You should now have no problems understanding the Java code that creates an order element according to the previously given schema snippet. It may be a good strategy to insert a newly created element immediately after its creation. a list of orders OrderType orderElem = objFact. // Data for an order int custId = .id ). If the subordinate element occurs repeatedly. // Create and insert the customer element.. // Create order and insert in top-level document. Obtain the reference to the subordinate List<X>.getOrders()..add( itemElem ). custElem. CustomerType custElem = objFact.setCustomer( custElem ). Item[] items = .setQuantity( item. of course.add( orderElem ). custElem. List<ItemType> itemList = orderElem. itemElem.setX( xElem ). // Complete customer... It reduces the risk that this essential operation is left out. // Create and add item elements.. } . Add this object to the current element. For each subordinate element: Create it using the factory method createX. String custName = .. This is. folder.setId( item. Append (add) it to the List<X>. Make the new element the current element and repeat this process recursively for the new element's offsprings. with a setter call current.createCustomerType(). for( Item item: items ){ ItemType itemElem = objFact. simply to be repeated for other child elements.setId( custId ).. orderElem.

) The counter-strategy to adopt here is to enforce a rigid naming convention which should not only deal with class names but also include naming rules for the temporary variables referencing objects of classes from either group. inline customer element. i. or a reference to a customer element that is in some other place.Another thing that can be gleaned from these lines is the danger of confusion. Our example is a variation of the order data. on the other hand.. 4. decide to emit each of these occurrences in full. Here.3. IDREF) 4. Recalling briefly that a key element or attribute with type xsd:ID has to be added to the element that is to be referenced from elsewhere and that a simple element or attribute with type xsd:IDREF is used in place of occurrences of the full element. The XML Schema language provides the schema data types xsd:ID and xsd:IDREF. (In the example there is ItemType and Item. of course. The Java type JAXB uses for the reference is plain Object. We now have getters and setters for a CustomerType. we'll proceed to discuss the techniques for assembling a document tree where elements are linked in this way. and their classes are bound to have names that aren't entirely different from the ones coming from the schema. There will be duplicated objects when the unmarshalled data is transferred into application objects. even though . <xsd:complexType name="CustomerType"> <xsd:sequence> <xsd:element name="id" type="xsd:ID"/> <xsd:element name="name" type="xsd:string"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="OrderType"> <xsd:sequence> <xsd:choice> <xsd:element name="customer" type="CustomerType"/> <xsd:element name="custref" type="xsd:IDREF"/> </xsd:choice> <xsd:element name="items" type="ItemType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> The Java code for OrderType deserves a quick inspection.1 One Element per Identification It is not unusual that the data that is to be represented as XML contains elements repeatedly that are either identical or equal. which we've already discussed in the section Referring to Another XML Element. we have the classes representing XML elements. the full.e. You may. On the one hand. an order may either contain a full customer XML element. the data for the XML document is likely to be around in a more or less similar set of objects. and. but this has obvious disadvantages: It increases the volume of the XML text.3 Assembling Data with Links (ID. or for a customer reference.

customer = value. } public List getItems() { if (items == null) { items = new ArrayList(). Notice that "first occurrence" is not necessarily the foremost element in the final XML text. where we'll use the second method. String custId. The first possibility replaces all occurrences with references. } public void setCustref(Object value) { this.CustomerType> id2cust = new HashMap<String. Map<String. public void addCust( OrderType order. } public void setCustomer(CustomerType value) { this.we'll only use objects of type CustomerType here.items. This means that the full elements must be added separately. String custName ){ CustomerType cust = id2cust. private ObjectFactory oFact = new ObjectFactory(). // complete customer cust. and in a way that is not to be confused with the actual document. Both ways you'll have to keep track of the association between keys and element references.custref = value.createCustomerType(). cust = oFact. } } The XML element may contain full elements and references in two slightly different arrangements. The other option is to leave the first occurrence of a specific element in place and replace all duplicates. protected List items.setCustomer( cust ).setId( custId ). we'll look at a method that adds the customer to an order. order. . } public Object getCustref() { return custref.CustomerType>(). too. Continuing our example. protected Object custref. public CustomerType getCustomer() { return customer. public class OrderType { protected CustomerType customer.get( custId ). if( cust == null ){ // Create and insert customer. } return this.

changing them magically to the corresponding string values. If the customer lookup returns an object. hides this as long as possible by letting you handle references implemented as addresses. i. This key is also used as a key in the map. We create a CustomerType object. JAXB. and make sure that the assembly of this element includes a call to the setter for the key element.2 Preserving Object Identity In the previous section we have tacitly assumed that there is one and only one object with a certain identification which is readily available from the object.e.0" encoding="UTF-8" standalone="yes"?> <folder> <orders> <customer> <id>c12789</id> <name>Smith</name> </customer> <items> <id>12</id> <quantity>1</quantity> </items> <items> <id>24</id> <quantity>100</quantity> </items> </orders> <orders> <custref>c12789</custref> <items> <id>35</id> <quantity>10</quantity> </items> </orders> </folder> Don't be confused when you look at the generated XML code and detect that the value in the "custref" element is nothing but a string. But . Here is a look into a folder containing two orders to the same customer.setCustref( cust ). Memory addresses .cust.put( custId. JAXB takes care of generating the XML text representing the reference. then we meet a customer for the first time.aren't useful in an XML text file. <?xml version="1. the "id" string. // save in map id2cust.the convenient material for references . where we keep that element for future reference. } else { order. we simply use the object reference value of the full element as an argument to the alternative setter for the custref element. } } If the lookup in the mapping of customer ids to customer elements returns null.. however. 4.setName( custName ). cust ).3.

The code below creates another XML element for AddressType from an Address object. To see how this works. For an example we extend the schema describing orders with an additional AddressType and use this. .util) to register marshalled elements. <xsd:complexType name="AddressType"> <xsd:sequence> <xsd:element name="street" type="xsd:string"/> <xsd:element name="city" type="xsd:string"/> <xsd:element name="country" type="xsd:string"/> <xsd:element name="zip" type="xsd:int"/> </xsd:sequence> <xsd:attribute name="id" type="xsd:ID"/> </xsd:complexType> <xsd:complexType name="AddrOrRefType"> <xsd:choice> <xsd:element name="addr" type="AddressType"/> <xsd:element name="addrRef" type="xsd:IDREF"/> </xsd:choice> </xsd:complexType> <xsd:complexType name="OrderType"> <xsd:sequence> <xsd:choice> <xsd:element name="customer" type="CustomerType"/> <xsd:element name="custref" type="xsd:IDREF"/> </xsd:choice> <xsd:element name="shipTo" type="AddrOrRefType"/> <xsd:element name="billTo" type="AddrOrRefType"/> <xsd:element name="items" type="ItemType" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> The generated class AddrOrRefType enables us to choose between an address in full or a reference to such an XML element.AddressType> pojo2elem = new IdentityHashMap<Address. but how does this help to avoid generating full XML text for each occurrence? Should we use the equals(Object o) method for identifying objects that deserve the same synthetic identifier? The answer is that with a little extra effort you can still preserve object identity so that the same number of objects can be reconstructed when the XML data is read and unmarshalled back into memory. Map<Address. Luckily there is a better way: we can use an instance of an IdentityHashMap (from java.what do you do if there is no such identification? Generating synthetic identifications isn't a problem. Keeping a list of marshalled elements and searching through it isn't attractive. once for a shipping address and once for a billing address. we assume that we have addresses in objects of type Address.of type AddressType. Also. This map uses the object's default hash code. Object identity can be tested by applying the operator == to any two objects. we have to add an (artificial) identification to our objects as this is required as the xsd:ID value.AddressType>(). even if hashCode has been overridden.

. // Register the object . } public AddrOrRefType makeAddrOrRefElement( ObjectFactory objFact. provided that the class of the object implements the java. pojo2elem. addrElem. // . if( addrElem == null ){ // First time: generate the full XML element. But the need does arise occasionally.(Copy attributes from addrPojo into addrElem. we enter it into the map and generate an AddrOrRef element containing the full AddressType element.util. The schema element that is to contain the serialized binary data should be declared with a type of xsd:hexBinary.setAddr( addrElem ). the AddrOrRef receives the reference to the previously created AddressType element.and insert it into its parent. <xsd:complexType name="JavaObjectType"> <xsd:sequence> <xsd:element name="data" type="xsd:hexBinary"/> </xsd:sequence> </xsd:complexType> <xsd:element name="container" type="JavaObjectType"/> The generated Java class JavaObjectType has a field byte[] data..setAddrRef( addrElem ).put( addrPojo. AddressType addrElem = pojo2elem. Address addrPojo ){ AddrOrRefType arElem = objFact.. } Using Address objects as keys. for instance. it is surprisingly simple.get( addrPojo ).4 Last Resort: Assembling a Java Object With all the features XML schema provides and JAXB translates you might think that including arbitrary Java objects in an XML document won't ever be necessary.. 4. addrElem = objFact. addrElem ). // . which is just what . may have to use this rather extreme technique.createAddrOrRefType()..).. arElem. arElem. For an encore. } else { // We've had this one before: insert its reference. } return arElem.. we map these to assembled AddressType objects. Special dumps of application data..id pair in the identity hash map.Serializable interface. // Set the xsd:ID attribute.int refcount = 0.setId( makeNextId() ). Whenever we encounter a new object of class Address. The schema snippet shows a simple container for some such object.createAddressType(). All in all. private String makeNextId(){ return "a" + refcount++.

The code required to serialize a Java object into a XML element is shown below.org/2001/XMLSchema-instance" xsi:schemaLocation="serial. ClassNotFoundException { ByteArrayInputStream bais = new ByteArrayInputStream( joElem. or the encoding in the XML prolog.xml.7878</data> </container> The reverse process is even simpler.createJavaObjectType(). import java. return joElem.io. joElem.getData() ). ObjectOutputStream ooStream = new ObjectOutputStream( baos ). The first argument must be an object that is either a root element. Other properties concern the inclusion of a schema location as an attribute in the top-level element. } The generated XML text is verbose and lengthy. String pathname ) . oiStream.0" encoding="UTF-8" standalone="yes"?> <container xmlns:xsi="http://www.io. return pojo. Here it is. ooStream. such as the one that's used below.5 Calling marshal Only a handful of source code lines is required to make a JAXB Marshaller object write a document tree as an XML file. JavaObjectType makePojoElem( ObjectFactory objFact. Object pojo ) throws IOException { ByteArrayOutputStream baos = new ByteArrayOutputStream(). as defined by your schema. Then.toByteArray() ). import javax. ObjectInputStream oiStream = new ObjectInputStream( bais ).flush().readObject(). The byte array returned by the getter for the data element is fed to the ObjectInputStream which smartly returns the original object. Object pojo = oiStream.*. since all object data required for a full reconstruction is included in the serialized data. which requests nice formatting of the XML text.close(). or a JAXBElement<?>. JavaObjectType joElem = objFact.writeObject( pojo ). you might set a number of properties. ooStream.we need for calling the java..setData( baos.w3. Object getPojo( JavaObjectType joElem ) throws IOException.xsd"> <data>ACED00057372. ooStream.* void writeDocument( Object document.close().. omitting a few hundred hexadecimal digits: <?xml version="1. } 4. First you obtain a Marshaller from a JAXBContext.ObjectOutputStream methods writeObject and readObject.bind.

throws JAXBException. Class<?> clazz = o.TRUE ).. st ).acme. clazz. but this is cumbersome.setProperty( Marshaller. } Sometimes marshalling needs to be done not only for one or two root documents but for objects of many different schema types.com".marshal( jbx. JAXBContext context = JAXBContext. m. @SuppressWarnings( "unchecked" ) JAXBElement<T> jbe = new JAXBElement( qtag.getName() ). System. o ).createMarshaller(). String tag.) With a Marshaller m obtained from this context. <T> JAXBElement<T> wrap( String ns. .. m. T o ){ QName qtag = new QName( ns. "someTag".getClass(). of course. (Creating a JAXBContext for several packages or classes is explained in section The JAXB Context. new FileOutputStream( pathname ) ).getClass(). m. Marshaller m = context.getValue(). return jbe. A generic solution is presented below. Boolean.getPackage(). tag ). IOException { Class<T> clazz = document. } To use it. you must create a context capable of handling all the classes that might crop up as instantiations for T.out ).marshal( document. The method wraps an arbitrary element of some type T into a JAXBElement<T>.JAXB_FORMATTED_OUTPUT.newInstance( clazz. add xsd:element definitions for all of them to the top level xsd:schema element. You could. JAXBElement<SomeType> jbx = wrap( "http://www.. the application of wrap is as simple as this: SomeType st = .

JAXB uses the somewhat unimaginative package name generated. however. where you would indicate the namespace URI: <?xml version="1.xjb. 5.0"> . Several customizing features are provided for adding information to the compiler's output. Its outermost element is jaxb:bindings. By default.ruleml -d gen-src RuleML. and for overriding the compiler's defaults for binding schema definitions to Java classes.5 Customizing 5. in addition to the option defining the root directory for the generated source files.2 Defining Package Names Some Java entities don't have a counterpart in an XML schema.sun. You can set a more appropriate package name in the call of the JAXB compiler. or it can be written on a separate file that is passed to the schema compiler.: xjc -p jess..com/xml/ns/jaxb" version="2.0" encoding="UTF-8"?> <jaxb:bindings xmlns:jaxb="http://java.. We'll see these techniques in the succeeding subsections. ususally of file type . This XML file uses elements from the jaxb namespace. </jaxb:bindings> . is neither flexible enough nor easy to maintain. The main reasons for customizing are: providing meaningful package names overriding the default class name (to avoid name clashes) overriding the default names for enum constants adding documentation associating a specific Java class with an XML Schema built-in type Customizing can be added inline to the schema.xsd This.ruleml"/> </jaxb:schemaBindings> </xsd:appinfo> </xsd:annotation> If you don't want to burden your XML schema with these annotations you can collect this and other customizing directives in a separate file. One of these things is the package name.1 Reasons for Customizing It may not always be possible for the JAXB Schema compiler to determine all details of the generated Java code from the XML schema alone. A better place would be in the schema file itself where you may write an xsd:annotation element containing an xsd:appinfo sub-element: <xsd:annotation> <xsd:appinfo> <jaxb:schemaBindings> <jaxb:package name="jess.

You pass the file name to the schema compiler: xjc -b RuleML. Let's assume that you have a schema where a complex type has been given the uninspired name List: <xsd:complexType name="List"> <xsd:sequence> . Usually it is more convenient to fix the XML schema.xjb -d gen-src RuleML.sun.0" encoding="UTF-8"?> <jaxb:bindings xmlns:jaxb="http://java. The value of the node attribute is an XPath expression referring to that outermost element.hotel"/> </jaxb:schemaBindings> </jaxb:bindings> </jaxb:bindings> Now we have nested jaxb:bindings elements. with the inner ones being associated with some xsd:schema element.xsd" node="/xsd:schema"> <jaxb:schemaBindings> <jaxb:package name="travel. the outermost element of an XML schema. but you may not always be at liberty to do so.com/xml/ns/jaxb" xmlns:xsd="http://www.0" encoding="UTF-8"?> <jaxb:bindings xmlns:jaxb="http://java.sun.w3.flight"/> </jaxb:schemaBindings> </jaxb:bindings> <jaxb:bindings schemaLocation="Hotel.com/xml/ns/jaxb" version="2. Notice that it's necessary to define the mapping of the XML Schema namespace prefix (here: xsd) to its URI in the top-level jaxb:bindings element. 5. Here is an example: <?xml version="1.org/2001/XMLSchema" jaxb:version="2.ruleml"/> </jaxb:schemaBindings> </jaxb:bindings> A slightly more complicated element structure is necessary if you want to compile several schema files in one run and the classes resulting from different schemata should emerge in separate packages.3 Overriding Names Overriding the name of a class or of an element's child is something you may have to do to avoid name clashes.xsd" node="/xsd:schema"> <jaxb:schemaBindings> <jaxb:package name="travel.0"> <jaxb:bindings schemaLocation="Flight.xsd To put all of your classes into the same package you define the package name in a jaxb:schemaBindings element at the outermost level: <?xml version="1.0"> <jaxb:schemaBindings> <jaxb:package name="jess.

i. If you don't fancy this.util.e. believe me.util. required within the generated class code for declaring the field items. But wherever this class is used it is potentially in conflict with its namesake from java. To avoid having to use the full class name for one of these two classes.<xsd:element name="items" type="ItemType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> JAXB's schema compiler circumnavigates the threatening name clash between this class and java. Yet another reason for changing a name arises from the use of the same name for a sub-element and an attribute within the same complex type definition.List.) <xsd:complexType name="ClassType"> <xsd:sequence> <xsd:element name="grade" type="xsd:string" minOccurs="0"/> </xsd:sequence> <xsd:attribute name="grade" type="xsd:string" use="optional"/> </xsd:complexType> . (Arguably this isn't good XML design. like this: <xsd:complexType name="School"> <xsd:sequence> <xsd:element name="class" type="ClassType"> <xsd:annotation> <xsd:appinfo> <jxb:property name="klass"/> </xsd:appinfo> </xsd:annotation> </xsd:element> </xsd:sequence> </xsd:complexType> Other Java keywords won't constitute a problem.. using an jxb:property element. you can request your own substitute. JAXB's workaround is the standard programmer's choice. For this one. But. The instance variable will be given a name consisting of an underscore followed by the letters of the keyword. you might override the class name for the generated class: <xsd:complexType name="List"> <xsd:annotation> <xsd:appinfo> <jxb:class name="MyListType"/> </xsd:appinfo> </xsd:annotation> <xsd:sequence> <xsd:element name="items" type="ItemType" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> Another unlucky choice for the name of an element or attribute would be Class. it is replaced by Clazz. it does happen.

<?xml version="1. Here is one way of adding some documentation for a class derived from a complex type definition: .0" encoding="UTF-8"?> <jaxb:bindings xmlns:jxb="http://java.xsd" node="/xsd:schema"> <jxb:bindings node="//xsd:attribute[@name='grade']"> <jxb:property name="gradeAttr"/> </jxb:bindings> </jxb:bindings> </jxb:bindings> XML Schema even lets you define a sequence where two individual elements have the same tag <xsd:complexType name="StrangeType"> <xsd:sequence> <xsd:element name="taga" type="xsd:string"/> <xsd:element name="tagb" type="xsd:string"/> <xsd:element name="taga" type="xsd:string"/> </xsd:sequence> </xsd:complexType> There is no such thing as a Java class that has two distinct fields with the same name. this time by specifying the property name in the bindings file.We'll resolve this conflict by renaming the attribute to gradeAttr.com/xml/ns/jaxb" xmlns:xsd="http://www..sun.4 Adding Documentation Both the readers of your XML schema and the users of the generated Java classes will be more than grateful for each morsel of documentation.0"> <jxb:bindings schemaLocation="School...org/2001/XMLSchema" jxb:version="2. it conveys nothing about the intentions behind the schema itself. <xsd:element name="taga" type="xsd:string"> <xsd:annotation> <xsd:appinfo> <jxb:property name="taga2"/> </xsd:appinfo> </xsd:annotation> </xsd:element> . JAXB does a good job by providing most if not all of the Javadoc that can be generated automatically. as part of the type definition in your schema. You must help the schema compiler to resolve this conflict. by renaming either element: .. Documentation is probably best written inline.w3. 5. This way it remains close to the schema text it refers to and documents (not quite perfectly) the XML schema itself. While this is good at describing the relation between the generated Java code and the originating chunks of the XML schema.

Documentation for elements and attributes is added in a similar manner. The variable name must begin and end with an asterisk ('*').<xsd:complexType name="GlobalType"> <xsd:annotation> <xsd:appinfo> <jxb:class> <jxb:javadoc> A &lt. we'll look at a snippet as it might be included to appear as package level documentation. (Another possibility is writing the text as a CDATA section.e. Java class for GlobalType complex type./code> object represents a single defglobal variable definition. It can be written at the outermost level of the schema. you add a child as shown in the example below.". The variable name must begin and end with an asterisk ('*'). Your browser will show you this text as the head of the documentation for the class GlobalType: public class GlobalType extends AssignmentType A GlobalType object represents a single defglobal variable definition." and "&amp. For either of these schema components.code>GlobalType&lt.. <xsd:schema> . "<" and "&" must be written as "&lt...) The text is added up front to the Javadoc text JAXB will provide anyway. . <xsd:element name="elemA" type="xsd:string"> <xsd:annotation> <xsd:appinfo> <jxb:property> <jxb:javadoc> This documents a property which happens to be an XML Schema element. </jxb:javadoc> </jxb:class> </xsd:appinfo> </xsd:annotation> <xsd:complexContent> <xsd:extension base="AssignmentType"/> </xsd:complexContent> </xsd:complexType> Notice that any XML markup requires the escaping of all less-than and ampersand characters. i. </jxb:javadoc> </jxb:property> </xsd:appinfo> </xsd:annotation> </xsd:element> Finally. see below.

. They represent XML element content for Jess constructs and function calls. is there a simple method for interning all strings resulting from unmarshalling? There is only two things to do. So. to sneak in our own method for parsing the XML string data to a Java string. <jaxb:globalBindings> <jaxb:javaType name="String" xmlType="xsd:string" parseMethod="faststring. This may reduce your memory footprint considerably. we customize a small change for the mapping of xsd:string to String. It enables you to write HTML tags in a more readable way.parseString( value ). } .jessml"> <jxb:javadoc> <![CDATA[<body>This package contains classes derived from the XML schema JessML2_0. but is guaranteed to be from a pool of unique strings. Two documents are supported: <ol> <li>rulebase documents containing Jess constructs and function calls <li>fact-list documents containing the result of a call to <code>save-facts-xml</code> </ol> </body>]]> </jxb:javadoc> </jxb:package> </jxb:schemaBindings> </xsd:appinfo> </xsd:annotation> This example features the XML technique for including arbitrary content as a CDATA section.xml. public class StringInterner { public static String parseStringToString( String value ){ return DatatypeConverter.DatatypeConverter.jessrules. First. <xsd:annotation> <xsd:appinfo> <jxb:schemaBindings> <jxb:package name="com. 5.StringInterner. Calling the intern() method on a String returns a string that has the same contents as this string. import javax..5 Interning Strings If your XML data contains a large number of strings with many repetitions it may be well worth interning these strings.bind.intern(). including their subordinate elements..parseStringToString"/> </jaxb:globalBindings> The other thing is to write the class StringInterner which contains a tiny wrapper for the method parseString from DatatypeConverter: package faststring.

util.put( 'V'.4}L?X{. 500 ). rom2int.6. 1 ).put( 'D'.util.4}V?I{.Map.Integer> entry: rom2int. 10.put( 'L'. 5.roman. we have to write a simple class like the one given below.Character> int2rom = new HashMap<Integer. private static Map<Integer. 1 }. import java. and the standard conversion of values between binary and string is just what you need.getValue(). rom2int. it is possible to customize the datatype binding. 500. This means that we'll also have to supply the conversions between the Roman number as a string of letters and as an integer value. for( Map. 5 ).HashMap. We'll illustrate this by a simple example where a xsd:simpleType for roman numbers is defined like this: <xsd:simpleType name="RomanNumberType"> <xsd:restriction base="xsd:string"> <xsd:pattern value="M*D?C{. static { rom2int. private static int[] digits = new int[]{ 1000. 100 ).Integer>(). But its a good strategy to go by the book and call the basic conversion except when we are prepared to do it all on our own. rom2int. } .6 Overriding the Datatype 5.4}"/> <xsd:minLength value="1"/> </xsd:restriction> </xsd:simpleType> (The pattern does not cover the subtractive notation which wasn't used in ancient times anyway. rom2int.Entry<Character. rom2int.entrySet() ){ int2rom. package util.put( 'X'. 50.Character>(). 50 ). 1000 ). as in the next example.) Although the XML type is xsd:string. 100.put( 'C'.1 Replacing the Conversions Most of the time JAXB's mapping of XML Schema types to Java datatypes will meet your expectations.put( 'I'.Integer> rom2int = new HashMap<Character. In those rare cases where this is not adequate. For this. import java. entry. 10 ).put( 'M'.getKey() ). public class RomanNumberConverter { private static Map<Character.put( entry. 5. we'd like to have these values represented by Java's int.} Peeking at the implementation of DatatypeConverter reveals that parseString just returns its argument. rom2int.

6.w3.sun. but the methods must be static.DatatypeConverter provides a rich set of methods that come in handy whenever the XML representation must follow the specifications in XML Schema Part 2: Datatypes. i < value.0" encoding="UTF-8"?> <jaxb:bindings xmlns:jaxb="http://java. The customizing entry supplied in a bindings file should then look like the one given below. We'll discuss the proceedings on the basis of this type definition of a complex type meant to describe integer variables.xsd" node="/xsd:schema"> <jaxb:bindings node="//xsd:simpleType[@name='RomanNumberType']"> <jaxb:javaType name="int" parseMethod="util.roman.RomanNumberConverter. so that it will call our methods for the to and fro between the representations.append( int2rom.xml.length().charAt( i ) ). sb. with a threefold nesting of <jaxb:bindings> providing the level where you define the schema position with an XPATH expression. <?xml version="1. } } There is a useful class that supports the writing of convertes such as this one: javax.com/xml/ns/jaxb" xmlns:xsd="http://www.get( value. for( int i = 0. .printIntToString"/> </jaxb:bindings> </jaxb:bindings> </jaxb:bindings> 5. } } return sb. The essential methods are the ones we'll have to announce to JAXB.RomanNumberConverter.0"> <jaxb:bindings schemaLocation="roman.2 Replacing a Simple Type Replacing a simple schema type such as string by some user defined Java type is a little more complicated than what we have seen in the previous section.toString().roman.get( d ) ). i++ ){ result += rom2int.} public static int parseStringToInt( String value ){ int result = 0.parseStringToInt" printMethod="util. } public static String printIntToString( int value ){ StringBuilder sb = new StringBuilder(). } return result. for( int d: digits ){ while( value > d ){ value -= d. You may choose any names you like.org/2001/XMLSchema" jaxb:version="1.bind.

<xsd:complexType name="VariableType"> <xsd:sequence> <xsd:element name="Value" type="xsd:int"/> </xsd:sequence> <xsd:attribute name="Impl" type="xsd:string"/> </xsd:complexType> The type we want to replace by customization is the one for the attribute Impl which is to be represented by the following enum type. package impl; public enum ImplType { UINT8( 1, false ), INT8( 1, true ), // ... UINT64(4,false), INT3644,true); private final int bytes; private final boolean signed; ImplType( int b, boolean s ) { bytes = b; signed = s; } } The utility class providing the conversions between a string representation and the enum constants is easy. package impl; import java.util.*; public class ImplConv { public static ImplType parseStringToEnum( String value ){ return ImplType.valueOf( ImplType.class, value ); } public static String printEnumToString( ImplType impl ){ return impl.toString(); } } Now we are prepared to set up the bindings file such as the one shown below, in full. Notice the progressive restriction of the scope for the binding specifications, first restricted to a specific schema (i.e., signal.xsd, then to the complex type definition for VariableType, and finally to its Impl attribute node. Also, the binding syntax requires that now, when we're substituting a type of our own for a base type, the <jaxb:javaType> element must be enclosed in a <jaxb:baseType>, and this, in turn, must be wrapped by a <jaxb:property element. <?xml version="1.0" encoding="UTF-8"?> <jaxb:bindings xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xsd="http://www.w3.org/2001/XMLSchema" jaxb:version="2.0"> <jaxb:bindings schemaLocation="signal.xsd" node="/xsd:schema"> <jaxb:schemaBindings>

<jaxb:package name="signal"/> </jaxb:schemaBindings> <jaxb:bindings node="//xsd:complexType[@name='VariableType']"> <jaxb:bindings node="./xsd:attribute[@name='Impl']"> <jaxb:property> <jaxb:baseType> <jaxb:javaType name="impl.ImplType" parseMethod="impl.ImplConv.parseStringToEnum" printMethod="impl.ImplConv.printEnumToString"/> </jaxb:baseType> </jaxb:property> </jaxb:bindings> </jaxb:bindings> </jaxb:bindings> </jaxb:bindings> You can glean the reward of your pains from looking at the generated code for the impl field of VariableType which lets you now deal with this attribute via ImplType enums, e.g.,: ObjectFactory of = new ObjectFactory(); VariableType var = of.createVariableType(); var.setValue( 42 ); var.setImpl( ImplType.INT16 );

6 JAXB Annotations 6.1 How a Schema Mapping Is Implemented The Java code generated by the JAXB schema compiler contains annotations providing metadata on packages, classes, fields and methods. Together, this metadata is intended to reflect the information contained in an XML schema, of which only a very small part can be expressed by the actual Java code. Annotations can be easily retrieved from their target construct with methods contained in classes such as java.lang.Class or java.lang.reflect.Field. Each annotation type has its own set of attributes, which are accessed in the usual way. Given some class, an annotation of type XmlType can be retrieved with Class clazz = ...; XmlType typeAnn = clazz.getAnnotation( XmlType.class ); If the result of the annotation getter is not null, annotation element values may be obtained by calling methods on the returned XmlType object. To retrieve the name of the corresponding XML Schema type you would write String schemaName = typeAnn.name(); Classes that can be used for marshalling and unmarshalling XML need not be generated by the JAXB schema compiler. It is equally possible to write these classes by hand, adding the JAXB annotations. We'll discuss some basic annotations in the next section. 6.2 A Survey Of JAXB Annotations 6.2.1 Top-level Elements: XmlRootElement A class that describes an XML element that is to be a top-level element, i.e., one that can function as an XML document, should be annotated with XmlRootElement. Its optional elements are name and namespace. By default, the class name is used as the name. This annotation corresponds to an xsd:element construct being used at the outermost level of an XML schema. The sequence of Java, XML and schema snippets given below illustrates this relation. @XmlRootElement( name="doc" ) public class Document { @XmlElement protected Foo foo; // ... } <?xml version="1.0" encoding="UTF-8"?> <doc> <foo>...</foo> </doc>

public EntryType(){} public EntryType( String artists.event = event. XmlRootElement may be the only annotation you have to make! Here's a small set of classes. String program ){ this.*. this.xml. XMLGregorianCalendar datetime ){ this. public DocType(){ } } import javax. that is even capable of marshalling a Map<K. import java.util..datatype. } } public class EntryType { public String program.xml.util. public KeyType(){} public KeyType( String event. public XMLGregorianCalendar datetime.HashMap. public String artists. you could produce XML data like so: <doc> .annotation.*. </xsd:complexType> <xsd:complexType name="Document"> <xsd:sequence> <xsd:element name="foo" type="Foo"/> </xsd:sequence> </xsd:complexType> <xsd:element name="doc" type="Document"/> It's a surprising fact that if all of your Java classes permit a straightforward mapping to XML Schema.Map.. import javax.program = program.EntryType> key2entry = new HashMap<KeyType.EntryType>(). @XmlRootElement(name="doc") public class DocType { public Map<KeyType. } } Applying the usual incantations for creating and marshalling content.artists = artists.<?xml version="1. public class KeyType { public String event.0" encoding="UTF-8"?> <xsd:complexType name="Foo"> . this.V>.bind. import java.datetime = datetime.

It must be written on a file package-info.xml.at/hospital". (It's pretty obvious that there can't be a connection between the textual order of items in a class definition and the order its fields are returned by reflection methods. "items". requesting that the elements title.XmlSchema( namespace = "http://www. The string array value defined by propOrder establishes an ordering of the subelements.3 Annotations for the Schema: XmlSchema This annotation can only be used with a package. . } 6.2 Annotation for Classes: XmlType This annotation adds information that would be available from a schema type. The annotation has several attributes: factoryClass and factoryMethod define the class containing a no-argument method for creating an instance of this class as the equivalent of an empty XML element. items and cluster should appear in the given order: @XmlRootElement @XmlType( propOrder={ "title".E. @javax. "cluster" } ) public class Document { . specifying the namespace and elementFormDefault elements.2.laune.java situated in the package.. You can see that JAXB had to "invent" a few tag names for the intermediary element levels separating map entries from each other. but you'd have to do something similar if you'd design it yourself. The attribute name provides the XML schema name if you don't want to use the class name.) Here is an example for XmlType.bind. according to the Schema Datatypes specification.<key2entry> <entry> <key> <event>Soiree</event> <datetime>2008-08-23T20:00:00</datetime> </key> <value> <program>Man on the Moon</program> <artists>R.annotation. 6. Below is an example. and key data from value data. The namespace attribute provides the name of the target namespace.. but isn't implied by a Java class declaration. It defines parameters that are derived from the xsd:schema element. and the 'T' between the date and the time is just right.2.M</artists> </value> </entry> </key2entry> </doc> The XMLGregorianCalendar is mapped to xsd:dateTime.

annotation.class.XmlNs( prefix = "med".at/hospital".bind. value).4 The Object Factory: XmlRegistry.annotation.annotation. } Most objects require nothing but a simple create method. TreeType. annotated with XmlRegistry. namespaceURI = "http://www. The previous example is extended with a namespace definition for the prefix med: @javax.bind. @XmlRegistry public class ObjectFactory { . null. name = "tree") public JAXBElement<TreeType> createTree( TreeType value) { return new JAXBElement<TreeType>(_Tree_QNAME. It contains an array of XmlNs annotations.XmlNsForm.w3.at/hospital" xmlns:xs="http://www.at/med" ) }. } .laune. This annotation is equivalent to an xs:schema element <xs:schema elementFormDefault="qualified" targetNamespace="http://www. Therefore. the unmarshaller must have an object factory with methods for creating all sorts of objects. an additional factory method for wrapping the "pure" Java object of some class Foo into an element of class JAXBElement<Foo> must be provided.annotation.laune..xml. providing the components of the element's tag name through the attributes namespace and name. This method is then annotated with XmlElementDecl.xml. XmlElementDecl To be able to create objects from XML elements.QUALIFIED) package hospital.2.bind. But whenever an element has to be represented as a JAXBElement<?>. elementFormDefault = javax.xml.0" > For defining namespace prefixes you use the xmlns element of the XmlSchema annotation.XmlSchema( namespace = "http://www. xmlns = { @javax.laune.elementFormDefault = javax. each package containing JAXB classes must contain one class ObjectFactory.xml.org/2001/XMLSchema" version="1. 6. This is a snippet from some object factory where an element of TreeType is wrapped into a JAXBElement<TreeType>: @XmlElementDecl(namespace = "".XmlNsForm.bind.at/hospital" xmlns:tns="http://www. This corresponds to using xmlns:med="http://www.QUALIFIED) package hospital..at/med" as an attribute in the xs:schema element.laune.laune. each of which contains a prefix and a namespaceURI element.

5 Controlling Element Selection: XmlAccessorType. } } The corresponding XML schema type definition looks like this: <xs:complexType name="someClass"> <xs:sequence> <xs:element name="a" type="xs:string" minOccurs="0"/> </xs:sequence> </xs:complexType> The second example illustrates the reverse process. } public void setB( String value ){ . The other annotation to be mentioned in this context is XmlTransient. } public String getA(){ . It suppresses binding for its target which can be an entire class or a field or a method. It shows a class with the most restrictive accessor type setting. setting its value element to one of the enum constants FIELD. Any protected.2.PUBLIC_MEMBER ) public class SomeClass { private String a.. You can annotate a package or a top level class with XmlAccessorType. say foo. public getter and setter pairs. public SomeClass(){ . } @XmlTransient public String getB(){ . by default. @XmlAccessorType( XmlAccessType. and methods getFoo and setFoo.NONE ) . @XmlAccessorType( XmlAccessType. If FIELD is set every non static. The first class illustrates a class that restricts the set of XML elements from an accessor type setting of PUBLIC_MEMBER.. or public fields. A class without this annotation inherits the XmlAccessorType setting either from its superclass or from the package setting. You have several possibilities to influence this default behaviour.. } public void setA( String value ){ . private String b. package-visible or private member is bound if it is annotated with a suitable annotation such as XmlElement or XmlAttribute.. NONE suppresses bind except for explicitly annotated fields or properties. PROPERTY instructs JAXB to do this for getter and setter pairs.... all public members will be bound. then. with one member explicitly annotated as an element. i.6.. XmlTransient If JAXB binds a class to XML. PROPERTY. This is also useful if you have a name clash resulting from a public field. non transient field will be automatically bound..e... PUBLIC_MEMBER or NONE. Member getB is blocked from being bound.

... the generated schema snippet is slightly different: <xs:complexType name="otherClass"> <xs:sequence> <xs:element name="b" type="xs:string"/> </xs:sequence> </xs:complexType> The final example for this topic demonstrates using these annotations in somewhat special circumstances. return b. } public void setA( String value ){ . Second.. public OtherClass(){ . XmlElement is used to request binding for getB. private List<String> b. } public void setA( String value ){ . private String b...PUBLIC_MEMBER ) public class SpecialClass { @XmlTransient public String a.. } public String getA(){ .... } } The generated complex type features both elements. <xs:complexType name="specialClass"> <xs:sequence> <xs:element name="a" type="xs:string" minOccurs="0"/> .public class OtherClass { private String a. public SpecialClass(){ .. } public void setB( String value ){ . } public String getA(){ . } } Since we have set the annotation element required to true. } @XmlElement public List<String> getB(){ if( b == null ) b = new ArrayList<String>(). (The getter follows the standard pattern of the JAXB generated Java code for elements bound to List<?>..... XmlTransient is used on the public field to avoid the name clash with the method pair. First. which doesn't have its setB spouse. } @XmlElement( required = true ) public String getB(){ . with changes being made on the list object..) @XmlAccessorType( XmlAccessType.

The typical case where this is required is for the subclasses of some class that is included. this means that you can. whether it is optional or nillable. respectively.2.7. define the strategy for all classes within the package or for all subclasses. required = true) protected List<SysWorkplaceType> workplace.. or you may inhibit bindings using the XmlTransient annotation.2..class} ) class Animal { //.<xs:element name="b" type="xs:string" maxOccurs="unbounded" minOccurs="0"/> </xs:sequence> </xs:complexType> Taken together. and below is the corresponding schema snippet. a default value and the Java class. because they are used as types for a field. This requires that these annotations are assembled in a XmlElements (not the plural "s") annotation that merely acts as a container. the namespace. It permits you to define the XML element name. 6.1 The Annotation XmlElement The basic annotation for a field that's intended to be an element is XmlElement. @XmlElement(name = "Workplace". there is a gap between what can be defined in an XML schema and the information available from field definitions within a Java class. Cat. more than one @XmlElement may have to be associated with this field. } 6. in contrast to those classes that are statically referenced. oriented on fields or properties. e. Here are two annotated fields. either at package level or at some superclass. i. as shown in the example below: @XmlSeeAlso( {Dog. required = true) protected PreambleType preamble. You use XmlSeeAlso on some class. or restrictive. the ones that are bound to schema elements.g. <xsd:sequence> <xsd:element name="Preamble" type="com:PreambleType"/> <xsd:element name="Workplace" type="SysWorkplaceType" minOccurs="1" maxOccurs="unbounded"/> </xsd:sequence> If a field has some collection type. @XmlElement(name = "Preamble".e. This strategy may be generally permissive. In the .7 Annotations for Fields Fields of a class may correspond to XML elements.2. Once more. permitting nothing by default. Within a class.. you may extend a restrictive setting by adding XmlElement or XmlAttribute. 6.class..6 Class Inclusion: XmlSeeAlso The annotation XmlSeeAlso instructs JAXB to include the specified classes in the set of recognized classes.

type = CheckBoxType. The annotated class Sentence @XmlType class Sentence { @XmlElement List<String> word.7. } results in <sentence> <word>This is terse</word> </sentence> Needless to say.class). @XmlElement(name = "Menu". the addition of XmlList @XmlType class Sentence { @XmlElement @XmlList List<String> word. using the XML representation of lists for strings is risky unless you . type = ItemType. 6.2 The Annotation XmlList The attribute XmlList instructs JAXB that a list value is to be represented as a blank separated list of values of some simple type rather than a list of individual child elements.2.class). the field entryOrChoiceOrCascade is a collection composed from objects of three different classes. } produces XML such as <sentence> <word>This</word> <word>is</word> <word>verbose</word> </sentence> In contrast. @XmlType(name = "MenuType") public class MenuType extends ItemType { @XmlElements({ @XmlElement(name = "Item". type = MenuType. } As a bonus you may avoid the complicated name for the list element that JAXB concocts from the first three possibles. @XmlElement(name = "CheckBox".class definition below.class) }) protected List entryList.

@XmlAttribute final static int answer = 42. public Price(){} @XmlElement .A "true" value of required is the same as using the XML Schema definition's attribute use="required". List<Sentence> word. the schema describing the XML Schema language itself.Sentence isn't a simple type.) 6.) JAXB. making judicious use of both.can be sure that no string value contains a blank. Now consider this simple Java class with a single instance variable: public class Price { private BigDecimal amount. The annotation for creating an XML attribute is XmlAttribute.7. This has the same effect as an XML Schema definition where the attribute element's attribute fixed is set to that value. then the simple answer is: "Do it yourself. If you ask about some way for defining the equivalent for the XML Schema attribute default="value". Its elements correspond to what can be defined in an XML schema: -.4 Mapping a Class to Simple Content or Simple Type: XmlValue Usually a Java class results in a complex type. (If you look for guidance. which is only valid for types that are simple according to XML Schema rules. -. of course.7. the default being the class field's name. A class such as Paragraph @XmlType class Paragraph { @XmlElement @XmlList // Not valid .2. remember the restriction for XML Schema's xsd:list. with one element or attribute for each field. is a good example.name defines the namestring for the attribute. 6. -.3 Class Fields as Attributes: XmlAttribute Provided that XML lets you represent a data item as a single value.namespace specifies the XML target namespace to be used for the attribute's name. there is no cutand-dried rule for deciding between using an element or an attribute. Also.2. has to be told when to make a field into an XML attribute. It's possible to annotate a static final field with XmlAttribute. (The Java compiler has no way of knowing that something is amiss here." Just write the getter so that it returns the default value if the field's value is null. } is bound to fail as soon as JAXB inspects the annotations.

e. } } If this type is used for some field. } public void setAmount( BigDecimal value ){ this.public BigDecimal getAmount(){ return amount.. @XmlValue public BigDecimal getAmount(){ return amount. or have no explicit mapping to some field in the Java class defining the element type.2.g.. too.45</amount> </price> What is required here is a way of telling JAXB to map class Price to a simple schema type. .45</price> Notice that fields of type Price could now be mapped to an XML attribute.amount = value. } This is now equivalent to this simple type definition: <xs:simpleType name="price"> <xs:restriction base="xs:decimal"/> </xs:simpleType> The XML data is pleasantly reduced to: <price>123..: <price> <amount>123.. } // . the result will be according to this XML Schema type definition: <xs:complexType name="price"> <xs:sequence> <xs:element name="amount" type="xs:decimal" minOccurs="0"/> </xs:sequence> </xs:complexType> The marshalled XML data is unnecessarily complicated due to an addtional element layer.7. This is done by annotating the single field amount with XmlValue instead of XmlElement: public class Price { // . 6.5 Collecting Unspecified Attributes: XmlAnyAttribute An XML element may carry attributes which aren't defined in the XML schema.

getValue() + """ ).out. the sub-element and its spurious attributes can be extracted like this: JAXBElement<DocumentType> jbe = (JAXBElement)u.getKey() + "="" + e.Object> getAny(){ if( any == null ){ any = new HashMap<QName. Then.Entry<QName.getTitle() ). DocumentType doc = jbe.println( "Title: " + mix.getMixture().out.Object>().getAny(). } This is the resulting output: A mixture of elements foo="a foo attribute" .Object> e: amap.entrySet() ){ System. for( Map.It's possible to collect these unspecified attributes into a map with the type Map<QName. MixtureType mix = doc. } return any.getValue(). public MixtureType(){} @XmlAnyAttribute public Map<QName.xml" ) ).Object> amap = mix. } } Let's assume that the top level element of type DocumentType contains nothing but one MixtureType element. Here is an example using the annotation XmlAnyAttribute: public class MixtureType { private Map<QName.println( e. private String title.Object> any. } public void setTitle( String value ){ title = value. Map<QName. } @XmlElement public String getTitle(){ return title. System.Object>.unmarshal( new File( "mixture. an XML data file that can be unmarshalled into an object of this class would look like this: <document> <mixture foo="a foo attribute" bar="attribute of bar"> <title>A mixture of elements</title> </mixture> </document> After unmarshalling this into a DocumentType object.

g.util.: <document> <zoo> <a>Anaconda</a> <b>Buffalo</b> <c>Chameleon</c> <d>Dromedar</d> </zoo> </document> The interesting class is ZooType. DocumentType doc = (DocumentType)u.getNodeName() + "->" + el.bind.unmarshal( f ).w3c.Element.getTextContent() ).2.7. } public void setAnimals( List value ){ animals = value. or an array or list of such elements. for( Element el: doc.println( el. (We have already seen that this corresponds to an object of type org.dom. public ZooType(){ } @XmlAnyElement public List<Element> getAnimals(){ if( animals == null ) animals = new ArrayList<Element>().*.createUnmarshaller(). return animals. } .dom.class ).xml.annotation. defining the structure of the element tagged zoo as a list of DOM elements: import java. public class ZooType { protected List<Element> animals. cf.newInstance( DocumentType. e. Unmarshaller u = jc.getZoo().Element. Let's say that we want to unmarshal XML data with arbitrary tags and some text content.w3c. } } Unmarshalling and accessing this data is done like this: JAXBContext jc = JAXBContext. import org.out.) The annotation XmlAnyElement instructs JAXB to map a field to a DOM Element object. import javax.getAnimals() ){ System. subsection DOM Elements.bar="attribute of bar" 6.*.6 Collecting Unspecified Elements: XmlAnyElement Arbitrary content is indicated by the XML Schema type xsd:anyType.

i. Here is a schema snippet for a complex type with mixed content: <xs:complexType name="MessageType" mixed="true"> <xs:sequence> <xs:element name="id" type="xs:int"/> <xs:element name="code" type="CodeType"/> </xs:sequence> </xs:complexType> . child elements embedded in the element's own data. JAXB binds such a type to a class containing a single list attribute typed List<JAXBElement>. as indicated in the XML snippet below. @XmlType( name="ParentType" ) public class ParentType { protected List item. with one field for each element and attribute.e. you need some additional element bracketing. for the repeated element. <parent> <wrapper> <item>A</item> <item>B</item> <item>C</item> </wrapper> </parent> You instruct JAXB to generate this additional element by adding the annotation XmlElementWrapper to a collection type attribute.2. and another one for the content text. cannot be bound to a class in the usual bean style. return item. or "wrapping".. public ParentType(){ .7. Doing so would lose the order of the sub-elements and the chunks of content text wherein they are embedded. } @XmlElement( name="item" ) @XmlElementWrapper( name="wrapper" ) public List getItem(){ if( item == null ) item = new ArrayList(). } } 6.. XmlMixed An XML complex type with mixed content.2..7 Wrapping Repeated Elements: XmlElementWrapper With a repeatable XML element you may want to distinguish between a list that is absent and an empty list.8 Annotations for Mixed Content: XmlElementRef. For this.The resulting output looks like this: a->Anaconda b->Buffalo c->Chameleon d->Dromedar 6.7.

@XmlElementRef(name = "code". } return this. type = JAXBElement.FIELD) @XmlType(name = "MessageType".class) }) protected List<JAXBElement<?>> content. Below is a slightly modified version of the schema snippet for the complex type MessageType. type = JAXBElement. you'll have to distinguish between JAXBElement objects for the sub-elements and String objects for the chunks of the content of the element itself. @XmlAccessorType(XmlAccessType. propOrder = { "content" }) public class MessageType { @XmlElementRefs( { @XmlElementRef(name = "code".content. When you process the elements of the content list after unmarshalling.class). @XmlElementRef(name = "id". which doesn't have mixed content any more.class) }) @XmlMixed protected List<Serializable> content. type = JAXBElement. A similar but rarely encountered situation is created by duplicating an element in a sequence. } } The generic parameter for the content list is Serializable. except that XmlMixed is omitted and the generic parameter for List should be JAXBElement<?>. you would write an annotated Java class like this: @XmlAccessorType(XmlAccessType. @XmlElementRef(name = "id".To achieve the same effect with an annotated class. public List<Serializable> getContent() { if (content == null) { content = new ArrayList<Serializable>(). type = JAXBElement. public List<JAXBElement<?>> getContent() { .FIELD) @XmlType(name = "Message".class). propOrder = { "content" } ) public class Message { @XmlElementRefs({ @XmlElementRef(name = "id". but contains a repetition of element id (ours not to worry why): <xs:complexType name="MessageType"> <xs:sequence> <xs:element name="id" type="xs:int"/> <xs:element name="code" type="CodeType"/> <xs:element name="id" type="xs:int"/> </xs:sequence> </xs:complexType> The annotated Java code would be similar to the one shown previously.class). slightly more specific than Object. type = JAXBElement.

this is sufficient: @XmlEnum public enum SubElemType { //. even numeric ones.(more enum constant definitions) private final String value. with arbitrary alternations of all three elements.String but other types. 6. Such a deluxe version of an enum type is shown below.content. It has an optional element value of type java. XmlEnumValue An enum type is annotated with XmlEnum.lang.lang. } public String value() { return value. Its required element defines the XML representation string. Usually. provide a getter for the XML string and perhaps even a lookup function (fromValue) to convert a string to the enum constant...8 Annotations for Enums: XmlEnum.2.. SubElemType(String v) { value = v. this is java. // .(enum definition) } Individual enum constants have to be annotated if there is a difference between the Java name and the string used to represent the value in XML. This is defined with an @XmlEnumValue annotation that is attached to individual enum constants. For a straightforward enum type.if (content == null) { content = new ArrayList<JAXBElement<?>>().Class which defines the class used for the values used in the XML representation. @XmlEnum public enum SubElemType { @XmlEnumValue("PrMaSig") PR_MA_SIG("PrMaSig"). } return this. } } This does. marshal or unmarshal many more sub-element sequences than the one shown in the schema snippet. and by default.. @XmlEnumValue("Track1") TRACK_1("Track1"). the enum type might define the XML representation as a parameter for the constructor. If it might be useful for the Java application to have support for the conversion between Java values and XML representations as well. are equally possible. in fact. } public static SubElemType fromValue(String v) { .

the class Courses containing a simple array of Course objects. } } @XmlJavaTypeAdapter(BrochureAdapter.45" id="c0"> <name>Course 0</name> </course> </brochure> </ns:training> The course elements could be represented as a list or array. i.adapters. Here is an XML example of the data we have to deal with. @XmlRootElement(name="training") public class Training { @XmlElement public Brochure brochure. To achieve our goal. Also.for (SubElemType c: SubElemType.ApplType> from the package javax. Although JAXB is capable of handling maps.2. but we would like to process this data in our application as a map of the id attribute to the Course object.45" id="c1"> <name>Course 1</name> </course> <course price="123. We'll illustrate adapters by defining a substitution of a map for an array.values()) { if (c. we write a class Brochure containing the map we have in mind and declare that this is the one that has to be adapted to something JAXB knows how to handle. } } 6.equals(v)) { return c. } } throw new IllegalArgumentException(v. you may want to represent Java types in a way that is entirely different from what JAXB is apt to do.annotation. public Training(){} public Training( Brochure b ){ brochure = b.9 Type Adapters: XmlJavaTypeAdapter For some Java container types JAXB has no built-in mapping to an XML structure. written as an extension of XmlAdapter<XmlType.class) .0" encoding="UTF-8" standalone="yes"?> <ns:training xmlns:ns="http://foo/bar"> <brochure> <course price="123.e.xml. we have seen (in section Top-level Elements: XmlRootElement) that the resulting XML structure isn't as simple as possible.bind.value. Such mappings require an adapter class. The annotation XmlJavaTypeAdapter is provided for announcing the adapter in the desired place. <?xml version="1..toString()).

public class Brochure { Map<String. } } public class Courses { @XmlElement(name="course") public Course[] carray.carray ) b. whereas application programming uses the Map type field courses in class Brochure. c ). Course>(). } } Courses is a class JAXB knows how to handle with respect to XML data. return courses.Brochure> { @Override public Brochure unmarshal( Courses value ){ Brochure b = new Brochure().id. for( Course c : value.values().courses. which is easily done by putting the map values into an array. defining class BrochureAdapter as its adapter.courses.carray = c. To summarize: XML binding happens against the class Courses. courses. In this method. } public class Course { @XmlAttribute String id. and the result of JAXB's innate capabilities is passed to the adaption for unmarshalling. we convert the data to a structure according to the desired class Brochure with its map.toArray(new Course[c. It has to override methods unmarshal and marshal.Course> courses.put( c. public Brochure() { courses = new HashMap<String. @XmlElement String name. the interesting class. Collection<Course> c = b. } @Override public Courses marshal( Brochure b ){ Courses courses = new Courses(). public class BrochureAdapter extends XmlAdapter<Courses. } Class Brochure is annotated with XmlJavaTypeAdapter.size()]). return b. . and this is. The reverse marshalling process has to convert a Brochure object with its map to a Courses object. @XmlAttribute Price price. of course.

one defining TextType as a container for a string. If you need multiple mappings at package level." ). Such a type mapping can be defined either for an individual element or for all occurrences within a package. Let's assume that the processing of chunks of text requires their extension.lang. a StringBuffer is better than String. but every now and then an alternative may be more convenient. and XmlIDREF is attached to any field that references objects of that class. text. For this. } public class String2StrBuf extends XmlAdapter<String. either after unmarshalling or before the emitting marshalling. Two annotations instruct JAXB to use references: XmlID must define a field of some class with type java. XmlJavaTypeAdapter. Most of the time the default mapping is satisfactory..: TextType text = new TextType().strbuf = new StringBuffer( "This is the house" ). // . public class TextType { @XmlElement @XmlSchemaType(name="string") @XmlJavaTypeAdapter( String2StrBuf.toString().2.11 Annotations for Object References: XmlID.append( " that Jack built. Both annotations may be used in addition to XmlElement. and the type adapter class for the simple conversion between String and StringBuffer.String that is suited to be used as a key. XmlIDREF The section Referring to Another XML Element describes the usefulness of using references rather than repeatedly serialized content.. TextType elements are now StringBuffers. Notice that the latter class is specified in a separate annotation. text. } @Override public StringBuffer unmarshal( String string ){ return new StringBuffer( string ).. i.10 Type Mapping: XmlSchemaType The annotation XmlSchemaType defines a mapping between an arbitrary Java type and a simple schema built-in type.class ) public StringBuffer strbuf.e.StringBuffer> { @Override public String marshal( StringBuffer strbuf ){ return strbuf.strbuf. Below are the essential Java classes. 6. which is the default mapping for xs:string.6. e.g.2. } } Within the Java code that unmarshals or marshals an instance document. and the XmlJavaTypeAdapter annotiations are packed into a single XmlJavaTypeAdapters annotation. you'll have to bundle the XmlSchemaType annotations in an XmlSchemaTypes (note the plural) annotation. .

} } import java. public class Item { private String id..annotation. In this case.annotation. public Item(){} @XmlID public String getId(){ .Set. The latter contains a list of existing items and a Cluster object that wraps a Set<Item> field containing references to some of the items from the list.We'll illustrate an application of these annotations in a somewhat more sophisticated pattern resulting from the possibility of attaching XmlIDREF to a field of some collection type. import java. Below is a group of Java classes defining an Item class and a Document class. private String name. } } package elset.util.HashSet. public Cluster(){ . import javax.. } @XmlIDREF public Set<Item> getItems(){ ..annotation.*.*..util.bind. import java..ArrayList.. import javax. import java. @XmlRootElement public class Document { . import javax.util. private String title.xml.. } @XmlElement public String getName(){ .bind.... the collection item type must contain an id field.*.xml.bind. } public void setId( String value ){ .util. } public void setName( String value ){ . public class Cluster { private Set<Item> items..xml.List..

} } --... private String title.. private List<Item> items. } public void setTitle( String value ){ .END --- .. } @XmlElement public Cluster getCluster(){ .private Cluster cluster.. } @XmlElement public String getTitle(){ ..... } @XmlElement public List<Item> getItems(){ . } public void setCluster( Cluster value ){ ... public Document(){ ..

Sign up to vote on this title
UsefulNot useful