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

From Eclipsepedia

Jump to: navigation, search
 
(20 intermediate revisions by one user not shown)
Line 1: Line 1:
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
  
= Design Documentation: ID Resolver =
+
= ID Resolver =
  
[http://bugs.eclipse.org/360249 ER 360249]
+
In the current JAXB RI, developed by Sun, there is a series of "proprietary" JAXB extensions which provide advanced functionality outside of the JAXB specification (these extension classes and properties reside in the '''com.sun.xml.bind''' package).
 
+
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.
 
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 <tt>id</tt> and Object <tt>obj</tt>, allow the user to perform custom <tt>bind</tt> code
 
** Given a String <tt>id</tt> and Class <tt>type</tt>, allow the user to perform custom <tt>resolve</tt> code
 
** Provide the user a hook into <tt>startDocument()</tt> and <tt>endDocument()</tt> events
 
 
* Unlike Sun's JAXB implementation, EclipseLink MOXy is not restricted to String-only IDs.  Therefore, we will include additional functionality to support complex IDs.
 
** Given a Map of ID names/values and Object <tt>obj</tt>, allow the user to perform custom <tt>bind</tt> code
 
** Given a Map of ID names/values and Class <tt>type</tt>, allow the user to perform custom <tt>resolve</tt> code
 
 
* Provide drop-in-replacement support, so that users already using the Sun implementation will not need to change their code when switching to EclipseLink.
 
  
  
Line 38: Line 20:
 
= Configuration =
 
= Configuration =
  
The user must extend the following abstract class:
+
The user must extend the '''org.eclipse.persistence.jaxb.IDResolver''' class and implement the following abstract methods (<tt>startDocument</tt> and <tt>endDocument</tt> are optional):
  
<div style="width:800px">
+
<div style="width:900px">
 
<source lang="java">
 
<source lang="java">
package org.eclipse.persistence.jaxb;
+
public abstract Callable<?> resolve(Object id, Class type) throws SAXException;
  
import java.util.concurrent.Callable;
+
public abstract Callable<?> resolve(Map<String, Object> id, final Class type) throws SAXException;
  
import javax.xml.bind.ValidationEventHandler;
+
public abstract void bind(Object id, Object obj) throws SAXException;
  
import org.xml.sax.SAXException;
+
public abstract void bind(Map<String, Object> id, Object obj) throws SAXException;
  
/**
+
public void startDocument(ValidationEventHandler errorHandler) throws SAXException {}
* IDResolver can be subclassed to allow customization of the ID/IDREF processing of
+
* JAXBUnmarshaller.
+
*
+
* @see JAXBUnmarshaller
+
*/
+
public abstract class IDResolver {
+
  
    public abstract Callable<?> resolve(Object id, Class type) throws SAXException;
+
public void endDocument() throws SAXException {}
 
+
    public abstract Callable<?> resolve(Map<String, Object> id, Class type) throws SAXException;
+
 
+
    public abstract void bind(Object id, Object obj) throws SAXException;
+
 
+
    public abstract void bind(Map<String, Object> id, Object obj) throws SAXException;
+
 
+
    public void startDocument(ErrorHandler errorHandler) throws SAXException {}
+
 
+
    public void endDocument() throws SAXException {}
+
 
+
}
+
 
</source>
 
</source>
 
</div>
 
</div>
Line 76: Line 40:
 
The user's '''IDResolver''' class can then be passed to the '''Unmarshaller''' through the <tt>setProperty()</tt> method:
 
The user's '''IDResolver''' class can then be passed to the '''Unmarshaller''' through the <tt>setProperty()</tt> method:
  
<div style="width:800px">
+
<div style="width:900px">
 
<source lang="java">
 
<source lang="java">
 
...
 
...
 
JAXBContext ctx = ...
 
JAXBContext ctx = ...
 
Unmarshaller u = ctx.createUnmarshaller();
 
Unmarshaller u = ctx.createUnmarshaller();
u.setProperty(org.eclipse.persistence.jaxb.JAXBContext.ID_RESOLVER, new MyIDResolver());
+
u.setProperty(UnmarshallerProperties.ID_RESOLVER, new MyIDResolver());
 
...
 
...
 
</source>
 
</source>
Line 88: Line 52:
 
'''Note:''' EclipseLink also supports Sun's IDResolver property names:
 
'''Note:''' EclipseLink also supports Sun's IDResolver property names:
  
<div style="width:850px">
+
<div style="width:900px">
 
<source lang="java">
 
<source lang="java">
 
m.setProperty("com.sun.xml.bind.IDResolver", new MyResolver());
 
m.setProperty("com.sun.xml.bind.IDResolver", new MyResolver());
Line 95: Line 59:
 
</div>
 
</div>
  
Also note that if you are using a Sun IDResolver with EclipseLink, it will be unable to support EclipseLink's multiple XML IDs feature.  In this case, you should re-implement your IDResolver as a subclass of org.eclipse.persistence.jaxb.IDResolver.
+
Also note that if you are using a Sun IDResolver with EclipseLink, it will be unable to support EclipseLink's multiple XML IDs feature.  In this case, you should re-implement your IDResolver as a subclass of '''org.eclipse.persistence.jaxb.IDResolver'''.
  
== XML Bindings ==
 
  
Because IDResolver is an Unmarshaller property, there is no configuration in XML Bindings.
+
= Appendix A - Example IDResolver =
  
 +
<div style="width:925px">
 +
<source lang="java">
 +
import java.util.LinkedHashMap;
 +
import java.util.Map;
 +
import java.util.concurrent.Callable;
  
= Examples =
+
import javax.xml.bind.ValidationEventHandler;
  
 +
import org.eclipse.persistence.jaxb.IDResolver;
  
= Design =
+
import org.xml.sax.SAXException;
  
 +
public class MyIDResolver extends IDResolver {
 +
  Map<Map<String, Object>, Apple> apples = new LinkedHashMap();
 +
  Map<Map<String, Object>, Orange> oranges = new LinkedHashMap();
  
= Appendix A - Example IDResolver =
+
  @Override
 +
  public void startDocument(ValidationEventHandler eventHandler) throws SAXException {
 +
      apples.clear();
 +
      oranges.clear();
 +
  }
  
From [http://weblogs.java.net/blog/kohsuke/archive/2005/08/pluggable_ididr.html Pluggable ID/IDREF handling in JAXB 2.0]
+
  @Override
 +
  public void endDocument() throws SAXException {
 +
  }
  
<div style="width:800px">
+
  @Override
<source lang="java">
+
  public void bind(Map<String, Object> idWrapper, Object obj) throws SAXException {
import java.util.HashMap;
+
      if (obj instanceof Apple) {
import java.util.Map;
+
          ((Apple) obj).processed = true;
import java.util.concurrent.Callable;
+
          apples.put(idWrapper, (Apple) obj);
 +
      } else {
 +
          ((Orange) obj).processed = true;
 +
          oranges.put(idWrapper, (Orange) obj);
 +
      }
 +
  }
  
import com.sun.xml.bind.IDResolver;
+
  @Override
 +
  public Callable<Object> resolve(final Map<String, Object> idWrapper, final Class type) throws SAXException {
 +
      return new Callable<Object>() {
 +
          public Object call() {
 +
              if (type == Apple.class) {
 +
                  return apples.get(idWrapper);
 +
              } else {
 +
                  return oranges.get(idWrapper);
 +
              }
 +
          }
 +
      };
 +
  }
  
class MyIDResolver extends IDResolver {
+
  @Override
    Map<String, Apple> apples = new HashMap<String, Apple>();
+
  public void bind(Object id, Object obj) throws SAXException {
    Map<String, Orange> oranges = new HashMap<String, Orange>();
+
      Map<String, Object> idMap = new LinkedHashMap<String, Object>(1);
 +
      idMap.put("stringId", id);
 +
      bind(idMap, obj);
 +
  }
  
    void startDocument() {
+
  @Override
        apples.clear();
+
  public Callable<?> resolve(Object id, Class type) throws SAXException {
        oranges.clear();
+
      Map<String, Object> idMap = new LinkedHashMap<String, Object>(1);
    }
+
      idMap.put("stringId", id);
 +
      return resolve(idMap, type);
 +
  }
  
    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);
 
            }
 
        };
 
    }
 
 
}
 
}
 
</source>
 
</source>
 
</div>
 
</div>
 
= Document History =
 
{|{{BMTableStyle}}
 
|-{{BMTHStyle}}
 
! Date
 
! Author
 
! Version Description & Notes
 
|-
 
| 111007
 
| Rick Barkhouse
 
| 1.00 : First draft
 
|-
 
| 111017
 
| Rick Barkhouse
 
| 1.01 : Considering possibility of supporting complex IDs
 
|-
 
| 111020
 
| Rick Barkhouse
 
| 1.02 : Revising design to support complex (non-String, composite) IDs
 
|}<br>
 

Latest revision as of 11:36, 18 June 2012

[edit] ID Resolver

In the current JAXB RI, developed by Sun, there is a series of "proprietary" JAXB extensions which provide advanced functionality outside of the JAXB specification (these extension classes and properties 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.


[edit] 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.


[edit] Configuration

The user must extend the org.eclipse.persistence.jaxb.IDResolver class and implement the following abstract methods (startDocument and endDocument are optional):

public abstract Callable<?> resolve(Object id, Class type) throws SAXException;
 
public abstract Callable<?> resolve(Map<String, Object> id, final Class type) throws SAXException;
 
public abstract void bind(Object id, Object obj) throws SAXException;
 
public abstract void bind(Map<String, Object> id, Object obj) throws SAXException;
 
public void startDocument(ValidationEventHandler errorHandler) throws SAXException {}
 
public void endDocument() throws SAXException {}

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

...
JAXBContext ctx = ...
Unmarshaller u = ctx.createUnmarshaller();
u.setProperty(UnmarshallerProperties.ID_RESOLVER, new MyIDResolver());
...

Note: EclipseLink also supports Sun's IDResolver property names:

m.setProperty("com.sun.xml.bind.IDResolver", new MyResolver());
m.setProperty("com.sun.xml.internal.bind.IDResolver", new MyResolver());

Also note that if you are using a Sun IDResolver with EclipseLink, it will be unable to support EclipseLink's multiple XML IDs feature. In this case, you should re-implement your IDResolver as a subclass of org.eclipse.persistence.jaxb.IDResolver.


[edit] Appendix A - Example IDResolver

import java.util.LinkedHashMap;
import java.util.Map;
import java.util.concurrent.Callable;
 
import javax.xml.bind.ValidationEventHandler;
 
import org.eclipse.persistence.jaxb.IDResolver;
 
import org.xml.sax.SAXException;
 
public class MyIDResolver extends IDResolver {
   Map<Map<String, Object>, Apple> apples = new LinkedHashMap();
   Map<Map<String, Object>, Orange> oranges = new LinkedHashMap();
 
   @Override
   public void startDocument(ValidationEventHandler eventHandler) throws SAXException {
       apples.clear();
       oranges.clear();
   }
 
   @Override
   public void endDocument() throws SAXException {
   }
 
   @Override
   public void bind(Map<String, Object> idWrapper, Object obj) throws SAXException {
       if (obj instanceof Apple) {
           ((Apple) obj).processed = true;
           apples.put(idWrapper, (Apple) obj);
       } else {
           ((Orange) obj).processed = true;
           oranges.put(idWrapper, (Orange) obj);
       }
   }
 
   @Override
   public Callable<Object> resolve(final Map<String, Object> idWrapper, final Class type) throws SAXException {
       return new Callable<Object>() {
           public Object call() {
               if (type == Apple.class) {
                   return apples.get(idWrapper);
               } else {
                   return oranges.get(idWrapper);
               }
           }
       };
   }
 
   @Override
   public void bind(Object id, Object obj) throws SAXException {
       Map<String, Object> idMap = new LinkedHashMap<String, Object>(1);
       idMap.put("stringId", id);
       bind(idMap, obj);
   }
 
   @Override
   public Callable<?> resolve(Object id, Class type) throws SAXException {
       Map<String, Object> idMap = new LinkedHashMap<String, Object>(1);
       idMap.put("stringId", id);
       return resolve(idMap, type);
   }
 
}