Create XQCommonHandler interface

[cfoster]

Create XQCommonHandler interface, along the lines of:

import javax.xml.xquery.XQItemAccessor;
import javax.xml.xquery.XQItem;
import javax.xml.xquery.XQException;

public interface XQCommonHandler
{
  public XQItem fromObject(Object obj) throws XQException;
  public Object toObject(XQItemAccessor item) throws XQException;
}

Add methods to XQConnection2 to enable the user to specify their own XQCommonHandler implementation in such a way that they can also simply override certain scenarios (e.g. certain Objects) and allow the rest of the XQJ driver to cater for everything else, as it would do normally.

So essentially, the user could create an implementation, something along the lines of:

public class CustomXQCommonHandler implements XQCommonHandler
{
  XQCommonHandler subordinateHandler; // e.g. the XQJ Driver's DEFAULT handler.
  XQDataFactory dataFactory;

  public CustomXQCommonHandler(
    XQCommonHandler handler,
    XQDataFactory factory)
  {
    subordinateHandler = handler;
    dataFactory = factory;
  }

  public XQItem fromObject(Object obj) throws XQException
  {
    if(obj instanceof MyFavouritePOJO)
    {
      /**
        create and return XQItem via dataFactory
      **/
    }
    else
    {
      return subordinateHandler.fromObject(obj);
    }
  }

  public Object toObject(XQItemAccessor item) throws XQException
  {
    if(item --- has certain characteristics we are interested in)
    {
      return createMyFavouritePOJO();
    }
    else
    {
      return subordinateHandler.toObject(item);
    }
}

When a user is using a custom XQCommonHandler, methods such as

• XQItemAccessor.getObject()
• XQDynamicContext.bindObject(QName varName, Object value, XQItemType type)
• XQDataFactory.createItemFromObject(Object value, XQItemType type)

will be affected.

This must be well documented.