javax.jcr.query
Interface Query

All Known Subinterfaces:

QueryObjectModel

public interface Query

A Query object.

Field Summary

static java.lang.String	JCR_JQOM A string constant representing the JCR-JQOM query language.
static java.lang.String	JCR_SQL2 A string constant representing the JCR-SQL2 query language.
static java.lang.String	SQL Deprecated. As of JCR 2.0, this language is deprecated.
static java.lang.String	XPATH Deprecated. As of JCR 2.0, this language is deprecated.

Method Summary

void	bindValue(java.lang.String varName, Value value) Binds the given value to the variable named varName.
QueryResult	execute() Executes this query and returns a QueryResult object.
java.lang.String[]	getBindVariableNames() Returns the names of the bind variables in this query.
java.lang.String	getLanguage() Returns the language set for this query.
java.lang.String	getStatement() Returns the statement defined for this query.
java.lang.String	getStoredQueryPath() If this is a Query object that has been stored using storeAsNode(java.lang.String) (regardless of whether it has been saved yet) or retrieved using QueryManager.getQuery(javax.jcr.Node)), then this method returns the path of the nt:query node that stores the query.
void	setLimit(long limit) Sets the maximum size of the result set to limit.
void	setOffset(long offset) Sets the start offset of the result set to offset.
Node	storeAsNode(java.lang.String absPath) Creates a node of type nt:query holding this query at absPath and returns that node.

Field Detail

XPATH

static final java.lang.String XPATH

Deprecated. As of JCR 2.0, this language is deprecated.

A string constant representing the XPath query language as defined in JCR 1.0.

See Also:

Constant Field Values

SQL

static final java.lang.String SQL

Deprecated. As of JCR 2.0, this language is deprecated.

A string constant representing the SQL query language as defined in JCR 1.0.

See Also:

Constant Field Values

JCR_SQL2

static final java.lang.String JCR_SQL2

A string constant representing the JCR-SQL2 query language.

Since:

JCR 2.0

See Also:

Constant Field Values

JCR_JQOM

static final java.lang.String JCR_JQOM

A string constant representing the JCR-JQOM query language.

Since:

JCR 2.0

See Also:

Constant Field Values

Method Detail

execute

QueryResult execute()
                    throws InvalidQueryException,
                           RepositoryException

Executes this query and returns a QueryResult object.

If this Query contains a variable (see BindVariableValue) which has not been bound to a value (see bindValue(java.lang.String, javax.jcr.Value)) then this method throws an InvalidQueryException.

Returns:

a QueryResult object

Throws:

InvalidQueryException - if the query contains an unbound variable.

RepositoryException - if another error occurs.

setLimit

void setLimit(long limit)

Sets the maximum size of the result set to limit.

Parameters:

limit - a long

Since:

JCR 2.0

setOffset

void setOffset(long offset)

Sets the start offset of the result set to offset.

Parameters:

offset - a long

Since:

JCR 2.0

getStatement

java.lang.String getStatement()

Returns the statement defined for this query.

If the language of this query is JCR-SQL2 or another string-based language, this method will return the statement that was used to create this query.

If the language of this query is JCR-JQOM, this method will return the JCR-SQL2 equivalent of the JCR-JQOM object tree. This is the standard serialization of JCR-JQOM and is also the string stored in the jcr:statement property if the query is persisted. See storeAsNode(String).

Returns:

the query statement.

getLanguage

java.lang.String getLanguage()

Returns the language set for this query. This will be one of the query language constants returned by QueryManager.getSupportedQueryLanguages().

Returns:

the query language.

getStoredQueryPath

java.lang.String getStoredQueryPath()
                                    throws ItemNotFoundException,
                                           RepositoryException

If this is a Query object that has been stored using storeAsNode(java.lang.String) (regardless of whether it has been saved yet) or retrieved using QueryManager.getQuery(javax.jcr.Node)), then this method returns the path of the nt:query node that stores the query.

Returns:

path of the node representing this query.

Throws:

ItemNotFoundException - if this query is not a stored query.

RepositoryException - if another error occurs.

storeAsNode

Node storeAsNode(java.lang.String absPath)
                 throws ItemExistsException,
                        PathNotFoundException,
                        VersionException,
                        ConstraintViolationException,
                        LockException,
                        UnsupportedRepositoryOperationException,
                        RepositoryException

Creates a node of type nt:query holding this query at absPath and returns that node.

This is a session-write method and therefore requires a Session.save() to dispatch the change.

The absPath provided must not have an index on its final element. If ordering is supported by the node type of the parent node then the new node is appended to the end of the child node list.

An ItemExistsException will be thrown either immediately, on dispatch or on persists, if an item at the specified path already exists and same-name siblings are not allowed. Implementations may differ on when this validation is performed.

A PathNotFoundException will be thrown either immediately, on dispatch or on persists, if the specified path implies intermediary nodes that do not exist. Implementations may differ on when this validation is performed.

A ConstraintViolationExceptionwill be thrown either immediately, on dispatch or on persists, if adding the node would violate a node type or implementation-specific constraint or if an attempt is made to add a node as the child of a property. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately, on dispatch or on persists, if the node to which the new child is being added is read-only due to a checked-in node. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately, on dispatch or on persists, if a lock prevents the addition of the node. Implementations may differ on when this validation is performed.

Parameters:

absPath - absolute path the query should be stored at

Returns:

the newly created node.

Throws:

ItemExistsException - if an item at the specified path already exists, same-name siblings are not allowed and this implementation performs this validation immediately.

PathNotFoundException - if the specified path implies intermediary Nodes that do not exist or the last element of relPath has an index, and this implementation performs this validation immediately.

ConstraintViolationException - if a node type or implementation-specific constraint is violated or if an attempt is made to add a node as the child of a property and this implementation performs this validation immediately.

VersionException - if the node to which the new child is being added is read-only due to a checked-in node and this implementation performs this validation immediately.

LockException - if a lock prevents the addition of the node and this implementation performs this validation immediately.

UnsupportedRepositoryOperationException - if persistent queries are not supported.

RepositoryException - if another error occurs or if the absPath provided has an index on its final element.

bindValue

void bindValue(java.lang.String varName,
               Value value)
               throws java.lang.IllegalArgumentException,
                      RepositoryException

Binds the given value to the variable named varName.

Parameters:

varName - name of variable in query

value - value to bind

Throws:

java.lang.IllegalArgumentException - if varName is not a valid variable in this query.

RepositoryException - if an error occurs.

Since:

JCR 2.0

getBindVariableNames

java.lang.String[] getBindVariableNames()
                                        throws RepositoryException

Returns the names of the bind variables in this query. If this query does not contains any bind variables then an empty array is returned.

Returns:

the names of the bind variables in this query.

Throws:

RepositoryException - if an error occurs.

Since:

JCR 2.0