Difference between revisions of "EclipseLink/Release/2.4.0/JAXB RI Extensions/ID Resolver"

From Eclipsepedia

Jump to: navigation, search
Line 91: Line 91:
 
= Appendix A - Example IDResolver =
 
= Appendix A - Example IDResolver =
  
From [http://weblogs.java.net/blog/kohsuke/archive/2005/08/pluggable_ididr.html]
+
From [http://weblogs.java.net/blog/kohsuke/archive/2005/08/pluggable_ididr.html Pluggable ID/IDREF handling in JAXB 2.0]
  
 
<div style="width:800px">
 
<div style="width:800px">

Revision as of 14:02, 18 October 2011

Design Documentation: IDResolver

ER 360249

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 abstract class IDResolver provided in the Sun JAXB implementation allows users to override the ID/IDREF processing of the JAXB runtime.

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


Requirements

  • Deliver an abstract IDResolver class in the EclipseLink library that will provide the same functionality as the Sun extension.
    • Given a String id and Object obj, allow the user to perform custom bind code
    • Given a String id and Class type, allow the user to perform custom resolve code
    • Provide the user a hook into startDocument() and endDocument() events


Behaviour

If an IDResolver has been set on the Unmarshaller (via properties), then the following things must happen during unmarshal:

  • The IDResolver's startDocument() method must be called when unmarshalling starts.
  • When an ID value is encountered during unmarshal, the IDResolver's bind method must be called, to bind the object to the ID.
  • When an IDREF value is encountered during unmarshal, the IDResolver's resolve method must be used to obtain the object for the IDREF.
  • The IDResolver's endDocument() method must be called when unmarshalling completes.


Configuration

The user must extend the following abstract class:

package org.eclipse.persistence.jaxb;
 
import java.util.concurrent.Callable;
 
import javax.xml.bind.ValidationEventHandler;
 
import org.xml.sax.SAXException;
 
public abstract class IDResolver {
 
    public abstract Callable<?> resolve(String id, Class type) throws SAXException;
 
    public abstract void bind(String id, Object obj) throws SAXException;
 
    public void startDocument(ValidationEventHandler eventHandler) throws SAXException {
    }
 
    public void endDocument() throws SAXException {
    }
 
}


OPEN ISSUE: Should we include additional support for non-String, and composite keys? If so, should we include additional bind()/resolve() methods, or force the user to change to a new method signature?


The user's IDResolver class can then be passed to the EclipseLink Unmarshaller through the addProperty() method:

...
JAXBContext ctx = ...
Unmarshaller u = ctx.createUnmarshaller();
u.setProperty(IDResolver.class.getName(), new MyIDResolver());
...


XML Bindings

???


Examples

Design

Appendix A - Example IDResolver

From Pluggable ID/IDREF handling in JAXB 2.0

import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.Callable;
 
import com.sun.xml.bind.IDResolver;
 
class MyIDResolver extends IDResolver {
    Map<String, Apple> apples = new HashMap<String, Apple>();
    Map<String, Orange> oranges = new HashMap<String, Orange>();
 
    void startDocument() {
        apples.clear();
        oranges.clear();
    }
 
    public void bind(String id, Object obj) {
        if (obj instanceof Apple)
            apples.put(id, (Apple) obj);
        else
            oranges.put(id, (Orange) obj);
    }
 
    public Callable resolve(final String id, final Class targetType) {
        return new Callable() {
            public Object call() {
                if (targetType == Apple.class)
                    return apples.get(id);
                else
                    return oranges.get(id);
            }
        };
    }
}

Document History

Date Author Version Description & Notes
111007 Rick Barkhouse 1.00 : First draft
111017 Rick Barkhouse 1.01 : Considering possibility of supporting complex PKs