Like most operations in the JCR API, querying is done through a Session instance, from which can be obtained the QueryManager that defines methods for creating Query objects, storing queries as Nodes in the repository, and reconstituting queries that were stored on Nodes. Thus, querying a repository generally follows this pattern:

// Obtain the query manager for the session ...

javax.jcr.query.QueryManager queryManager = session.getWorkspace().getQueryManager();


// Create a query object ...

String language = ...

String expression = ...

javax.jcr.Query query = queryManager.createQuery(expression,language);


// Execute the query and get the results ...

javax.jcr.QueryResult result = query.execute();


// Iterate over the nodes in the results ...

javax.jcr.NodeIterator nodeIter = result.getNodes();

while ( nodeIter.hasNext() ) {

    javax.jcr.Node node = nodeIter.nextNode();

        ...

}


// Or iterate over the rows in the results ...

String[] columnNames = result.getColumnNames();

javax.jcr.query.RowIterator rowIter = result.getRows();

while ( rowIter.hasNext() ) {

    javax.jcr.query.Row row = rowIter.nextRow();

    // Iterate over the column values in each row ...

    javax.jcr.Value[] values = row.getValues();

    for ( javax.jcr.Value value : values ) {

                ...

    }

    // Or access the column values by name ...

    for ( String columnName : columnNames ) {

        javax.jcr.Value value = row.getValue(columnName);

                ...

    }

}


// When finished, close the session ...

session.logout();

For more detail about these methods or about how to use other facets of the JCR query API, please consult Section 6.7 of the JCR 1.0 specification.

The JCR 1.0 specification uses the XPath query language because node structures in JCR are very analogous to the structure of an XML document. Thus, XPath provides a useful language for selecting and searching workspace content. And since JCR 1.0 defines a mapping between XML and a workspace view called the "document view", adapting XPath to workspace content is quite natural.

A JCR XPath query specifies the subset of nodes in a workspace that satisfy the constraints defined in the query. Constraints can limit the nodes in the results to be those nodes with a specific (primary or mixin) node type, with properties having particular values, or to be within a specific subtree of the workspace. The query also defines how the nodes are to be returned in the result sets using column specifiers and ordering specifiers.

SELECT * FROM [nt:base]

SELECT * FROM [my:type]

SELECT [my:title] FROM [my:type]

SELECT [my:title], [my:text] FROM [my:type]

SELECT [my:title], [my:text] FROM [my:type]

SELECT * FROM [nt:base]

SELECT * FROM [my:type]

SELECT * FROM [my:type] 
WHERE PATH([my:type])> LIKE '/nodes/%'
 AND DEPTH([my:type]) = CAST(2 AS LONG)

SELECT * FROM [my:type] 
WHERE PATH([my:type]) LIKE '/nodes/%'

SELECT * FROM [my:type] 
WHERE PATH([my:type]) LIKE '/nodes/%'
 AND NAME([my:type]) = 'ex:nodeName'

SELECT * FROM [nt:base] 
WHERE [nt:base].prop1 IS NOT NULL

SELECT * FROM [my:type]
WHERE [my:type].prop1 IS NOT NULL

SELECT * FROM [my:type]
WHERE [my:type].prop1 = CAST('true' AS BOOLEAN)

SELECT * FROM [my:type]
WHERE id < 1 AND name = 'john'

SELECT * FROM [my:type]
JOIN [nt:base] as nodeSet1 
  ON ISCHILDNODE(nodeSet1,[my:type])
JOIN [nt:base] as nodeSet2 
  ON ISCHILDNODE(nodeSet2,nodeSet1)
WHERE (NAME(nodeSet1) = 'a' 
  AND NAME(nodeSet2) = 'b')
  AND nodeSet2.id IS NOT NULL

SELECT * FROM [my:type]
JOIN [nt:base] as nodeSet1 
  ON ISCHILDNODE(nodeSet1,[my:type])
JOIN [nt:base] as nodeSet2
  ON ISCHILDNODE(nodeSet2,nodeSet1)
WHERE nodeSet2.id IS NOT NULLL

SELECT * FROM [my:type]
JOIN [nt:base] as nodeSet1 
  ON ISDESCENDANTNODE(nodeSet1,[my:type])
WHERE nodeSet2.id IS NOT NULLL

SELECT * FROM [nt:base]
WHERE PATH([nt:base]) = '/a/b'

SELECT * FROM [nt:base]
WHERE PATH([nt:base]) = '/a/b'

SELECT * FROM [nt:base]
WHERE PATH([nt:base]) = '/a[2]/b'

SELECT * FROM [my:type]
WHERE PATH([nt:base]) = '/a/b[2]/c[4]'
   OR PATH(nodeSet1) LIKE '/a/b[2]/%/c[4]'

SELECT * FROM [my:type]
WHERE PATH([nt:base]) = '/a/b/c/d'
   OR PATH([nt:base]) LIKE '/a/b/%/c/d' 
   OR PATH([nt:base]) LIKE '/a/b/c/%/d'
   OR PATH([nt:base]) LIKE '/a/b/%/c/%/d'

SELECT * FROM [my:type]
WHERE id < 1 AND name = 'john'

SELECT * FROM [my:type]
WHERE PATH([my:type]) = '/a/b/%'

SELECT nodeSet1.title
FROM [nt:base] AS nodeSet1 
ORDER BY nodeSet1.title

SELECT nodeSet1.title
FROM [nt:base] AS nodeSet1 
ORDER BY nodeSet1.title,
         SCORE([nt:base])

The JCR-SQL query language is defined by the JCR 1.0 specification as a way to express queries using strings that are similar to SQL. Support for the language is optional, and in fact this language was deprecated in the JCR 2.0 specification in favor of the improved and more powerful (and more SQL-like) JCR-SQL2 language, which is covered in the next section. As such, ModeShape does not support the original JCR-SQL language.

The JCR-SQL2 query language is defined by the JCR 2.0 specification as a way to express queries using strings that are similar to SQL. This query language is an improvement over the earlier JCR-SQL language, which has been deprecated in JCR 2.0 (see previous section).

ModeShape includes full support for the complete JCR-SQL2 query language. However, ModeShape adds several extensions to make it even more powerful:

The grammar for the JCR-SQL2 query language is actually a superset of that defined by the JCR 2.0 specification, and as such the complete grammar is included here.

QueryCommand ::= Query | SetQuery

SetQuery ::= Query ('UNION'|'INTERSECT'|'EXCEPT') ['ALL'] Query
                 { ('UNION'|'INTERSECT'|'EXCEPT') ['ALL'] Query }

Query ::= 'SELECT' ['DISTINCT'] columns
          'FROM' Source
          ['WHERE' Constraint]
          ['ORDER BY' orderings]
          [Limit]

Source ::= Selector | Join

Selector ::= nodeTypeName ['AS' selectorName]

nodeTypeName ::= Name

	
Join ::= left [JoinType] 'JOIN' right 'ON' JoinCondition
         // If JoinType is omitted INNER is assumed.

left ::= Source
right ::= Source

JoinType ::= Inner | LeftOuter | RightOuter | FullOuter | Cross

Inner ::= 'INNER' ['JOIN']

LeftOuter ::= 'LEFT JOIN' | 'OUTER JOIN' | 'LEFT OUTER JOIN'

RightOuter ::= 'RIGHT OUTER' ['JOIN']

RightOuter ::= 'FULL OUTER' ['JOIN']

RightOuter ::= 'CROSS' ['JOIN']

JoinCondition ::= EquiJoinCondition | SameNodeJoinCondition | 
                  ChildNodeJoinCondition | DescendantNodeJoinCondition

	
EquiJoinCondition ::= selector1Name'.'property1Name '=' selector2Name'.'property2Name

selector1Name ::= selectorName
selector2Name ::= selectorName
property1Name ::= propertyName
property2Name ::= propertyName

	
SameNodeJoinCondition ::= 'ISSAMENODE(' selector1Name ',' selector2Name [',' selector2Path] ')'

selector2Path ::= Path

	
ChildNodeJoinCondition ::= 'ISCHILDNODE(' childSelectorName ',' parentSelectorName ')'

childSelectorName ::= selectorName
parentSelectorName ::= selectorName

	
DescendantNodeJoinCondition ::= 'ISDESCENDANTNODE(' descendantSelectorName 
                                                ',' ancestorSelectorName ')'
descendantSelectorName ::= selectorName
ancestorSelectorName ::= selectorName

	
Constraint ::= ConstraintItem | '(' ConstraintItem ')'

ConstraintItem ::= And | Or | Not | Comparison | Between | PropertyExistence | 
                   SetConstraint | FullTextSearch | SameNode | ChildNode | DescendantNode

And ::= constraint1 'AND' constraint2

constraint1 ::= Constraint
constraint2 ::= Constraint

	
Or ::= constraint1 'OR' constraint2

	
Not ::= 'NOT' Constraint

	
Comparison ::= DynamicOperand Operator StaticOperand

Operator ::= '=' | '!=' | '<' | '<=' | '>' | '>=' | 'LIKE'

	
Between ::= DynamicOperand ['NOT'] 'BETWEEN' lowerBound ['EXCLUSIVE'] 
                                   'AND' upperBound ['EXCLUSIVE']

lowerBound ::= StaticOperand
upperBound ::= StaticOperand

	
PropertyExistence ::= selectorName'.'propertyName 'IS' ['NOT'] 'NULL' | 
                      propertyName 'IS' ['NOT'] 'NULL' /* If only one selector exists in this query */

SetConstraint ::= selectorName'.'propertyName ['NOT'] 'IN' | 
                      propertyName ['NOT'] 'IN' /* If only one selector exists in this query */
                      '(' firstStaticOperand {',' additionalStaticOperand } ')'
firstStaticOperand ::= StaticOperand
additionalStaticOperand ::= StaticOperand

	
FullTextSearch ::= 'CONTAINS(' ([selectorName'.']propertyName | selectorName'.*') 
                           ',' ''' fullTextSearchExpression''' ')'
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      preceding the propertyName is optional */

fullTextSearchExpression ::= FulltextSearch

FulltextSearch ::= Disjunct {Space 'OR' Space Disjunct}

Disjunct ::= Term {Space Term}

Term ::= ['-'] SimpleTerm

SimpleTerm ::= Word | '"' Word {Space Word} '"'

Word ::= NonSpaceChar {NonSpaceChar}

Space ::= SpaceChar {SpaceChar}

NonSpaceChar ::= Char - SpaceChar /* Any Char except SpaceChar */

SpaceChar ::= ' '

Char ::= /* Any character */

	
SameNode ::= 'ISSAMENODE(' [selectorName ','] Path ')' 
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      preceding the path is optional */

ChildNode ::= 'ISCHILDNODE(' [selectorName ','] Path ')' 
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      preceding the path is optional */

DescendantNode ::= 'ISDESCENDANTNODE(' [selectorName ','] Path ')' 
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      preceding the propertyName is optional */

Name ::= '[' quotedName ']' | '[' simpleName ']' | simpleName

quotedName ::= /* A JCR Name (see the JCR specification) */
simpleName ::= /* A JCR Name that contains only SQL-legal 
                  characters (namely letters, digits, and underscore) */

Path ::= '[' quotedPath ']' | '[' simplePath ']' | simplePath

quotedPath ::= /* A JCR Path that contains non-SQL-legal characters */
simplePath ::= /* A JCR Path (rather Name) that contains only SQL-legal 
                    characters (namely letters, digits, and underscore) */

	
StaticOperand ::= Literal | BindVariableValue

Literal
Literal ::= CastLiteral | UncastLiteral

CastLiteral ::= 'CAST(' UncastLiteral ' AS ' PropertyType ')'

PropertyType ::= 'STRING' | 'BINARY' | 'DATE' | 'LONG' | 'DOUBLE' | 'DECIMAL' | 
                 'BOOLEAN' | 'NAME' | 'PATH' | 'REFERENCE' | 'WEAKREFERENCE' | 'URI'
                 /* 'WEAKREFERENCE' is not currently supported in JCR 1.0 */

UncastLiteral ::= UnquotedLiteral | ''' UnquotedLiteral ''' | '"' UnquotedLiteral '"'

UnquotedLiteral ::= /* String form of a JCR Value, as defined in the JCR specification */

	
BindVariableValue ::= '$'bindVariableName

bindVariableName ::= /* A string that conforms to the JCR Name syntax, though the prefix
                        does not need to be a registered namespace prefix. */

	
DynamicOperand ::= PropertyValue | ReferenceValue | Length | NodeName | NodeLocalName | NodePath | NodeDepth | 
                   FullTextSearchScore | LowerCase | UpperCase | Arithmetic | 
                   '(' DynamicOperand ')'

PropertyValue ::= [selectorName'.'] propertyName
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      preceding the propertyName is optional */

ReferenceValue ::= 'REFERENCE(' selectorName '.' propertyName ')' |
                   'REFERENCE(' selectorName ')' |
                   'REFERENCE()' |
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      preceding the propertyName is optional. Also, the property name may be excluded 
                      if the constraint should apply to any reference property. */

Length ::= 'LENGTH(' PropertyValue ')'

NodeName ::= 'NAME(' [selectorName] ')'
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      is optional */

NodeLocalName ::= 'LOCALNAME(' [selectorName] ')'
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      is optional */

NodePath ::= 'PATH(' [selectorName] ')'
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      is optional */

NodeDepth ::= 'DEPTH(' [selectorName] ')'
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      is optional */

FullTextSearchScore ::= 'SCORE(' [selectorName] ')'
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      is optional */

LowerCase ::= 'LOWER(' DynamicOperand ')'

UpperCase ::= 'UPPER(' DynamicOperand ')'

Arithmetic ::= DynamicOperand ('+'|'-'|'*'|'/') DynamicOperand

	
orderings ::= Ordering {',' Ordering}

Ordering ::= DynamicOperand [Order]

Order ::= 'ASC' | 'DESC'

	
columns ::= (Column ',' {Column}) | '*'

Column ::= ([selectorName'.']propertyName ['AS' columnName]) | (selectorName'.*')
                   /* If only one selector exists in this query, explicit specification of the selectorName
                      preceding the propertyName is optional */
selectorName ::= Name
propertyName ::= Name
columnName ::= Name

	
Limit ::= 'LIMIT' count [ 'OFFSET' offset ]
count ::= /* Positive integer value */
offset ::= /* Non-negative integer value */

There are times when a formal structured query language is overkill, and the easiest way to find the right content is to perform a search, like you would with a search engine such as Google or Yahoo! This is where ModeShape's full-text search language comes in, because it allows you to use the JCR query API but with a far simpler, Google-style search grammar.

This query language is actually defined by the JCR 2.0 specification as the full-text search expression grammar used in the second parameter of the CONTAINS(...) function of the JCR-SQL2 language. We just pulled it out and made it available as a first-class query language.

This language allows a JCR client to construct a query to find nodes with property values that match the supplied terms. Nodes that "best" match the terms are returned before nodes that have a lesser match. Of course, ModeShape uses a complex system to analyze the node content and the query terms, and may perform a number of optimizations, such as (but not limited to) eliminating stop words (e.g., "the", "a", "and", etc.), treating terms independent of case, and converting words to base forms using a process called stemming (e.g., "running" into "run", "customers" into "customer").

Search terms can also include phrases by simply wrapping the phrase with double-quotes. For example, the search term 'table "customer invoice"' would rank higher those nodes with properties containing the phrase "customer invoice" than nodes with properties containing just "customer" or "invoice".

Term in the query are implicitly AND-ed together, meaning that the matches occur when a node has property values that match all of the terms. However, it is also possible to put an "OR" in between two terms where either of those terms may occur.

It is also possible to specify that terms should not appear in the results. This is called a negative term, and it reduces the rank of any node whose property values contain the the value. To specify a negative term, simply prefix the term with a hyphen ('-').

The grammar for this full-text search language is specified in Section 6.7.19 of the JCR 2.0 specification, but it is also included here as a convenience.

FulltextSearch ::= Disjunct {Space 'OR' Space Disjunct}

Disjunct ::= Term {Space Term}

Term ::= ['-'] SimpleTerm

SimpleTerm ::= Word | '"' Word {Space Word} '"'

Word ::= NonSpaceChar {NonSpaceChar}

Space ::= SpaceChar {SpaceChar}

NonSpaceChar ::= Char - SpaceChar /* Any Char except SpaceChar */

SpaceChar ::= ' '

Char ::= /* Any character */