Design Documentation: @XmlLocation

In the current JAXB RI, developed by Sun, there are a series of "proprietary" JAXB extensions that are available to provide advanced JAXB functionality outside of the JAXB spec (these extension classes reside in the com.sun.xml.bind package).

The @XmlLocation annotation is one of these extensions - it allows the user to specify a property on the JAXB object that will be updated (upon unmarshalling) with that object's XML location information (i.e. the line number, column number, and system ID that points to this object's location in the XML input).

This document will outline the design for an EclipseLink equivalent to this extension.

Requirements

Deliver an @XmlLocation annotation in the EclipseLink library that will provide the same functionality as the Sun extension.

Line number

Column number

System ID, if applicable

Have zero impact on memory/performance if the user is not using @XmlLocation.

Behaviour

If an object containing an @XmlLocation property is unmarshalled, a Locator object will be created and set on the property, containing the XML location info.

If an object with a populated Locator is marshalled to XML, the Locator information will appear in the resultant XML.

If XML is unmarshalled that contains actual Locator information (e.g. the example above), that information is not read in like a normal mapping; upon unmarshalling the Locator property will be set to reflect the current XML location.

If an @XmlLocation property is also marked as @XmlTransient, then Locator information will NOT appear in marshalled XML.

Not all unmarshal sources will be able to provide XML location information. For example, unmarshalling from a File would be able to give you line, column and system ID (filename); system ID is not available when unmarshalling from an InputStream; unmarshalling from a Node would give you no XML location information at all.

Unmarshal Source

Line #

Col #

Sys ID

java.net.URL

java.io.File

java.io.InputStream

Configuration

In order to use @XmlLocation, the user must first have a property on their Java object (either a field or get/set pair) of type
org.xml.sax.Locator. The user can then specify that this property should be used to track XML location by using either EclipseLink Annotations or XML Bindings.

When a Customer is unmarshalled, the Locator field is automatically set to contain the XML location information for that object. By default, if that object was then marshalled back to XML, the XML location information would be written out as well.

Example 2

In most cases, you would not want XML location information written out during marshal, as this information reflects the location the object was unmarshalled FROM, not the location it is being marshalled TO. If XML location is encountered when unmarshalling XML, it would be ignored anyway, and instead the "fresh" XML location information would be used instead.

To avoid writing out XML location during marshal operations, you can additionally annotate your @XmlLocation property with @XmlTransient (or, in XML Bindings, use "xml-transient" instead of "xml-element"):