This is the fundamental interface for applications. A XQueryConnection provides an environment for creating Expressions, which can then be executed. Notice that the word Connection does not necessarily imply a remote connection through a network. XQuest currently uses the RMI technology, so the application and the "server" can work in a distributed object environment, but of course the client code can also run in the same Java Virtual Machine as the XQuery engine.

A XQueryConnection is obtained from a XQueryServer, or from XQueryDataSource, which is an abstract connection factory.

Each application should have its own XQueryConnection. Access to the same connection by several threads must be explicitly synchronized.

Abstract view of a XQuery Engine (embedded or remotely accessible). It is mainly a provider of connections through a method named getConnection() which can specify a particular XML Library (database).

An implementation of the XQuery engine (XQueryServer interface). This is a controller centralizing the management of resources (memory, XML Libraries, compiled XQuery modules, cache of parsed XML documents). The configuration interface belongs to the server side and is not visible to applications, which see this object as a XQueryServer only.

Configuring and starting a XQueryEngine is dependent on the context in which XQuest is used (standalone, J2EE). This topic is explained in a separate section below.

A XQueryExpression is the equivalent of a JDBC/SQL Statement. It is created from a Connection and receives a XQuery script.

Its purpose is to execute simple scripts. However values can be bound with XQuery variables, like for XQueryPreparedExpression. It can be reused for several different scripts.

A Prepared Expression is a particular case of XQueryExpression, used to execute repetitively the same XQuery script with different variable settings. Global XQuery variables can be assigned a value through this interface.

This is the result of the execution of an Expression. A XQuery expression returns a value which is a sequence of items (XQItem). An Item is a simple "atomic" value (string, number etc.) or a XML Node (a node of the XML Data Model).

XQResultSequence appears as an iterator which enumerates the items of the sequence. It provides methods to obtain and test the type and value of each item.

This is an abstract interface which provides methods to obtain and test the type and value of the item.

A representation of XQuery types. XQType is the most general: it can describe Item types (XQItemType) or sequence types. The type of a XQValue is generally XQType, while the type of a XQItem is always a XQItemType.

A specialization of XQItem representing XML nodes. It provides access to the XML Data Model. Data Model interfaces are presented in a separate section below.

represents the accessor dm:node-kind() which returns string values like "document", "element", "attribute" etc.

returns the node kinds as integer values, more convenient for programming, like DOCUMENT, ELEMENT, ATTRIBUTE, TEXT, COMMENT, PROCESSING_INSTRUCTION, and NAMESPACE (all constant fields of the Node interface).

represents the accessor dm:node-name() which returns a qualified name if applicable (elements, attributes) or the null value.

Returns the parent node or null.

Returns the textual contents of the node, as defined in the DM specifications (The string value of an element is the concatenation of all text fragments encompassed by the element).

For documents and elements, returns a NodeSequence, an abstract iterator which can enumerate the children nodes in document order. To iterate on children, the following code pattern is typically used:

NodeSequence children = node.children();
while(children.next()) {
    Node child = children.currentNode();
    //...
}

For other node kinds, the sequence is always empty.

This method returns the sequence of attribute nodes belonging to an element. Example: a crude serialization of an element:

if( node.getNature() == Node.ELEMENT ) {
   output.print("<");
   // print element name: needs to convert QName to string
   output.printName(node.getNodeName()); 

   NodeSequence attributes = node.attributes();
   for( ; attributes.next(); ) {
       Node attr = attributes.next.currentNode();
       output.print(" ");
       // print attribute name: needs to convert QName to string
       output.printName(attr.getNodeName());
       output.print("='");
       // print attribute value (needs escaping)
       output.printName(attr.getStringValue());
       output.print('");
   }
   output.print(">");
}

Returns the sequence of children which pass the test. For example, this code returns an iterator on children which have the name "section", with a blank namespace:

node.children( new ElementTest("section") )

which can also be written less simply as:

node.children( new BaseNodeTest( Node.ELEMENT, 
                                 Namespace.NONE, "section") )

Returns the sequence of attributes which pass the test. For example, this code returns an iterator on all attributes which have a name with namespace ns:

node.children( new AttributeTest( ns, null ) )

Similar filtered iterators which implement XPath axes like ancestor, descendant etc.

is equivalent to children(test)

etc.

Returns -1 if this node is strictly before the other node in the document order, 0 if nodes are identical, or 1 if after the argument node.

This method is generally very efficient.

compares the string values of two nodes, whatever their kinds, with an optional Collator.

DOMEventBuilder can build W3C DOM trees.

For example (assuming expr is a XQueryExpression associated with a valid connection) this code snippet would build a DOM tree representing the XML fragment <E>1 2 3</E>:

DOMEventBuilder builder = new DOMEventBuilder();
expr.executeQuery("element E { 1 to 3 }", builder);
Node result = builder.harvest();

The created tree can be retrieved with the method harvest(). The builder can be reused by calling the reset() method.

Another class CoreEventBuilder, very similar to DOMEventBuilder, can build trees of the internal "Core" Data Model. This is mainly for internal usage.

XMLSerializer, DOMEventBuilder and CoreEventBuilder are in fact particular implementations of a general interface called XMLEventHandler, which is conceptually similar to SAX2.

Like SAX, this interface handles events like StartDocument, StartElement, Attribute, EndElement, Text, Comment... EndDocument, and incrementally builds another representation.

There is a convenience transformation method which traverses any node and its subtree:

XMLEventHandler.traverse(node);

Though it may not look very intuitive, using this interface can be quite powerful for transforming a tree - or generating large trees with small memory footprint-, by combining export with explicit construction or tree traversal.

QName DOC = QName.get("doc");
QName WRAP = QName.get("wrap");
XMLEventHandler eh = new DOMEventBuilder();
eh.evStartElement(DOC);
eh.evText("some text");
eh.evAttribute(QName.get("id"), "x0001");
// wrap the result of a query evaluation in a "wrapper" element:
eh.evStartElement(WRAP);
// include the query result:
expr.executeQuery(eh);
eh.evEndElement(WRAP);
eh.evComment(" a comment ");
eh.evEndElement(DOC);
XQNode result = eh.harvest();

This snippet would create the following DOM tree (the fragment <result>...</result> stands for whatever is returned by the query execution):

<doc id="x0001">some text<wrap>
<result>...</result>
</wrap><!-- a comment --></doc>