001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.query.qom;
005:
006: /**
007: * Filters node-tuples based on the outcome of a binary operation.
008: * <p/>
009: * For any comparison, {@link #getOperand2 operand2} always evaluates to a
010: * scalar value. In contrast, {@link #getOperand1 operand1} may evaluate to
011: * an array of values (for example, the value of a multi-valued property),
012: * in which case the comparison is separately performed for each element of
013: * the array, and the <code>Comparison</code> constraint is satisfied as a
014: * whole if the comparison against <i>any</i> element of the array is satisfied.
015: * <p/>
016: * If {@link #getOperand1 operand1} and {@link #getOperand2 operand2}
017: * evaluate to values of different property types, the value of
018: * {@link #getOperand2 operand2} is converted to the property type of
019: * the value of {@link #getOperand1 operand1}. If the type conversion
020: * fails, the query is invalid.
021: * <p/>
022: * Certain operators may only be applied to values of certain property types.
023: * The following describes required operator support for each property type:
024: * <ul>
025: * <li><code>STRING</code><ul>
026: * <li><code>EqualTo</code>, <code>NotEqualTo</code>, <code>LessThan</code>,
027: * <code>LessThanOrEqualTo</code>, <code>GreaterThan</code>,
028: * <code>GreaterThanOrEqualTo</code>, <code>Like</code></li></ul></li>
029: * <li><code>BINARY</code><ul>
030: * <li>None</li></ul></li>
031: * <li><code>DATE</code>, <code>LONG</code>, <code>DOUBLE</code>,
032: * <code>DECIMAL</code><ul>
033: * <li><code>EqualTo</code>, <code>NotEqualTo</code>, <code>LessThan</code>,
034: * <code>LessThanOrEqualTo</code>, <code>GreaterThan</code>,
035: * <code>GreaterThanOrEqualTo</code></li></ul></li>
036: * <li><code>BOOLEAN</code>, <code>NAME</code>, <code>PATH</code>,
037: * <code>REFERENCE</code>, <code>WEAKREFERENCE</code>, <code>URI</code><ul>
038: * <li><code>EqualTo</code>, <code>NotEqualTo</code></li></ul></li>
039: * </ul>
040: * <p/>
041: * If {@link #getOperator operator} is not supported for the property type of
042: * {@link #getOperand1 operand1}, the query is invalid.
043: * <p/>
044: * If {@link #getOperand1 operand1} evaluates to null (for example, if the
045: * operand evaluates the value of a property which does not exist), the
046: * constraint is not satisfied.
047: * <p/>
048: * The <code>EqualTo</code> operator is satisfied <i>only if</i> the value of
049: * {@link #getOperand1 operand1} equals the value of
050: * {@link #getOperand2 operand2}.
051: * <p/>
052: * The <code>NotEqualTo</code> operator is satisfied <i>unless</i> the value of
053: * {@link #getOperand1 operand1} equals the value of
054: * {@link #getOperand2 operand2}.
055: * <p/>
056: * The <code>LessThan</code> operator is satisfied <i>only if</i> the value of
057: * {@link #getOperand1 operand1} is ordered <i>before</i> the value of
058: * {@link #getOperand2 operand2}.
059: * <p/>
060: * The <code>LessThanOrEqualTo</code> operator is satisfied <i>unless</i> the
061: * value of {@link #getOperand1 operand1} is ordered <i>after</i> the value of
062: * {@link #getOperand2 operand2}.
063: * <p/>
064: * The <code>GreaterThan</code> operator is satisfied <i>only if</i> the value
065: * of {@link #getOperand1 operand1} is ordered <i>after</i> the value of
066: * {@link #getOperand2 operand2}.
067: * <p/>
068: * The <code>GreaterThanOrEqualTo</code> operator is satisfied <i>unless</i> the
069: * value of {@link #getOperand1 operand1} is ordered <i>before</i> the value of
070: * {@link #getOperand2 operand2}.
071: * <p/>
072: * The <code>Like</code> operator is satisfied only if the value of
073: * {@link #getOperand1 operand1} <i>matches</i> the pattern specified by the
074: * value of {@link #getOperand2 operand2}, where in the pattern:
075: * <ul>
076: * <li>the character "<code>%</code>" matches zero or more characters, and</li>
077: * <li>the character "<code>_</code>" (underscore) matches exactly one
078: * character, and</li>
079: * <li>the string "<code>\<i>x</i></code>" matches the character
080: * "<code><i>x</i></code>", and</li>
081: * <li>all other characters match themselves.</li>
082: * </ul>
083: *
084: * @since JCR 2.0
085: */
086: public interface Comparison extends Constraint {
087: /**
088: * Gets the first operand.
089: *
090: * @return the operand; non-null
091: */
092: public DynamicOperand getOperand1();
093:
094: /**
095: * Gets the operator.
096: *
097: * @return either
098: * <ul>
099: * <li>{@link QueryObjectModelConstants#OPERATOR_EQUAL_TO},</li>
100: * <li>{@link QueryObjectModelConstants#OPERATOR_NOT_EQUAL_TO},</li>
101: * <li>{@link QueryObjectModelConstants#OPERATOR_LESS_THAN},</li>
102: * <li>{@link QueryObjectModelConstants#OPERATOR_LESS_THAN_OR_EQUAL_TO},</li>
103: * <li>{@link QueryObjectModelConstants#OPERATOR_GREATER_THAN},</li>
104: * <li>{@link QueryObjectModelConstants#OPERATOR_GREATER_THAN_OR_EQUAL_TO}, or</li>
105: * <li>{@link QueryObjectModelConstants#OPERATOR_LIKE}</li>
106: * </ul>
107: */
108: public int getOperator();
109:
110: /**
111: * Gets the second operand.
112: *
113: * @return the operand; non-null
114: */
115: public StaticOperand getOperand2();
116: }
117:
118: // EOF
|