With ModeShape, all query operations can be performed using only the JCR API interfaces. The first step is to obtain the QueryManager from your Session instance. The QueryManager interface defines methods for creating Query objects, executing queries, storing queries (not results) 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 chapter 6 of the JCR 2.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.

ModeShape offers a bit more functionality in the "jcr:contains(...)" clauses than required by the specification. In particular, the second parameter specifies the search expression, and for these ModeShape accepts full-text search language expressions, including wildcard support.

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[1]/b[2]'

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[%]/%'

/a/b/c[2]/d[%]/%/e[_]

/a[%]/b[%]/c[2]/d[%]/%/e[_]

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

SELECT *
FROM [nt:base] AS nodeSet1 
ORDER BY SCORE(nodeSet1)

SELECT *
FROM [my:type] AS nodeSet1 
ORDER BY SCORE(nodeSet1)

SELECT jcr:path
FROM [nt:base] AS nodeSet1 
ORDER BY PATH(nodeSet1)

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

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.

The JCR 2.0 specification defines how nodes in a repository are mapped onto relational tables queryable through a SQL-like language, including JCR-SQL and JCR-SQL2. Basically, each node type is mapped as a relational view with a single column for each of the node type's (residual and non-residual) property definitions. Conceptually, each node in the repository then appears as a record inside the view corresponding to the node type for which "Node.isNodeType(nodeTypeName)" would return true.

Since each node likely returns true from this method for multiple node type (e.g., the primary node type, the mixin types, and all supertypes of the primary and mixin node types), all nodes will likely appear as records in multiple views. And since each view only exposes those properties defined by (or inherited by) the corresponding node type, a full picture of a node will likely require joining the views for multiple node types. This special kind of join, where the nodes have the same identity on each side of the join, is referred to as an identity join, and is handled very efficiently by ModeShape.

ModeShape includes support for the JCR-SQL language, and adds several extensions to make it even more powerful and useful:

The grammar for the JCR-SQL query language is actually a superset of that defined by the JCR 1.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 From [Where] [OrderBy] [Limit]

Select ::= 'SELECT' ('*' | Proplist ) 

From ::= 'FROM' NtList 

Where ::= 'WHERE' WhereExp

OrderBy ::= 'ORDER BY' propname [Order] {',' propname [Order]}

Order ::= 'DESC' | 'ASC'

Proplist ::= propname {',' propname}

NtList ::= ntname {',' ntname}

WhereExp ::= propname Op value |
             propname 'IS' ['NOT'] 'NULL' |
             like | 
             contains | 
             whereexp ('AND'|'OR') whereexp | 
             'NOT' whereexp |
             '(' whereexp ')' | 
             joinpropname '=' joinpropname |
             between |
             propname ['NOT'] 'IN' '(' value {',' value } ')'

Op ::= '='|'>'|'<'|'>='|'<='|'<>'

joinpropname ::= quotedjoinpropname | unquotedjoinpropname
quotedjoinpropname ::= ''' unquotedjoinpropname '''
unquotedjoinpropname ::= ntname '.jcr:path'

propname ::= quotedpropname | unquotedpropname
quotedpropname ::= ''' unquotedpropname '''
unquotedpropname ::= /* A property name, possible a pseudo-property: jcr:score or jcr:path */

ntname ::= quotedntname | unquotedntname 
quotedntname ::= ''' unquotedntname ''' 
unquotedntname ::= /* A node type name */ 

value ::= literal | subquery

literal ::= ''' literalvalue ''' | literalvalue
literalvalue ::= /* A property value (in standard string form) */

subquery ::= '(' QueryCommand ')' | QueryCommand

like ::= propname 'LIKE' likepattern [ escape ]
likepattern ::= ''' likechar { likepattern } '''
likechar ::= char | '%' | '_'

escape ::= 'ESCAPE' ''' likechar '''

char ::= /* Any character valid within the string representation of a value
            except for the characters % and _ themselves. These must be escaped */

contains ::= 'CONTAINS(' scope ',' searchexp ')'
scope ::= unquotedpropname | '.'
searchexp ::= ''' exp '''
exp ::= ['-']term {whitespace ['OR'] whitespace ['-']term}
term ::= word | '"' word {whitespace word} '"'
word ::= /* A string containing no whitespace */
whitespace ::= /* A string of only whitespace*/

between ::= propname ['NOT'] 'BETWEEN' lowerBound ['EXCLUSIVE'] 
                                 'AND' upperBound ['EXCLUSIVE']
lowerBound ::= value
upperBound ::= value

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

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 JCR-SQL language, providing among other things far richer specifications of joins and criteria.

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 | Subquery

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. */

Subquery ::= '(' QueryCommand  ')' |
             QueryCommand

	
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 */

 ... selector1.[jcr:path] = selector2.[jcr:path] ... 

 ... ISSAMENODE(selector1,selector2) ... 

 SELECT * FROM [nt:base] 

 SELECT [jcr:primaryType] FROM [nt:base] 

 SELECT [jcr:primaryType], [jcr:path], [mode:depth] FROM [nt:base] 

[mix:created] mixin 
  - jcr:created (date) protected  
  - jcr:createdBy (string) protected

[nt:hierarchyNode] > mix:created abstract 

[nt:file] > nt:hierarchyNode 
  + jcr:content (nt:base) primary mandatory

 SELECT * FROM [nt:file] 

SELECT [jcr:primaryType], [jcr:created], [jcr:createdBy], 
       [jcr:path], [jcr:name], [jcr:score], [mode:localName], [mode:depth] 
FROM [nt:file] 

SELECT [jcr:primaryType], [jcr:created], [jcr:createdBy], [jcr:path] FROM [nt:file] 
WHERE LOCALNAME() LIKE '%.txt'

SELECT [jcr:primaryType], [jcr:created], [jcr:createdBy], [jcr:path] FROM [nt:file] 
WHERE [mode:localName] LIKE '%.txt'

SELECT "jcr:primaryType", "jcr:created", "jcr:createdBy", "jcr:path" FROM "nt:file" 
WHERE "mode:localName" LIKE '%.txt'

SELECT file.*, ref.* FROM [nt:file] AS file JOIN [mix:referenceable] AS ref
JOIN ON ISSAMENODE(file,ref)

SELECT file.[jcr:primaryType], file.[jcr:created], file.[jcr:createdBy], ref.[jcr:uuid],
       file.[jcr:path], file.[jcr:name], file.[jcr:score], file.[mode:localName], file.[mode:depth],
       ref.[jcr:path], ref.[jcr:name], ref.[jcr:score], ref.[mode:localName], ref.[mode:depth] 
FROM [nt:file] AS file JOIN [mix:referenceable] AS ref
JOIN ON ISSAMENODE(file,ref)

SELECT file.[jcr:primaryType] AS primaryType, 
       file.[jcr:created] AS created, 
       file.[jcr:createdBy] AS createdBy, 
       ref.[jcr:uuid] AS uuid,
       file.[jcr:path] AS path,
       file.[jcr:name] AS name,
       file.[jcr:score] AS score,
       file.[mode:localName] AS localName, 
       file.[mode:depth] AS depth
FROM [nt:file] AS file JOIN [mix:referenceable] AS ref
JOIN ON ISSAMENODE(file,ref)

SELECT file."jcr:primaryType" AS primaryType, 
       file."jcr:created" AS created, 
       file."jcr:createdBy" AS createdBy, 
       ref."jcr:uuid" AS uuid,
       file."jcr:path" AS path,
       file."jcr:name" AS name,
       file."jcr:score" AS score,
       file."mode:localName" AS localName, 
       file."mode:depth" AS depth
FROM "nt:file" AS file JOIN "mix:referenceable" AS ref
JOIN ON file."jcr:path" = ref."jcr:path"

SELECT [jcr:primaryType], [jcr:created], [jcr:createdBy], [jcr:path] FROM [nt:file]
UNION
SELECT [jcr:primaryType], [jcr:created], [jcr:createdBy], [jcr:path] FROM [nt:folder]

SELECT [jcr:primaryType], [jcr:created], [jcr:createdBy], [jcr:path] FROM [nt:file] 
WHERE PATH() IN ( 
   SELECT [vdb:originalFile] FROM [vdb:virtualDatabase]
   WHERE [vdb:version] <= $maxVersion AND CONTAINS([vdb:description],'xml OR xml maybe')
) 

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, such that a full-text search query supplied by the user, full-text-query, is equivalent to executing this JCR-SQL2:

 SELECT * FROM [nt:base] WHERE CONTAINS([nt:base],'full-text-query') 

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.

By default, all terms are assumed to be positive terms, in the sense that the occurrence of the term will increase the rank of any nodes containing the value. However, it is 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 ('-').

Each term may also contain wildcards to specify the pattern to be matched (or negated). ModeShape supports two different sets of wildcards:

The former are wildcards that are more commonly used in various systems (including older JCR repository implementations), while the latter are the wildcards used in LIKE expressions in both JCR-SQL and JCR-SQL2. Both families are supported for convenience, and you can also mix and match and combine the various wildcards, such as 'ta**bl_' and 'ta__ble%*'. (Of course, placing multiple '*' or '%' characters next to each other offers no real benefit, as it is equivalent to a single '*' or '%'.)

If you want to use these characters literally in a term and do not want them to be treated as wildcards, they must be escaped by prefixing them with a '\' character. For example, this full text search expression:

 table\* 'customer invoice\?' 

will would rank higher those nodes with properties containing 'table*' (including the asterisk) and those containing the phrase "customer invoice?" (including the question mark). To use a literal backslash character, simply escape it as well.

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 */

JCR 2.0 introduces a new API for programmatically constructing a query. This API allows the client to construct the lower-level objects for each part of the query, and is a great fit for applications that would otherwise generate fairly complicated query expressions. Using this API is a matter of getting the QueryObjectModelFactory from the session's QueryManager, and using the factory to create the various components, starting with the lowest-level components. Then, these lower-level components can be passed to other factory methods to create the higher-level components, and so on, until finally the createQuery(...) method is called to return the QueryObjectModel.

Here is a simple example that shows how this is done for the simple query "SELECT * FROM [nt:unstructured] AS unstructNodes":

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

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


// Create a query object model factory ...

QueryObjectModelFactory factory = queryManager.getQOMFactory();


// Create the FROM clause: a selector for the [nt:unstructured] nodes ...

Selector source = factory.selector("nt:unstructured","unstructNodes");


// Create the SELECT clause (we want all columns defined on the node type) ...

Column[] columns = null;


// Create the WHERE clause (we have none for this query) ...

Constraint constraint = null;


// Define the orderings (we have none for this query)...

Ordering[] orderings = null;


// Create the query ...

QueryObjectModel query = factory.createQuery(source,constraint,orderings,columns);

 

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

// (This is the same as before.)

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

From this point on, processing the results is the same as when using the JCR Query API:

// 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();

Of course, most queries will create the columns, orderings, and constraints using the QueryObjectModelFactory, whereas the example above just assumes all of the columns, no orderings, and no constraints.