A repository maysupportquery.
The structure andevaluation semantics of a query are defined by anabstract querymodel (AQM) for which two concrete language bindings arespecified:
JCR-SQL2, which expressesa query as a string with syntax similar to SQL, and
JCR-JQOM(JCR JavaQuery Object Model), which expresses a query as a tree of Javaobjects.
The languages are bothdirect mappings of the AQM and are therefore equally expressive; anyquery expressed in one can be machine-transformed to the other.
Whether animplementation supports query can be determined by querying therepository descriptor table with the key
.
The returned arraycontains the constants representing the supported languages (see§24.2Repository Descriptors). If a repository supportsquery it must return at least the constants for the two JCR-definedlanguages,
and
,
indicating support forthose languages. In addition, a repository may support other querylanguages. These can be either additional language bindings to theAQM or completely independent of that model.
JCR 1.0 defines adialect of SQL different from JCR-SQL2, as well as a dialect ofXPath. Support for these languages is deprecated.
Support forjoinsis optional beyond support for query itself. The extent of joinsupport can be determined by querying the repository descriptortable with the key
.
The value returnedwill be one of
:Joins are not supported and therefore queries are limited to asingle selector.
:Inner joins are supported.
:Inner and outer joins are supported.
This sectionintroduces how queries are specified and evaluated in the AQM.
A query has one ormoreselectors. When the query is evaluated, each selectorindependently selects a subset of the nodes in the workspace basedon node type.
In a repository thatdoes not supportjoins, a query will have only oneselector.
If the query has morethan one selector, it also has one or morejoins thattransform the sets of nodes selected by each selector into a singleset ofnode-tuples.
The membership of theset of node-tuples depends on thejoin type andjoincondition of each join. The join type can beinner,left-outer, orright-outer. The join condition cantest the equality of properties' values or the hierarchicalrelationship between nodes.
If the query hasnselectors, it hasn - 1 joins resulting in a set ofn-tuples.For example, if the query has two selectors, it will have one joinand produce a set of 2-tuples. If it has three selectors, it willhave two joins and produce a set of 3-tuples. If it has only oneselector, it will not have any joins and will produce a set of1-tuples, that is, the nodes selected by its only selector.
Support forjoinsis optional. In a repository thatdoes not supportjoins,the node-tuples produced are necessarily singletons. In other words,each node in the set produced by the (one and only) selector isconverted directly into a node-tuple of size one. All furtherprocessing within the query evaluation operates on these tuples justas it would on tuples of size greater than one.
A query can specify aconstraint to filter the set of node-tuples by anycombination of:
Absolute or relative path, forexample:
The node reachedby path
Nodes that arechildren of
Nodes that aredescendants of
Name of the node, for example:
Nodes named
Value of a property, for example:
Nodes whoseproperty is after
Length of a property, forexample:
Nodes whoseproperty is longer than 100 KB
Existence of a property, forexample:
Nodes with aproperty
Full-text search, for example:
Nodes which have a property thatcontains the phrase “beautiful sunset”
A query can specifyorderings to sort the filtered node-tuples by property value.
The filtered andsorted node-tuples form thequery results. The query resultsare available in two formats:
A list of node-tuples. For eachnode-tuple, you can retrieve the node for each selector. In arepository that does not supportjoins there will be onlyone selector and consequently only one node per tuple.
A table whose rows are thenode-tuples and whose columns are properties of the nodes in thenode-tuples. This is referred to as the tabular view of the queryresults. A query can specify which properties appear as columns inthe tabular view.
When testing forequality or order of two property values of the same type, the queryoperators conform to the definitions in §3.6.5Comparison ofValues.
When testing forequality or order of two property values of differing type, thequery operators perform standard property type conversion (see§3.6.4Property Type Conversion) and conform to standardvalue comparison (see §3.6.5Comparison of Values).
Support for equalityand order comparison ofvalues is not required.
To be successfullyevaluated and produce query results, a query must bevalid.
A query isinvalidif:
it cannot be expressed in theAQM, or
it can beexpressed in the AQM, but fails a validation constraint defined in§6.7Abstract Query Model and Language Bindings.
An invalid querycauses the repository to throw.Which method invocation throws this exception is implementationdetermined, but for an invalid query, the exception must be thrownno later than completion of the.
A querymustsearch the persistent workspace associated with the current session.Itmay take into account pending changes to the persistentworkspace; that is, changes which are either unsaved or, within atransaction, saved but uncommitted.
Three notations areused in the following sections: the AQM type grammar, the JCR-SQL2EBNF grammar and the JCR-JQOM Java API.
The AQM is defined asa set of abstract types. The type grammar is written like this:
which means:
The typehas 4 attributes:
:mandatory, of type ,which is an enumeration with possible values,and.
:optional, of type
:a list of one or more items
:a list of zero or more items
The type is a subtype of .It inherits 'sattributes, and adds:
:mandatory, a string
JCR–SQL2 is amapping of the AQM to a string serialization based on the SQLlanguage.
Each non-terminal inthe JCR-SQL2 EBNF grammar corresponds to the type of the same namein the AQM grammar. The semantics of each JCR-SQL2 production isdescribed by reference to the semantics of the corresponding AQMproduction. The two grammars are, however, entirely distinct andself- contained. Care should be taken not to mix productions fromone grammar with those of the other.
The JCR-SQL2 grammaris written like this:
Throughout thissection string literals that appear in the syntactic grammardefining JCR-SQL2 must be interpreted as specified in §1.3.1StringLiterals in Syntactic Grammars except that each character in thestring literal must be interpreted as representing both upper andlower case versions. In other words, implementations must becase-insensitive with regard to JCR-SQL2.
JCR-JQOM is a mappingof the AQM to a Java API.
Each method andparameter name of the JCR-JQOM Java API corresponds to the type ofthe same name in the AQM grammar. The semantics of each JCR-JQOMmethod is described by reference to the semantics of thecorresponding AQM production.
A JCR-JQOM query isbuilt by assembling objects created using the factory methods of.
For each AQM type, thefollowing are listed:
If the AQM type is anon-enumandnon-abstract (in the AQM sense, not the Java sense) thenthe factory method ofused to create an instance of that type is listed.
If the AQM type isnon-enumthen the corresponding Java interface is listed.
If the AQM type is anenumthen the corresponding constants ofare listed.
Unless otherwiseindicated, the Java interfaces listed in this section are in thepackage.
The following sectiondescribes the AQM grammar and its mapping to JCR-SQL2 and JCR-JQOM.For each AQM production, a description of its semantics is provided,followed by the corresponding JCR-SQL2 production and thecorresponding JCR-JQOM methods.
For queries with onlyone selector the JCR-SQL2 syntax permits the selector name to beomitted. In such cases the implementation must automaticallygenerate a selector name for internal use. If the resulting query islater examined through the JCR-JQOM API, the automatically producedselector name will be seen.
AQM
Aconsists of:
A.When the query is evaluated, theevaluates its selectors and the joins between them to produce a(possibly empty) set of node-tuples. This is a set of 1-tuples ifthe query has one selector (and therefore no joins), a set of2-tuples if the query has two selectors (and therefore one join), aset of 3-tuples if the query has three selectors (two joins), andso forth.
An optional.When the query is evaluated, the constraint filters the set ofnode-tuples.
A list of zero or mores.The orderings specify the order in which the node-tuples appear inthe query results. The relative order of two node-tuples isdetermined by evaluating the specified orderings, in list order,until encountering an ordering for which one node-tuple precedesthe other. If no orderings are specified, or if there is noordering specified in which one node-tuple precedes the other, thenthe relative order of the node-tuples is implementation determined(and may be arbitrary).
A list of zero or moresto include in the tabular view of the query results. If no columnsare specified, the columns available in the tabular view areimplementation determined, but minimally include, for eachselector, a column for each single-valued non-residual property ofthe selector's node type.
JCR-SQL2
JCR-JQOM
A query is representedby aobject, created with:
extendsand declares:
AQM
Evaluates to a set ofnode-tuples.
JCR-SQL2
JCR-JQOM
is an empty interface with subclassesand.
AQM
Selects a subset ofthe nodes in the workspace based on node type.
The query is invalidifrefers to a node type that has aqueryable node typeattribute of(see §3.7.1.5Queryable Node Type). Otherwise, if thequeryable node type attribute is true, the following holds:
A selector selectsevery node in the workspace, subject to access control constraints,that satisfies at least one of the following conditions:
the node’s primary node type is,or
the node’s primary node type isa subtype of,or
the node has a mixin node typethat is,or
the node has a mixin node typethat is a subtype of.
A selector has athat can be used elsewhere in the query to identify the selector.
The query isinvalidifis identical to theof another selector in the query.
The query is alsoinvalid if is not a valid JCR name or is a valid JCR name but not the name of anode type available in the repository.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
A JCR name.
The query isinvalidif the name does not satisfy either theproduction in §3.2.5.1Expanded Form or theproduction in §3.2.5.2Qualified Form.
JCR-SQL2
JCR-JQOM
A JCR name inform (either qualified or expanded).
Support forjoinsis optional.
AQM
Performs a joinbetween two node-tuple sources.
Ifevaluates toL, a set ofm-tuples, andevaluates toR, a set ofn-tuples, then the joinevaluates toJ, a set of (m + n)-tuples. The membersofJdepend on theand.
LetL xRbe the Cartesian product ofL andR as a set of (m+ n)-tuples
LxR = { ℓr: ℓL,rR}
andc(A)be the selection overA of its members satisfyingc
c(A)= { a : aA,c(a)}
Then ifis:
J=c(LxR)
Otherwise, ifis:
J =c(LxR)(L–L(c(LxR)))
whereL(c(LxR)) is the projection of them-tuples contributed byL from the(m + n)-tuples ofc(LxR).
Otherwise, ifis:
J =c(LxR)(R–R(c(LxR)))
whereR(c(LxR)) is the projection of then-tuples contributed byR from the(m + n)-tuples ofc(LxR).
The query isinvalidifis the same source as.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
Support forjoinsis optional.
AQM
JCR-SQL2
JCR-JQOM
A join type is aconstant. One of:
Support forjoinsis optional.
AQM
Filters the set ofnode-tuples formed from a join.
JCR-SQL2
JCR-JQOM
is an empty interface with subclasses,,and.
Support forjoinsis optional.
AQM
Tests whether the value of a propertyin a first selector is equal to the value of a property in a secondselector.
A node-tuple satisfies the constraintonly if:
thenode has a property named,and
thenode has a property named,and
the value of propertyis equal to the value of property,as defined in §3.6.5Comparison of Values.
The query isinvalid if
eitheroris not the name of a selector in the query, or
is equal to,or
theis not the same property type as,or
eitheroris a multi-valued property, or
eitheroris aproperty and equality test forproperties is not supported (see §3.6.6Value.equals Method).
JCR-SQL2
JCR-JQOM
Anis created with:
extends and declares:
Support forjoinsis optional.
AQM
Tests whether two nodes are “thesame” according to themethod.
Ifis omitted:
Tests whether thenode is the same as thenode. A node-tuple satisfies the constraint only if:
would return ,whereis the node for the selectorandis the node for the selector.
Otherwise, ifis specified:
Tests whether thenode is the same as a node identified by relative pathfrom thenode. A node-tuple satisfies the constraint only if:
would return,whereis the node for the selectorandis the node for the selector.
The query isinvalid if:
is not the name of a selector in the query, or
is not the name of a selector in the query, or
is the same as,or
is not a syntactically valid relative path, as defined in §3.4.3.3Lexical Path Grammar. However, ifis syntactically valid but does not identify a node in theworkspace visible to this session, the query is valid but theconstraint is not satisfied.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
Support forjoinsis optional.
AQM
Tests whether thenode is a child of thenode. A node-tuple satisfies the constraint only if:
would return ,whereis the node for the selectorandis the node for the selector.
The query isinvalid if:
is not the name of a selector in the query, or
is not the name of a selector in the query, or
is the same as.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
Support forjoinsis optional.
AQM
Tests whether thenode is a descendant of thenode. A node-tuple satisfies the constraint only if:
would returnfor some non-negative integer,whereis the node for the selectorandis the node for the selector.
The query isinvalid if:
is not the name of a selector in the query, or
is not the name of a selector in the query, or
is the same as .
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Filters the set of node-tuples formedby evaluating the query's selectors and the joins between them.
To be included in the query results, anode-tuple must satisfy the constraint.
JCR-SQL2
In JCR-SQL2, thefollowing precedence classes apply, in order of evaluation:
Class | ConstraintProduction | JCR-SQL2 Syntax |
1 | (grouping with parentheses) | |
2 | ,,,,,, | |
3 | ||
4 | ||
5 |
JCR-JQOM
is an empty interface with subclasses,,,,,,,and.
AQM
Performs a logical conjunction of twoother constraints.
To satisfy the constraint, a node-tuple must satisfy both and .
JCR-SQL2
JCR-JQOM
Anis created with:
extendsand declares:
AQM
Performs a logical disjunction of twoother constraints.
To satisfy the constraint, the node-tuple must either:
satisfy but not ,or
satisfy but not ,or
satisfy both and .
JCR-SQL2
JCR-JQOM
Anis created with:
extendsand declares:
AQM
Performs a logical negation of anotherconstraint.
To satisfy the constraint, the node-tuple mustnot satisfy .
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Filters node-tuples based on theoutcome of a binary operation.
For any comparison, always evaluates to a scalar value. In contrast, may evaluate to an array of values (for example, the values of amulti-valued property), in which case the comparison is separatelyperformed for each element of the array, and the constraint is satisfied as a whole if the comparison againstanyelement of the array is satisfied.
If and evaluate to values of different property types, the value ofis converted to the property type of the value of as described in §3.6.4 Property Type Conversion. If the typeconversion fails, the query isinvalid.
Given an operatorand a property instanceof property type,can be compared usingonly if:
The implementation supportscomparison of properties of typeusing.For example, some implementations may permitandas comparison operators forproperties while others may not.
Assuming that comparison ofproperties of typeis supported in general, the property definition that applies to(found in the node type of'sparent node) must also listamong itsavailable query operators(see §3.7.3.3AvailableQuery Operators).
If is not supported for the property type of ,the query isinvalid.
If evaluates to (for example, if the operand evaluates the value of a property whichdoes not exist), the constraint is not satisfied.
The operator is satisfiedonly if the value ofis equal to the value of ,as described in §3.6.5Comparison of Values.
The operator is satisfiedunless the value ofis equal tothe value of ,as described in §3.6.5Comparison of Values.
The operator is satisfiedonly if the value ofis orderedbefore the value of ,as described in §3.6.5Comparison of Values.
The operator is satisfiedunless the value ofis orderedafter the value of ,as described in §3.6.5Comparison of Values.
The operator is satisfiedonly if the value ofis orderedafter the value of ,as described in §3.6.5Comparison of Values.
The operator is satisfiedunless the value ofis orderedbefore the value of ,as described in §3.6.5Comparison of Values.
The operator is satisfiedonly if the value ofmatches the pattern specified by the value of ,where in the pattern:
the character “”matches zero or more characters, and
the character “”(underscore) matches exactly one character, and
the string “”matches the character “”,and
all other characters matchthemselves.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
JCR-SQL2
JCR-JQOM
An operator is aconstant. One of:
AQM
Tests the existence of a property.
A node-tuple satisfies the constraintif the node has a property named .
The query isinvalid ifis not the name of a selector in the query.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Performs a full-text search.
The full-text search expression isevaluated against the set of full-text indexed properties within thefull-text search scope. If is specified, the full-text search scope is the property of thatname on the node in the node-tuple; otherwise the full-text search scope isimplementation determined.
Whether a particular property isfull-text indexed can be determined by thefull-text searchableattribute of its property definition (see §3.7.3.4Full-TextSearchable).
It is implementation-determinedwhether is independently evaluated against each full-text indexed propertyin the full-text search scope, or collectively evaluated against theset of such properties using some implementation-determinedmechanism.
Similarly, for multi-valuedproperties, it is implementation-determined whetheris independently evaluated against each element in the array ofvalues, or collectively evaluated against the array of values usingsome implementation-determined mechanism.
Theis a,meaning that it may be either a literal JCR value or a boundvariable (which evaluates to a JCR value). The value must be a(or convertible to a)that conforms to the following grammar:
U+0020 */
A query satisfies a constraint if the value (or values) of the full-text indexedproperties within the full-text search scope satisfy the specified,evaluated as follows:
Anot preceded with “”(minus sign) is satisfied only if the valuecontains thatterm.
A term preceded with “”(minus sign) is satisfied only if the valuedoes not containthat term.
Terms separated by whitespace areimplicitly “ANDed”.
Terms separated by “OR” are“ORed”.
“AND” has higher precedencethan “OR”.
Within a term, each “”(double quote), “”(minus sign), and “”(backslash) must be escaped by a preceding “”.
The query isinvalid if:
is not the name of a selector in the query, or
does not conform to the above grammar (as augmented by theimplementation).
The grammar and semantics describedabove defines theminimal requirement, meaning that anysearch string accepted as valid by an implementation must conform tothis grammar. An implementation may, however, restrict acceptablesearch strings further by augmenting this grammar and expanding thesemantics appropriately.
If is specified but, for a node-tuple, the node does not have a property named ,the query isvalid but the constraint is not satisfied.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Tests whether the node is reachable by the absolute path specified. A node-tuplesatisfies the constraint only if:
would return ,where is the node for the specified selector.
The query isinvalid if:
is not the name of a selector in the query, or
is not a syntactically valid absolute path (see §3.3.4 LexicalPath Grammar). Note, however, that if is syntactically valid but does not identify a node in theworkspace (or the node is not visible to this session, because ofaccess control constraints), the query isvalid but theconstraint is not satisfied.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Tests whether the node is a child of a node reachable by the absolute path specified.A node-tuple satisfies the constraint only if:
would return ,where is the node for the specified selector.
The query isinvalid if:
is not the name of a selector in the query, or
is not a syntactically valid absolute path (see §3.3.4 LexicalPath Grammar). Note, however, that if is syntactically valid but does not identify a node in theworkspace (or the node is not visible to this session, because ofaccess control constraints), the query isvalid but theconstraint is not satisfied.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Tests whether the node is a descendant of a node reachable by the absolute pathspecified. A node-tuple satisfies the constraint only if:
would return for some non-negative integer ,where is the node for the specified selector.
The query isinvalid if:
is not the name of a selector in the query, or
is not a syntactically valid absolute path (see §3.3.4 LexicalPath Grammar). Note, however, that if is syntactically valid but does not identify a node in theworkspace (or the node is not visible to this session, because ofaccess control constraints), the query isvalid but theconstraint is not satisfied.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
A JCR path.
JCR-SQL2
JCR-JQOM
A JCR path in stringform (standard, non-standard, normalizedor non-normalized, see §3.3.5Standard and Non-Standard Formand §3.3.6.3Normalized Paths).
AQM
JCR-SQL2
JCR-JQOM
is an empty interface with subclassesand.
AQM
An operand whose value can bedetermined from static analysis of the query, prior to itsevaluation.
JCR-SQL2
JCR-JQOM
is an empty interface with subclassesand.
AQM
An operand whose value can only bedetermined in evaluating the query.
JCR-SQL2
JCR-JQOM
is an empty interface with subclasses,,,,,and.
AQM
Evaluates to the value (or values, ifmulti-valued) of a property.
If, for a node-tuple, the node does not have a property named ,the operand evaluates to .
The query isinvalid ifis not the name of a selector in the query.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Evaluates to the length (or lengths,if multi-valued) of a property. In evaluating this operand, arepositoryshould use the semantics defined in §3.6.7Lengthof a Value.
If evaluates to ,the operand also evaluates to .
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Evaluates to a value equal to theJCR name of a node.
The query isinvalid ifis not the name of a selector in the query.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Evaluates to a value equal to theJCR local name of a node.
The query isinvalid ifis not the name of a selector in the query.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Evaluates to a value equal to the full-text search score of a node.
Full-text search score ranks aselector's nodes by their relevance to the specified in a .The values to which evaluates and the interpretation of those values are implementationspecific. may evaluate to a constant value in a repository that does notsupport full-text search scoring or has no full-text indexedproperties.
The query isinvalid ifis not the name of a selector in the query.
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Evaluates to the lower-case stringvalue (or values, if multi-valued) of .
If does not evaluate to a string value, its value is first converted toa string as described in §3.6.4Property Type Conversion.The lower-case string value is computed as though the method of were called.
If evaluates to ,the operand also evaluates to .
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
Evaluates to the upper-case stringvalue (or values, if multi-valued) of .
If does not evaluate to a string value, its value is first converted toa string as described in §3.6.4Property Type Conversion.The upper-case string value is computed as though the method of were called.
If evaluates to ,the operand also evaluates to .
JCR-SQL2
JCR-JQOM
Anis created with:
extendsand declares:
AQM
A JCR value.
JCR-SQL2
Anmay be interpreted as aof property typeor some other type inferred from static analysis. A,on the other hand, is interpreted as the string form of aof theindicated.
JCR-JQOM
A JCR.Aobject can be created using(see §6.10Literal Values). Note that unlike in the case ofJCR-SQL2, property type information is intrinsic to theobject, so no equivalent of thefunction is needed in JCR-JQOM.
AQM
Evaluates to the value of a bindvariable.
The query isinvalid if novalue is bound to .
JCR-SQL2
JCR-JQOM
Ais created with:
extendsand declares:
AQM
A JCR prefix.
The query isinvalid if theprefix does not satisfy the production in §3.2.5.2Qualified Form.
JCR-SQL2
JCR-JQOM
A string that conformsto the JCR Name prefix syntax. This is not required to be an actualprefix in use in the repository. The prefix syntax is used simply tocharacterize the range of possible variables.
AQM
Determines the relative order of twonode-tuples by evaluating for each.
For a first node-tuple, ,for which evaluates to ,and a second node-tuple, ,for which evaluates to :
If operand is a(see §6.7.27PropertyValue) of a propertyand thequery-orderable attribute of the property definitionofis(see §3.7.3.5Query-Orderable) then the relative order ofand is implementation determined, otherwise, if thequery-orderableattribute is,then:
If is ,then:
if either is ,is ,or both and are ,the relative order of and is implementation determined, otherwise
if is a different property type than ,the relative order of and is implementation determined, otherwise
ifis orderedbefore ,as described in §3.6.5 Comparison of Values, then precedes ,otherwise
ifis orderedafter ,as described in §3.6.5 Comparison of Values, then precedes ,otherwise
the relative order of and is implementation determined and may be arbitrary.
Otherwise, ifis ,then:
if either is ,is ,or both and are ,the relative order of and is implementation determined, otherwise
if is a different property type than ,the relative order of and is implementation determined, otherwise
ifis orderedbefore ,as described in §3.6.5 Comparison of Values, then precedes ,otherwise
ifis orderedafter ,as described in §3.6.5 Comparison of Values, then precedes ,otherwise
the relative order of and is implementation determined and may be arbitrary.
The query isinvalid if does not evaluate to a scalar value.
JCR-SQL2
Ifis omitted in the JCR-SQL2 statement the default is(see §6.7.38Order).
JCR-JQOM
An ascendingis created with:
A descendingis created with:
declares:
AQM
is eitheror.
JCR-SQL2
JCR-JQOM
An order is aconstant. One of:
AQM
Defines a column to include in thetabular view of query results.
If is not specified, a column is included for each single-valuednon-residual property of the node type specified by the attribute of the selector .
If is specified, is required and used to name the column in the tabular results. Ifis not specified, must not be specified, and the included columns will be named“”.
The query isinvalid if:
is not the name of a selector in the query, or
is specified but does not evaluate to a scalar value, or
is specified but is omitted, or
is omitted but is specified, or
the columns in the tabular vieware not uniquely named, whether those column names are specified by(if is specified) or generated as described above (if is omitted).
If is specified but, for a node-tuple, the node does not have a property named ,the query isvalid and the column has value.
JCR-SQL2
JCR-JQOM
Ais created with:
declares:
The query function isaccessed through theobject, acquired through
.
returns an array ofstrings representing the supported query languages. In allrepositories that support query, the array will contain at least thestring constants
and
.
Any additionallanguages also supported will also be listed in the returned array.
A newobject can be created with
.
Theparameter is a string representing one of the supported languages.Theparameter is the query statement itself. This method is used forlanguages that are string-based (i.e., most languages, such asJCR-SQL2) as well as for the string serializations ofnon-string-based languages (such as JCR-JQOM). For example, the call
,
whereis theandis a JCR-SQL2 statement, returns aobject encapsulating.
However, the call
also works. It returnsa(a subclass of)holding the JCR-JQOM object tree equivalent to.
In either case thereturnedobject encapsulates the resulting query. In some repositories thefirst method call (with JCR-SQL2 specified) may also result in a,though this is not required.
Toprogrammatically build a query tree using JCR-JQOM the user acquiresausing
.
The user then buildsthe query tree using the factory methods of,ultimately resulting in aobject (a subclass ofrepresenting the query.
The JCR-SQL2 language,in addition to being a query language in its own right is also thestandard serialization of a valid JCR-JQOM object tree. Since thetwo languages are formally equivalent they can always beroundtripped.
returns the statementset for the query. If thewas created with an explicitly suppliedstring parameter usingthen this method returns that statement. The statement returned mustbe semantically identical to the original statement but need not bean identical string (for example, it may be normalized).
If theis actually acreated withthenmust return the serialized form of the query, in JCR-SQL2 syntax.
returns the languagein which the query is specified. If thewas created with an explicitly suppliedstring parameter usingthen this method returns that string.
If theis actually acreated withthenwill return the string constant.
Sets the maximum sizeof the result set, expressed in terms of the number ofs,as found in the table-view of the(see §6.11QueryResult).
Sets the offset withinthe full result set at which the returned result set should start,expressed in terms of the number ofsto skip, as found in the table-view of the(see §6.11QueryResult).
A querymay contain variables.
bindsto the variable.
InJCR-SQL2 a bind variable is indicated by a leading dollar-sign. InJCR-JQOM it is a QOM object created with the(see §6.7.35BindVariable).
Themethod
returns the names ofthe bind variables in the query. If the query does not contains anybind variables then an empty array is returned.
When a newobject is first created it is atransient query. If therepository supports the node type,then a transient query can be stored in content by calling
.
This creates annode at the specified path. Ais required to persist the node.
Thenode type is defined as follows:
holds the string returned by.
holds the string returned by.
If the language ofthis query is JCR-JQOM,will hold the JCR-SQL2 serialization of the JCR-JQOM object tree andwill return that string. Also, since the original query wasconstructed using JCR-JQOM,records the language as “”andreturns “”.
returns the absolutepath of athat has been stored as a node.
retrieves a previouslypersisted query and instantiates it as aobject.
Note that the querystatement stored within a stored query (the value of the property)is stored as a simple string. Therefore, if it contains qualifiedJCR names it will benamespace-fragile. If the stored queryis run in a context where a prefix used maps to a differentnamespace than it did upon creation then the query will notreproduce the original result. To mitigate this, users shouldeither,
always useexpanded form names within queries, or
always ensurethat appropriate namespace mappings are in place when a storedquery is executed.
Whencreating aobject (see 6.7.16Comparison)a user may wish to pass a literal property value (see 6.7.34Literal)in the form of aobject.objects are created using theacquired through
.
(see§10.4.3Creating Value Objects).
Once a query has beendefined, it can be executed. The method
returns the aobject. Theis returned in two formats: as a table and as a list of nodes.
The table view of aresult is accessed with
The returnedholds a series ofobjects. Aobject represents a single row of the query result table whichcorresponds to a node-tuple returned by the query.
Upon retrieving anindividual,the set ofsmaking up that row can be retrieved with
The values arereturned in that same order as their corresponding column names arereturned by.
returns theof the indicated column of the.The names of the columns can be retrieved with
.
In queries with onlyone selector included among the specified columns, eachcorresponds to a single.In such cases
returns that.
In queries with morethan one selector included among the specified columns, a particularselector must be indicated in order to retrieve its corresponding. This is done using
.
The available selectornames can be retrieved with
.
If theis from a result involving outer joins, it may have nocorresponding to the specified selector, in which case this methodreturns.
The methods
are equivalent toand
, respectively.However, some implementations may be able gain efficiency by notresolving the actual.
The method
returns the full textsearch score for this row that is associated with the specifiedselector. This is equivalent to the score of theassociated with that thisand that selector.
If noAQM object (see §6.7.31FullTextSearchScore) is associatedwith the specified selector this method will still return a valuebut that value may not be meaningful or may simply reflect theminimum possible relevance level (for example, in some systems thismight be a score of 0).
If thisis from a result involving outer joins, it may have nocorresponding to the specified selector, in which case this methodreturns an implementation selected value, as it would if there werenoassociated with the selector.
The method
works identically to, but only in cases wherethere is exactly one selector and therefore its name need not beexplicitly specified.
Forqueries with only one selector
returnsan iterator over all matching nodes in the order specified by thequery. For queries with more than one selector the order in whichnodes are returned is implementation-specific.
Eachis bound to aobject via thethrough which it was created and theobject through which thatwas acquired. Through its associatedandobjects a query is therefore bound to a single persistent workspaceand a single transient store.
A query result alwaysrespects the access restrictions of its bound.This includes all restrictions, as reflected in thecapabilitiesof the,which encompassesprivileges,permissions andotherrestrictions (see §9Permissions and Capabilities).
In general, if thebounddoes not have read access to a particular item, then that item willnot be included in the result set even if it would otherwiseconstitute a match.
A query runs againsteither
the content ofits bound persistent workspace,without regard to any pendingchanges in its bound transient store, or
the content ofits bound persistent workspaceas modified by the pendingchanges in its bound transient store.
The choice of whichscope to use is an implementation-variant.
Regardless of whichscope is used, when an item is accessed from within aobject, the state of the item returned will obey the same semanticsas if it were retrieved using a normalor:the item state will reflect any pending changes in transient storeof the.As a result, it is possible that an item returned as a match willnot reflect the state that caused it tobe a match (i.e., itspersistent state). Applications can clear the(either throughor)before running a query in order to avoid such discrepancies.