com.ddtek.xquery3
Interface XQCommonHandler

public interface XQCommonHandler

XQCommonHandler defines the interface for all handlers for object models such as DOM4J, JDOM, JAXB, etc. This interface provides the default behaviour for handling known objects, that is to return the corresponding Java object for each XML type as defined by Java to XML type mapping. The default object model is DOM. For example, XQCommonHandler returns Integer object for integer type, String for string type, Double for double type, DOM node for Node, and so forth. The application must provide a subclass implementation for the specific object model to be supported.

A usage example with a JAXB handler :

  ...
  XQDataSource dataSource = ...
  XQConnection con = dataSource.getConnection("myUID", "myPWD");
 
  // Find all Employees belong to the SW department 
  //  from the EMPS collection
  String qs = "for $e in collection('EMPS.xml')
               where $e/Dept='SW'
               return $e";
  XQPreparedExpression = con.preparedExpression(qs);
  XQResultSequence rs = expression.executeQuery();

  // JAXBHandler class is provided by the application
  // or by a service provider
  // Creates a JAXB handler for com.acme.xml package
  JAXBContext jaxbContext = JAXBContext.newInstance("com.acme.xml");
  XQCommonHandler jaxbHandler = new JAXBHandler(jaxbContext);

  while(rs.next()) {
     // Employee is a JAXB object 
     //    defined in com.acme.xml package
     // Note that we could have set the jaxbHandler at the connection
     // level, before preparing the expression, in which case, 
     // we need not supply the handler to the getObject.
     Employee emp = (Employee) rs.getObject(jaxbHandler); 
     // use the Employee object
     // assuming Employee implements toString()
     System.out.println(emp); 
  }
  ...
 

Usage :

The common handler object can be used in the following scenarios.

• Passing the common handler object as a parameter of getObject() method. For example,

     Employee emp = (Employee) rs.getObject(jaxbHandler);
    

• Setting the common handler object as the default handler for a connection. Prepared and unprepared expressions created by this connection will generate a result sequence having this handler as the default handler. For example,

    
     connection.setCommonHandler(jaxbHandler);
     XQPreparedExpression pe = connection.prepareExpression(expression);
     XQSequence rs = pe.executeQuery();
     ...
     Employee emp = (Employee) rs.getObject(); 
    

• Setting the common handler object as the default handler for a datasource. All connections obtained from this datasource will have this handler as the default handler. Therefore, the getObject method can be invoked without a parameter. For example,

   
     XQDataSource datasource = ...  datasource.setCommonHandler(jaxbHandler);
     XQConnection conn = datasource.getConnection();
     XQPreparedExpression pe = connection.prepareExpression(expression);
     XQSequence rs = pe.executeQuery();
     ...
     Employee emp = (Employee) rs.getObject();
    

See Also:

XQSequence, XQResultSequence, XQItem

Method Summary

XQItem	fromObject(Object obj) Converts an object from a specific object model to a standard XQItem object containable in a sequence, thus compatible with other operations involving items and sequences.
Object	toObject(XQItemAccessor item) Converts an item into its corresponding object in the current object model supported.

Method Detail

toObject

public Object toObject(XQItemAccessor item)
                throws XQException

Converts an item into its corresponding object in the current object model supported. This method takes in an XQItemAccessor interface and hence the item object passed in could reside in a sequence or exist independently. This method is called by XQSequence.getObject(), XQSequence.getObject(XQCommonHandler ch), XQItem.getObject(), and XQItem.getObject(XQCommonHandler ch) to convert an item representation into an object of the appropriate object model.

A possible implementation of the method getObject(XQCommondHandler ch) above is:

  public Object getObject(XQCommonHandler ch) {
    return ch.toObject(this);
  } 

The following is using the default handler,

  public Object getObject() {
    return defaultHandler.toObject(this);
  } 

The defaultHandler is a private variable of the XQSequence implementation that is initially set to the default XQCommonHandler class. This can be overriden with a more specific handler using the method setCommonHandler(XQCommonHandler ch).

Parameters:

item - the item to be converted accessible via an item accessor interface

Returns:

an object that need to be casted to the appropriate type

Throws:

XQException - if the current item can not be converted to the specified object model

fromObject

public XQItem fromObject(Object obj)
                  throws XQException

Converts an object from a specific object model to a standard XQItem object containable in a sequence, thus compatible with other operations involving items and sequences.

Parameters:

obj - an object from a specific object model, e.g. DOM4J, JDOM, JAXB, etc

Returns:

an XQItem item

Throws:

XQException - if conversion failed