nux.xom.pool
Class XQueryPool

java.lang.Object
  nux.xom.pool.XQueryPool

public class XQueryPool
extends Object

Efficient thread-safe pool/cache of XQuery objects, creating and holding at most maxEntries XQuery objects (each representing a compiled query). On cache miss, a new XQuery is created via a factory, cached for future reuse, and then returned. On cache hit an XQuery is returned instantly. Pool eviction is based on a LRU (least recently used) policy, or if the JVM runs low on free memory.

This class helps to avoid the large overhead involved in constructing (i.e. compiling) an XQuery instance, in particul for complex queries over small input XML documents. Most useful in high throughput server container environments (e.g. large-scale Peer-to-Peer messaging network infrastructures over high-bandwidth networks, scalable MOMs, etc).

Note that this class caches queries, not their results or result fragments. In particular, no materialized view maintenance is done. If desired, result caching can be implemented in an application-specific manner on top of this class, in a large variety of ways, for example via DocumentMap.

Example usage (in any arbitrary thread and any arbitrary object):

     XQuery xquery = XQueryPool.GLOBAL_POOL.getXQuery(new File("samples/xmark/q03.xq"));
     //XQuery xquery = XQueryPool.GLOBAL_POOL.getXQuery("for $i in /* return $i/headline_text", null);
     Document doc = BuilderPool.GLOBAL_POOL.getBuilder(false).build(new File(samples/xmark/auction-0.01.xml));
     Nodes results = xquery.execute(doc).toNodes();
     for (int i=0; i < results.size(); i++) {
         System.out.println("node "+i+": "+results.get(i).toXML());
     }
 

Note: Internally uses extremely short-lived locks; the resulting potential lock contention is completely negligible.

Author:

whoschek.AT.lbl.DOT.gov, $Author: hoschek3 $

Field Summary

static XQueryPool

GLOBAL_POOL A default pool (can be shared freely across threads without harm); global per class loader.

Constructor Summary

XQueryPool()
Creates a new pool with default parameters.

XQueryPool(PoolConfig config, XQueryFactory factory)
Creates a new pool with the given configuration that uses the given factory on cache misses.

Method Summary

XQuery	getXQuery(File query) Returns an XQuery for the given input query.
XQuery	getXQuery(File query, URI baseURI) Returns an XQuery for the given input query, using the given base URI.
XQuery	getXQuery(ResourceResolver resolver, String resourceName, URI baseURI) Returns an XQuery for the input stream obtained from resolving the given resourceName against the given resolver.
XQuery	getXQuery(String query, URI baseURI) Returns an XQuery for the given input query, using the given base URI.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GLOBAL_POOL

public static final XQueryPool GLOBAL_POOL

A default pool (can be shared freely across threads without harm); global per class loader.

Constructor Detail

XQueryPool

public XQueryPool()

Creates a new pool with default parameters.

XQueryPool

public XQueryPool(PoolConfig config,
                  XQueryFactory factory)

Creates a new pool with the given configuration that uses the given factory on cache misses.

Parameters:

config - the configuration to use

factory - the factory creating new XQuery instances on cache misses

Method Detail

getXQuery

public XQuery getXQuery(File query)
                 throws XQueryException,
                        IOException

Returns an XQuery for the given input query.

Parameters:

query - the query to compile

Returns:

an XQuery

Throws:

IOException - if an I/O error occured while reading the query.

XQueryException - if the query has a syntax error, or if it references namespaces, variables, or functions that have not been declared, or contains other static errors such as type mismatches.

getXQuery

public XQuery getXQuery(File query,
                        URI baseURI)
                 throws XQueryException,
                        IOException

Returns an XQuery for the given input query, using the given base URI.

Parameters:

query - the query to compile

baseURI - an absolute URI, used when necessary in the resolution of relative URIs found in the query. Used by the XQuery doc function, and hence the resolver. May be null in which case it defaults to the current working directory.

Returns:

an XQuery

Throws:

IOException - if an I/O error occured while reading the query.

XQueryException - if the query has a syntax error, or if it references namespaces, variables, or functions that have not been declared, or contains other static errors such as type mismatches.

getXQuery

public XQuery getXQuery(String query,
                        URI baseURI)
                 throws XQueryException

Returns an XQuery for the given input query, using the given base URI.

Parameters:

query - the query to compile

baseURI - an absolute URI, used when necessary in the resolution of relative URIs found in the query. Used by the XQuery doc function, and hence the resolver. May be null in which case it defaults to the current working directory.

Returns:

an XQuery

Throws:

XQueryException - if the query has a syntax error, or if it references namespaces, variables, or functions that have not been declared, or contains other static errors such as type mismatches.

getXQuery

public XQuery getXQuery(ResourceResolver resolver,
                        String resourceName,
                        URI baseURI)
                 throws XQueryException,
                        IOException,
                        MissingResourceException

Returns an XQuery for the input stream obtained from resolving the given resourceName against the given resolver.

Parameters:

resolver - an object that can produce an input stream for a given resource name.

resourceName - the resource name (e.g. a path or URL)

baseURI - an absolute URI, used when necessary in the resolution of relative URIs found in the query. Used by the XQuery doc function, and hence the resolver. May be null in which case it defaults to the current working directory. Need not be the actual URI of the resolver's stream.

Returns:

an XQuery

Throws:

MissingResourceException - if the resolver could not find the resource (unchecked exception)

IOException - if an I/O error occured while reading the query from the stream

XQueryException - if the query has a syntax error, or if it references namespaces, variables, or functions that have not been declared, or contains other static errors such as type mismatches.