Version 9.6
 —  The CentraSite API for XQJ  —

Working with the CentraSite XQJ Interface

If you wish to develop an XQJ application, you will find the classes of the CentraSite XQJ implementation in the jar file rts/bin/xqj.jar under the CentraSite installation location.

You can use the CentraSite XQJ interface to perform an XQuery on the basis of a standard XQExpression or an XQPreparedExpression. With a standard XQExpression, the query is parsed each time it is executed. If a query is to be executed many times, it can be more efficient to use an XQPreparedExpression, which is parsed only once.


Executing an XQuery with a Standard XQExpression

Start of instruction setTo execute an XQuery with a standard XQExpression

  1. Invoke the getXQConnection() method to get the XQConnection object from the JAXRConnection.

    Example

    /* Get the XQConnection from the JAXRConnection */
    XQConnection connection = jaxrConnection.getXQConnection ();

    You have now established an XQConnection.

  2. Create an XQExpression object from the XQConnection object. The XQExpression is used to invoke several other methods to perform various tasks using the CentraSite XQJ interface. You may create more than one XQExpression from a single connection if required.

    Example

    /* Create XQExpression from XQConnection to execute an XQuery. */
    XQExpression expression = connection.createExpression();
    
  3. Optionally, you can bind one or more external variables. An external variable is a type of variable that can be dynamically added to the query by declaring the variable in the query. The value of the variable can be set externally and added to the pre-set variable while executing the XQuery.

    Example

    String xquery = "declare variable $year as xs:int external" +
                    "for $q in input()/bib/book where $q/@year > $year return $q" ;
    XQExpression expression = connection.createExpression();
    expression.bindInt(new QName("year"),1993,XQItemTypeHelper.createIntXQItemType());
    XQResultSequence xqResultSequence = expression.executeQuery(xquery);
    
  4. Invoke the executeQuery() method. This returns an XQResultSequence.

    Example

    /* Executing an XQuery */
    /* Instance of the query string: */
    String xquery = "for $b in input()/book return $b/title";
    /* Execute the above XQuery String, which returns an XQResultSequence */
    XQResultSequence xqResultSequence = expression.executeQuery(xquery);
    
  5. The XQResultSequence represents the XQuery result. Retrieve the query result and read/print it in XML format. The query result sequence is displayed item by item. Using XQJ, it is possible to get the result sequence in DOM, SAX and StAX-compatible formats.

    Note:
    You cannot scroll the XQResultSequences backwards.

    Example

    /* Iterating the XQResultSequence */
    XMLStreamReader reader = null;
    While(xqResultSequence.next())
    {
      reader =  xqResultSequence.getItemAsStream();
      /* Iterate the XML StreamReader using StAX-compatible APIs */
    }
    connection.commit();
    connection.close();
    

    Example using the getInt() method

    /* Instance of the XQuery String */
    String xquery =" for $b in input()/bib/book return xs:int($b/@year) ";
    /* This query on execution will return the year as an integer value */
    XQResultSequence xqResultSequence = expression.executeQuery(xquery);
    
    xqResultSequence.next();
    int I = xqResultSequence.getInt();
    

    Example using the getAtomicValue() method

    /* Instance of the XQuery String */
    String xquery = "for $p in input()/book return xs:string($p/title)";
    XQResultSequence xqResultSequence = expression.executeQuery(xquery);
    
    /* This query on execution will return the title as a String */
    xqResultSequence.next();
    String str = xqResultSequence.getAtomicValue();
    

    Example using the getNode() method

    /* Instance of the XQuery String */
    String xquery = "for $q in input()/bib/book return $q";
    XQResultSequence xqResultSequence = expression.executeQuery(xquery);
    xqResultSequence.next();
    Node node = result.getNode();
    

    Example using the writeItemToSAX() method

    xqResultSequence.next();
    StringWriter sw = new StringWriter();
    
    /* Provide a org.xml.sax.ContentHandler, which is saxhandler in our case */
    XQSAXTextEventHandler saxhandler = new XQSAXTextEventHandler(sw);
    resultSequence.writeItemToSAX(saxhandler);
    System.out.println(sw);
    
  6. Finally, invoke the XQConnection.close() method to close the connection to the registry/repository.

    Example

    /* Commit and close the XQConnection once you have completed working with it */
    connection.commit();
    connection.close();
    

Top of page

Executing an XQuery with an XQPreparedExpression

Start of instruction setTo execute an XQuery with an XQPreparedExpression

  1. Invoke the getXQConnection() method to get the XQConnection object from the JAXRConnection.

    Example

    /* Get the XQConnection from the JAXRConnection */
    XQConnection connection = jaxrConnection.getXQConnection ();

    You have now established an XQConnection.

  2. Create an XQPreparedExpression object from the XQConnection object. The XQPreparedExpression is used to invoke several other methods to perform various tasks using the CentraSite XQJ interface. You may create more than one XQPreparedExpression from a single connection if required.

    Example

    /* Create XQPreparedExpression from XQConnection */
    String pQuery = "for $q in input()/bib/book return $q"; 
    XQPreparedExpression preparedExpression = conn.prepareExpression(pQuery);
    
  3. Optionally, you can bind one or more external variables. An external variable is a type of variable that can be dynamically added to the query by declaring the variable in the query. The value of the variable can be set externally and added to the pre-set variable while executing the XQuery.

    Example

    /* Binding variables in Prepared Expressions */
    String pQuery = "declare variable $int as xs:int external" +  
                    "for $q in input()/bib/book where $q/@year = $int return $q";
    
    XQPreparedExpression preparedExpression = conn.prepareExpression(pQuery);
    
    /* Bind the appropriate value to the prepared expression using the matching binding API provided. */
    

    Using bindInt() to bind an int value to the prepared expression

    preparedExpression.bindInt(new QName("int"), 1994, XQItemTypeHelper.createIntXQItemType());
    

    Using bindNode() to bind a node to the prepared expression

    /* Get a node to bind by executing an expression */
    XQExpression expression = connection.createExpression();
    XQResultSequence xqResultSequence = 
        expression.executeQuery("for $q in input()/bib/book where $q/@year = 1994 return $q/title");
    xqResultSequence.next();
    
    /* Get a node from the result sequence retrieved above */
    Node node = xqResultSequence.getNode();
    
    /* PreparedQuery */
    String pquery = "declare variable $node external " +    
                    "for $q in input()/bib/book where $q/title = $node return $q"; 
    XQPreparedExpression prepared = connection.prepareExpression(pQuery);
    
    /* Bind the above retrieved node to the prepared query */ 
    prepared.bindNode(new QName("node"), node);
    
  4. Invoke the executeQuery() method. This returns an XQResultSequence.

    Example

    /* Execute the prepared expression which returns an XQResultSequence */
    XQResultSequence xqResultSequence = preparedExpression.executeQuery();
    
  5. The XQResultSequence represents the XQuery result. Retrieve the query result and read/print it in XML format. The query result sequence is displayed item by item. Using XQJ, it is possible to get the result sequence in DOM, SAX and StAX-compatible formats.

    Example

    /* Iterating the XQResultSequence */
    XQResultSequence xqResultSequence = preparedExpression.executeQuery();
    XMLStreamReader reader = null;
    While(xqResultSequence.next())
    {
      reader =  xqResultSequence.getItemAsStream();
      /* Iterate the XML StreamReader using StAX-compatible APIs */
    }
    

    Example using the getInt() method

    XQResultSequence xqResultSequence = preparedExpression.executeQuery();
    xqResultSequence.next();
    int I = xqResultSequence.getInt();
    

    Example using the getAtomicValue() method

    XQResultSequence xqResultSequence = preparedExpression.executeQuery();
    xqResultSequence.next();
    String str = xqResultSequence.getAtomicValue();
    

    Example using the getNode() method

    XQResultSequence xqResultSequence = preparedExpression.executeQuery();	
    xqResultSequence.next();
    Node node = result.getNode();
    

    Example using the writeItemToSAX() method

    XQResultSequence xqResultSequence = preparedExpression.executeQuery();	
    xqResultSequence.next();
    StringWriter sw = new StringWriter();
    
    /* Provide an org.xml.sax.ContentHandler, which is saxhandler in our case */
    XQSAXTextEventHandler saxhandler = new XQSAXTextEventHandler(sw);
    resultSequence.writeItemToSAX(saxhandler);
    System.out.println(sw);
    
  6. Finally, invoke the XQConnection.close() method to close the connection to the registry/repository.

    Example

    /* Commit and close the XQConnection once you have completed working with it */
    connection.commit();
    connection.close();
    

Top of page

Working with a Materialized XQSequence

A materialized sequence is not bound to any connection or XQuery expression. It can be created from XQResultSequences or from a java.util.iterator.

Examples

Creating a Sequence

This example demonstrates how to create a materialized sequence from Java collection via the java.util.iterator interface. It creates a materialized sequence holding 3 int items.

ArrayList items = new ArrayList();
items.add(conn.createItemFromInt(123,null));
items.add(conn.createItemFromInt(456,null));
items.add(conn.createItemFromInt(789,null));
XQSequence sequence = conn.createSequence(items.iterator());

Creating a Copy from an XQResultSequence

This example demonstrates how an XQResultSequence can be copied into a materialized sequence. The materialized sequence will exist independently of the XQResultSequence.

String query = "for $q in input()/bib/book where $q/@year = 1994 return $q";
XQExpression expression = connection.createExpression();
XQResultSequence resultSequence = expression.executeQuery(query);

XQSequence Sequence = connection.createSequence(resultSequence);

Top of page