EclipseLink/Release/2.4.0/JAXB RI Extensions/XML Location

Design Documentation: @XmlLocation

ER 355766

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 field 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.

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.

Annotations

package org.eclipse.persistence.oxm.annotations;
 
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
 
@Target({METHOD, FIELD}) 
@Retention(RUNTIME)
public @interface XmlLocation {}

Example

import javax.xml.bind.annotation.XmlRootElement;
import org.xml.sax.helpers.LocatorImpl;
import com.sun.xml.bind.annotation.XmlLocation;
 
@XmlRootElement
public class Customer {
 
   public String name;
   public int id;
 
   @XmlLocation
   public LocatorImpl locator;
 
}

OXM Metadata

eclipselink_oxm_2_4.xsd:

...
    <xs:element name="xml-transient" substitutionGroup="java-attribute">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="java-attribute">
                    <xs:attribute name="xml-location" type="xs:boolean" default="false" />
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
...
    <xs:element name="xml-element" substitutionGroup="java-attribute">
        <xs:complexType>
            <xs:complexContent>
                <xs:extension base="java-attribute">
                    ...
                    <xs:attribute name="xml-location" type="xs:boolean" default="false" />
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:element>
...

Example

...
    <java-types>
        <java-type name="Customer">
            <xml-root-element />
            <java-attributes>
                <xml-element java-attribute="name" />
                <xml-element java-attribute="id" />
                <xml-element java-attribute="locator" xml-location="true" />
            </java-attributes>
        </java-type>
    </java-types>
...

Config Options

The @XmlLocation feature does not expose any configuration options, it is merely a tagging annotation that indicates the property to be used for tracking XML location information.

Design

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Document History

Date	Author	Version Description & Notes
110926	Rick Barkhouse	1.00 : First draft