An unmarshaller is used to read XML and build an object tree from classes generated by the compiler. To read an XML file, you would simply do
Unmarshaller unmarshaller = context.createUnmarshaller();
MyObject o = (MyObject)unmarshaller.unmarshal(new File("foo.xml"));
There are other overloaded versions that take different types of input, such as
InputStream or
InputSource. You can even unmarshal a
javax.xml.transform.Source object. All in all, it's similar to the way DOM trees are parsed.
In the previous version of JAXB, this functionality was provided as a method on the generated class. Since one cannot add methods to existing classes, this design made it impossible to unmarshal them. By moving it into a separate
Unmarshaller interface, the new API makes it possible to support this in a future version.
JAXB also supports unmarshalling via a SAX
ContentHandler. You can send SAX events to the unmarshaller and have it unmarshal objects. This enhances the connectivity of the
Unmarshaller considerably. For example, you can parse the header of a message by using JAXB and send the body of the message to another component. With
ContentHandler support, this can be done efficiently.
By default,
Unmarshaller is very forgiving. Even if a document is invalid, it tries to recover from errors. If the document is so broken that it cannot be read, an
UnmarshalException will be thrown.
It's often desirable to get more information about errors or reject documents with errors. The first step to do this is to set
ValidationEventHandler to the
Unmarshaller. A
ValidationEventHandler can explicitly tell a JAXB implementation whether it should reject a document or try to recover from errors. It also gives you more information, such as line numbers, about errors.
An
Unmarshaller can validate a document with the schema while unmarshalling. With this option turned on, it rejects anything short of a valid document. However, W3C XML Schema validation can be very costly.
Another possibility is to set up a SAX pipeline in such a way that your XML parser does the validation; alternately, you could install a stand-alone validator in the pipeline (such as
JARV: validation API). In this way, for example, you can change your schema to change what you get from the compiler, while maintaining the scrutiny of the original schema.
