org.apache.jackrabbit.commons.query

Class GQL

java.lang.Object

org.apache.jackrabbit.commons.query.GQL

public final class GQL
extends Object

GQL is a simple fulltext query language, which supports field prefixes similar to Lucene or Google queries.

GQL basically consists of a list of query terms that are optionally prefixed with a property name. E.g.: title:jackrabbit. When a property prefix is omitted, GQL will perform a fulltext search on all indexed properties of a node. There are a number of pseudo properties that have special meaning:

• path: only search nodes below this path. If you specify more than one term with a path prefix, only the last one will be considered.
• type: only return nodes of the given node types. This includes primary as well as mixin types. You may specify multiple comma separated node types. GQL will return nodes that are of any of the specified types.
• order: order the result by the given properties. You may specify multiple comma separated property names. To order the result in descending order simply prefix the property name with a minus. E.g.: order:-name. Using a plus sign will return the result in ascending order, which is also the default.
• limit: limits the number of results using an interval. E.g.: limit:10..20 Please note that the interval is zero based, start is inclusive and end is exclusive. You may also specify an open interval: limit:10.. or limit:..20 If the dots are omitted and only one value is specified GQL will return at most this number of results. E.g. limit:10 (will return the first 10 results)
• name: a constraint on the name of the returned nodes. The following wild cards are allowed: '*', matching any character sequence of length 0..n; '?', matching any single character.

Property name

Instead of a property name you may also specify a relative path to a property. E.g.: "jcr:content/jcr:mimeType":text/plain

Double quotes

The property name as well as the value may enclosed in double quotes. For certain use cases this is required. E.g. if you want to search for a phrase: title:"apache jackrabbit". Similarly you need to enclose the property name if it contains a colon: "jcr:title":apache, otherwise the first colon is interpreted as the separator between the property name and the value. This also means that a value that contains a colon does not need to be enclosed in double quotes.

Escaping

To imply double-quotes("), backslash(\), and colon(:) literally you can escape them with a backslash. E.g. similar to example above in quoting for colon, "jcr:title":apache is equiavalent to jcr\:title:apache.

Auto prefixes

When a property, node or node type name does not have a namespace prefix GQL will guess the prefix by looking up item and node type definitions in the node type manager. If it finds a definition with a local name that matches it will automatically assign the prefix that is in the definition. This means that you can write: 'type:file' and GQL will return nodes that are of node type nt:file. Similarly you can write: order:lastModified and your result nodes will be sorted by their jcr:lastModified property value.

Common path prefix

For certain queries it is useful to specify a common path prefix for the GQL query statement. See execute(String, Session, String). E.g. if you are searching for file nodes with matches in their resource node. The common path prefix is prepended to every term (except to pseudo properties) before the query is executed. This means you can write: 'type:file jackrabbit' and call execute with three parameters, where the third parameter is jcr:content. GQL will return nt:file nodes with jcr:content nodes that contain matches for jackrabbit.

Excerpts

To get an excerpt for the current row in the result set simply call Row.getValue("rep:excerpt()");. Please note that this is feature is Jackrabbit specific and will not work with other implementations!

Parser callbacks

You can get callbacks for each field and query term pair using the method parse(String, Session, ParserCallback). This may be useful when you want to do some transformation on the GQL before it is actually executed.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	GQL.Filter Defines a filter for query result rows.
static interface	GQL.ParserCallback Defines a callback interface that may be implemented by client code to get a callback for each GQL term that is parsed.

Method Summary

Modifier and Type	Method and Description
static RowIterator	execute(String statement, Session session) Executes the GQL query and returns the result as a row iterator.
static RowIterator	execute(String statement, Session session, String commonPathPrefix) Executes the GQL query and returns the result as a row iterator.
static RowIterator	execute(String statement, Session session, String commonPathPrefix, GQL.Filter filter) Executes the GQL query and returns the result as a row iterator.
static RowIterator	executeXPath(String jcrQuery, String jcrQueryLanguage, Session session, String commonPathPrefix, GQL.Filter filter) Executes the GQL query and returns the result as a row iterator.
static void	parse(String statement, Session session, GQL.ParserCallback callback) Parses the given statement and generates callbacks for each GQL term parsed.
static String	translateToXPath(String statement, Session session, String commonPathPrefix) Translate the GQL query to XPath.

Methods inherited from class java.lang.Object

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

Method Detail

execute

public static RowIterator execute(String statement,
                                  Session session)

Executes the GQL query and returns the result as a row iterator.

Parameters:

statement - the GQL query.

session - the session that will execute the query.

Returns:

the result.

execute

public static RowIterator execute(String statement,
                                  Session session,
                                  String commonPathPrefix)

Executes the GQL query and returns the result as a row iterator.

Parameters:

statement - the GQL query.

session - the session that will execute the query.

commonPathPrefix - a common path prefix for the GQL query.

Returns:

the result.

execute

public static RowIterator execute(String statement,
                                  Session session,
                                  String commonPathPrefix,
                                  GQL.Filter filter)

Executes the GQL query and returns the result as a row iterator.

Parameters:

statement - the GQL query.

session - the session that will execute the query.

commonPathPrefix - a common path prefix for the GQL query.

filter - an optional filter that may include/exclude result rows.

Returns:

the result.

executeXPath

public static RowIterator executeXPath(String jcrQuery,
                                       String jcrQueryLanguage,
                                       Session session,
                                       String commonPathPrefix,
                                       GQL.Filter filter)

Executes the GQL query and returns the result as a row iterator.

Parameters:

jcrQuery - the native JCR query.

jcrQueryLanguage - the JCR query language

session - the session that will execute the query.

commonPathPrefix - a common path prefix for the GQL query.

filter - an optional filter that may include/exclude result rows.

Returns:

the result.

translateToXPath

public static String translateToXPath(String statement,
                                      Session session,
                                      String commonPathPrefix)
                               throws RepositoryException

Translate the GQL query to XPath.

Parameters:

statement - the GQL query.

session - the session that will execute the query.

commonPathPrefix - a common path prefix for the GQL query.

Returns:

the xpath statement.

Throws:

RepositoryException

parse

public static void parse(String statement,
                         Session session,
                         GQL.ParserCallback callback)
                  throws RepositoryException

Parses the given statement and generates callbacks for each GQL term parsed.

Parameters:

statement - the GQL statement.

session - the current session to resolve namespace prefixes.

callback - the callback handler.

Throws:

RepositoryException - if an error occurs while parsing.