001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.query.qom;
005:
006: /**
007: * Performs a full-text search.
008: * <p/>
009: * The full-text search expression is evaluated against the set of full-text
010: * indexed properties within the full-text search scope. If
011: * {@link #getPropertyName property} is specified, the full-text search scope
012: * is the property of that name on the {@link #getSelectorName selector} node
013: * in the node-tuple; otherwise the full-text search scope is all properties
014: * of the {@link #getSelectorName selector} node (or, in some implementations,
015: * all properties in the node subtree).
016: * <p/>
017: * Which properties (if any) in a repository are full-text indexed is
018: * implementation determined.
019: * <p/>
020: * It is also implementation determined whether
021: * {@link #getFullTextSearchExpression fullTextSearchExpression} is
022: * independently evaluated against each full-text indexed property in the
023: * full-text search scope, or collectively evaluated against the set of such
024: * properties using some implementation-determined mechanism.
025: * <p/>
026: * Similarly, for multi-valued properties, it is implementation determined
027: * whether {@link #getFullTextSearchExpression fullTextSearchExpression} is
028: * independently evaluated against each element in the array of values, or
029: * collectively evaluated against the array of values using some
030: * implementation-determined mechanism.
031: * <p/>
032: * At minimum, an implementation must support the following
033: * {@link #getFullTextSearchExpression fullTextSearchExpression} grammar:
034: * <pre> fullTextSearchExpression ::= [-]term {whitespace [OR] whitespace [-]term}
035: * <p/>
036: * term ::= word | '"' word {whitespace word} '"'
037: * <p/>
038: * word ::= (A string containing no whitespace)
039: * <p/>
040: * whitespace ::= (A string of only whitespace)
041: * </pre>
042: * <p/>
043: * A query satisfies a <code>FullTextSearch</code> constraint if the
044: * value (or values) of the full-text indexed properties within the
045: * full-text search scope satisfy the specified
046: * {@link #getFullTextSearchExpression fullTextSearchExpression},
047: * evaluated as follows:
048: * <ul>
049: * <li>A term not preceded with "<code>-</code>" (minus sign) is satisfied
050: * only if the value contains that term.</li>
051: * <li>A term preceded with "<code>-</code>" (minus sign) is satisfied only
052: * if the value does not contain that term.</li>
053: * <li>Terms separated by whitespace are implicitly "ANDed".</li>
054: * <li>Terms separated by "<code>OR</code>" are "ORed".</li>
055: * <li>"AND" has higher precedence than "OR".
056: * <li>Within a term, each double quote (<code>"</code>), "<code>-</code>"
057: * (minus sign), and "<code>\</code>" (backslash) must be escaped by a
058: * preceding "<code>\</code>" (backslash).</li>
059: * </ul>
060: * <p/>
061: * The query is invalid if:
062: * <ul>
063: * <li>{@link #getSelectorName selector} is not the name of a selector in the
064: * query, or</li>
065: * <li>{@link #getPropertyName property} is specified but is not a syntactically
066: * valid JCR name, or</li>
067: * <li>{@link #getFullTextSearchExpression fullTextSearchExpression} does not
068: * conform to the above grammar (as augmented by the implementation).</li>
069: * </ul>
070: * <p/>
071: * If {@link #getPropertyName property} is specified but, for a node-tuple,
072: * the selector node does not have a property named {@link #getPropertyName
073: * property}, the query is valid but the constraint is not satisfied.</li>
074: *
075: * @since JCR 2.0
076: */
077: public interface FullTextSearch extends Constraint {
078: /**
079: * Gets the name of the selector against which to apply this constraint.
080: *
081: * @return the selector name; non-null
082: */
083: public String getSelectorName();
084:
085: /**
086: * Gets the name of the property.
087: *
088: * @return the property name if the full-text search scope
089: * is a property, otherwise null if the full-text
090: * search scope is the node (or node subtree, in
091: * some implementations).
092: */
093: public String getPropertyName();
094:
095: /**
096: * Gets the full-text search expression.
097: *
098: * @return the full-text search expression; non-null
099: */
100: public String getFullTextSearchExpression();
101: }
102:
103: // EOF
|