org.exist.fluent
Class QueryService

java.lang.Object
  org.exist.fluent.QueryService

All Implemented Interfaces:

Cloneable

public class QueryService
extends Object
implements Cloneable

Provides facilities for performing queries on a database. It cannot be instantiated directly; you must obtain an instance from a resource or the database.

Author:

Piotr Kaminski

Nested Class Summary

static class	QueryService.QueryAnalysis An access point for running various analyses on a query.
static class	QueryService.Statistics

Method Summary

ItemList	all(String query, Object... params) Get all items that match the given query in the context of this object.
QueryService.QueryAnalysis	analyze(String query, Object... params) Statically analyze a query for various properties.
QueryService	clone()
QueryService	clone(NamespaceMap nsBindingsOverride, Map<QName,?> varBindingsOverride) Clone this query service, optionally overriding the clone's namespace and variable bindings.
Database	database() Return the database to which the resource that provides the context for this query service belongs.
boolean	exists(String query, Object... params) Return whether at least one item matches the given query in the context of this object.
boolean	flag(String query, boolean defaultValue)
QueryService	importModule(Document module) Import an XQuery library module from the given document.
QueryService	importSameModulesAs(QueryService that) Import the same modules into this query service as imported by the given query service.
QueryService	let(QName variableName, Object value) Bind a variable to the given value within all query expression evaluated subsequently.
QueryService	let(String variableName, Object value) Bind a variable to the given value within all query expression evaluated subsequently.
QueryService	limitRootDocuments(Collection<XMLDocument> rootDocs) Limit the root documents accessible to the query to the given list, overriding the any set derived from the query's context.
QueryService	limitRootDocuments(XMLDocument... rootDocs) Limit the root documents accessible to the query to the given list, overriding the any set derived from the query's context.
QueryService	namespace(String key, String uri) Declare a namespace binding within the scope of this query.
NamespaceMap	namespaceBindings() Return this query service's namespace bindings for inspection or modification.
Item	optional(String query, Object... params) Get no more than one item that matches the given query in the context of this object.
QueryService	presub() Pre-substitute variables of the form '$n' where n is an integer in all query expressions evaluated subsequently.
void	run(String query, Object... params) Run the given query, ignoring the results.
Item	single(String query, Object... params) Get the one and only item that matches the given query in the context of this object.
static QueryService.Statistics	statistics() Get the process-wide performance statistics gathering facet.
ItemList	unordered(String query, Object... params) Get all items that match the given query in the context of this object, without regard for the order of the results.

Methods inherited from class java.lang.Object

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

Method Detail

statistics

public static QueryService.Statistics statistics()

Get the process-wide performance statistics gathering facet.

Returns:

the performance statistics facet

database

public Database database()

Return the database to which the resource that provides the context for this query service belongs. The returned database will inherit its namespace bindings from this query service.

Returns:

the database that contains this object

let

public QueryService let(String variableName,
                        Object value)

Bind a variable to the given value within all query expression evaluated subsequently.

Parameters:

variableName - the qualified name of the variable to bind; prefixes are taken from the namespace mappings of the folder that provided this service; if the name starts with a $, it will be stripped automatically

value - the value the variable should take

Returns:

this service, to chain calls

let

public QueryService let(QName variableName,
                        Object value)

Bind a variable to the given value within all query expression evaluated subsequently.

Parameters:

variableName - the qualified name of the variable to bind

value - the value the variable should take

Returns:

this service, to chain calls

namespace

public QueryService namespace(String key,
                              String uri)

Declare a namespace binding within the scope of this query.

Parameters:

key - the key to bind

uri - the namespace uri

Returns:

this service, to chain calls

namespaceBindings

public NamespaceMap namespaceBindings()

Return this query service's namespace bindings for inspection or modification.

Returns:

this query service's namespace bindings

importModule

public QueryService importModule(Document module)

Import an XQuery library module from the given document. The namespace and preferred prefix of the module are extracted from the module itself. The MIME type of the document is set to "application/xquery" as a side-effect.

Parameters:

module - the non-XML document that holds the library module's source

Returns:

this service, to chain calls

Throws:

DatabaseException - if the module is an XML document, or the module declaration cannot be found at the top of the document

importSameModulesAs

public QueryService importSameModulesAs(QueryService that)

Import the same modules into this query service as imported by the given query service. This is a one-time copy; further imports into either query service won't affect the other one.

Parameters:

that - the query service to copy module imports from

Returns:

this service, to chain calls

limitRootDocuments

public QueryService limitRootDocuments(XMLDocument... rootDocs)

Limit the root documents accessible to the query to the given list, overriding the any set derived from the query's context. The query will still be able to access other documents through bound variables or by naming them directly, though.

Parameters:

rootDocs - the list of root documents to limit the query to

Returns:

this service, to chain calls

limitRootDocuments

public QueryService limitRootDocuments(Collection<XMLDocument> rootDocs)

Limit the root documents accessible to the query to the given list, overriding the any set derived from the query's context. The query will still be able to access other documents through bound variables or by naming them directly, though.

Parameters:

rootDocs - the list of root documents to limit the query to

Returns:

this service, to chain calls

presub

public QueryService presub()

Pre-substitute variables of the form '$n' where n is an integer in all query expressions evaluated subsequently. The values are taken from the usual postional parameter list. Parameters that are presubbed are also bound to the usual $_n variables and can be used normally as such. Pre-subbing is useful for element and attribute names, where XQuery doesn't allow variables.

Returns:

this service, to chain calls

clone

public QueryService clone()

Overrides:

clone in class Object

clone

public QueryService clone(NamespaceMap nsBindingsOverride,
                          Map<QName,?> varBindingsOverride)

Clone this query service, optionally overriding the clone's namespace and variable bindings. If the namespace bindings override or variable bindings override is specified, then that object is cloned and used for its respective purpose. If an override is not specified, the bindings are cloned from the original query service.

Parameters:

nsBindingsOverride - the namespace bindings to clone, or null to clone from the original

varBindingsOverride - the variable bindings to clone, or null to clone from the original

Returns:

a clone of this query service with bindings optionally overridden

all

public ItemList all(String query,
                    Object... params)

Get all items that match the given query in the context of this object.

Parameters:

query - the query to match

params - parameters to the query, will be substituted for $_1, $_2, etc.

Returns:

a collection of all items that match the query

run

public void run(String query,
                Object... params)

Run the given query, ignoring the results. Useful for running update "queries" -- see eXist's XQuery Update Extensions.

Parameters:

query - the query to run

params - parameters to the query, will be substituted for $_1, $_2, etc.

unordered

public ItemList unordered(String query,
                          Object... params)

Get all items that match the given query in the context of this object, without regard for the order of the results. This can sometimes make a query run faster.

Parameters:

query - the query to match

params -

Returns:

a collection of all items that match the query

single

public Item single(String query,
                   Object... params)

Get the one and only item that matches the given query in the context of this object.

Parameters:

query - the query to match

params -

Returns:

the unique item that matches the query

optional

public Item optional(String query,
                     Object... params)

Get no more than one item that matches the given query in the context of this object.

Parameters:

query - the query to match

params -

Returns:

the item that matches this query, or Item.NULL if none

flag

public boolean flag(String query,
                    boolean defaultValue)

exists

public boolean exists(String query,
                      Object... params)

Return whether at least one item matches the given query in the context of this object.

Parameters:

query - the query to match

params -

Returns:

true if at least one item matches, false otherwise

analyze

public QueryService.QueryAnalysis analyze(String query,
                                          Object... params)

Statically analyze a query for various properties.

Parameters:

query - the query to analyze

params - parameters for the query; if necessary parameters are left out they will be listed as required variables in the analysis

Returns:

a query analysis facet