001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.query.qom;
005:
006: import javax.jcr.RepositoryException;
007: import javax.jcr.Value;
008: import javax.jcr.query.InvalidQueryException;
009:
010: /**
011: * A <code>QueryObjectModelFactory</code> creates instances of the JCR query
012: * object model.
013: * <p/>
014: * Refer to {@link QueryObjectModel} for a description of the query object
015: * model.
016: *
017: * @since JCR 2.0
018: */
019: public interface QueryObjectModelFactory extends
020: QueryObjectModelConstants {
021: ///
022: /// QUERY
023: ///
024:
025: /**
026: * Creates a query with one selector.
027: * <p/>
028: * The specified selector will be the <i>default selector</i> of the query.
029: *
030: * @param selector the selector; non-null
031: * @param constraint the constraint, or null if none
032: * @param orderings zero or more orderings; null is equivalent to a
033: * zero-length array
034: * @param columns the columns; null is equivalent to a zero-length
035: * array
036: * @return the query; non-null
037: * @throws InvalidQueryException if the query is invalid
038: * @throws RepositoryException if the operation otherwise fails
039: */
040: public QueryObjectModel createQuery // CM
041: (Selector selector, Constraint constraint, Ordering[] orderings,
042: Column[] columns) throws InvalidQueryException,
043: RepositoryException;
044:
045: /**
046: * Creates a query with one or more selectors.
047: * <p/>
048: * If <code>source</code> is a selector, that selector is the <i>default
049: * selector</i> of the query. Otherwise the query does not have a default
050: * selector.
051: *
052: * @param source the node-tuple source; non-null
053: * @param constraint the constraint, or null if none
054: * @param orderings zero or more orderings; null is equivalent to a
055: * zero-length array
056: * @param columns the columns; null is equivalent to a zero-length
057: * array
058: * @return the query; non-null
059: * @throws InvalidQueryException if the query is invalid
060: * @throws RepositoryException if the operation otherwise fails
061: */
062: public QueryObjectModel createQuery(Source source,
063: Constraint constraint, Ordering[] orderings,
064: Column[] columns) throws InvalidQueryException,
065: RepositoryException;
066:
067: ///
068: /// SELECTOR
069: ///
070:
071: /**
072: * Selects a subset of the nodes in the repository based on node type.
073: * <p/>
074: * The selector name is the node type name.
075: *
076: * @param nodeTypeName the name of the required node type; non-null
077: * @return the selector; non-null
078: * @throws InvalidQueryException if the query is invalid
079: * @throws RepositoryException if the operation otherwise fails
080: */
081: public Selector selector(String nodeTypeName) // CM
082: throws InvalidQueryException, RepositoryException;
083:
084: /**
085: * Selects a subset of the nodes in the repository based on node type.
086: *
087: * @param nodeTypeName the name of the required node type; non-null
088: * @param selectorName the selector name; non-null
089: * @return the selector; non-null
090: * @throws InvalidQueryException if the query is invalid
091: * @throws RepositoryException if the operation otherwise fails
092: */
093: public Selector selector(String nodeTypeName, String selectorName)
094: throws InvalidQueryException, RepositoryException;
095:
096: ///
097: /// JOIN
098: ///
099:
100: /**
101: * Performs a join between two node-tuple sources.
102: *
103: * @param left the left node-tuple source; non-null
104: * @param right the right node-tuple source; non-null
105: * @param joinType either
106: * <ul>
107: * <li>{@link QueryObjectModelConstants#JOIN_TYPE_INNER},</li>
108: * <li>{@link QueryObjectModelConstants#JOIN_TYPE_LEFT_OUTER},</li>
109: * <li>{@link QueryObjectModelConstants#JOIN_TYPE_RIGHT_OUTER}</li>
110: * </ul>
111: * @param joinCondition the join condition; non-null
112: * @return the join; non-null
113: * @throws InvalidQueryException if the query is invalid
114: * @throws RepositoryException if the operation otherwise fails
115: */
116: public Join join(Source left, Source right, int joinType,
117: JoinCondition joinCondition) throws InvalidQueryException,
118: RepositoryException;
119:
120: ///
121: /// JOINCONDITION
122: ///
123:
124: /**
125: * Tests whether the value of a property in a first selector is equal to the
126: * value of a property in a second selector.
127: *
128: * @param selector1Name the name of the first selector; non-null
129: * @param property1Name the property name in the first selector; non-null
130: * @param selector2Name the name of the second selector; non-null
131: * @param property2Name the property name in the second selector; non-null
132: * @return the constraint; non-null
133: * @throws InvalidQueryException if the query is invalid
134: * @throws RepositoryException if the operation otherwise fails
135: */
136: public EquiJoinCondition equiJoinCondition(String selector1Name,
137: String property1Name, String selector2Name,
138: String property2Name) throws InvalidQueryException,
139: RepositoryException;
140:
141: /**
142: * Tests whether a first selector's node is the same as a second selector's
143: * node.
144: *
145: * @param selector1Name the name of the first selector; non-null
146: * @param selector2Name the name of the second selector; non-null
147: * @return the constraint; non-null
148: * @throws InvalidQueryException if the query is invalid
149: * @throws RepositoryException if the operation otherwise fails
150: */
151: public SameNodeJoinCondition sameNodeJoinCondition(
152: String selector1Name, String selector2Name)
153: throws InvalidQueryException, RepositoryException; // CM
154:
155: /**
156: * Tests whether a first selector's node is the same as a node identified
157: * by relative path from a second selector's node.
158: *
159: * @param selector1Name the name of the first selector; non-null
160: * @param selector2Name the name of the second selector; non-null
161: * @param selector2Path the path relative to the second selector; non-null
162: * @return the constraint; non-null
163: * @throws InvalidQueryException if the query is invalid
164: * @throws RepositoryException if the operation otherwise fails
165: */
166: public SameNodeJoinCondition sameNodeJoinCondition(
167: String selector1Name, String selector2Name,
168: String selector2Path) throws InvalidQueryException,
169: RepositoryException;
170:
171: /**
172: * Tests whether a first selector's node is a child of a second selector's
173: * node.
174: *
175: * @param childSelectorName the name of the child selector; non-null
176: * @param parentSelectorName the name of the parent selector; non-null
177: * @return the constraint; non-null
178: * @throws InvalidQueryException if the query is invalid
179: * @throws RepositoryException if the operation otherwise fails
180: */
181: public ChildNodeJoinCondition childNodeJoinCondition(
182: String childSelectorName, String parentSelectorName)
183: throws InvalidQueryException, RepositoryException;
184:
185: /**
186: * Tests whether a first selector's node is a descendant of a second
187: * selector's node.
188: *
189: * @param descendantSelectorName the name of the descendant selector; non-null
190: * @param ancestorSelectorName the name of the ancestor selector; non-null
191: * @return the constraint; non-null
192: * @throws InvalidQueryException if the query is invalid
193: * @throws RepositoryException if the operation otherwise fails
194: */
195: public DescendantNodeJoinCondition descendantNodeJoinCondition(
196: String descendantSelectorName, String ancestorSelectorName)
197: throws InvalidQueryException, RepositoryException;
198:
199: ///
200: /// CONSTRAINT
201: ///
202:
203: /**
204: * Performs a logical conjunction of two other constraints.
205: *
206: * @param constraint1 the first constraint; non-null
207: * @param constraint2 the second constraint; non-null
208: * @return the <code>And</code> constraint; non-null
209: * @throws InvalidQueryException if the query is invalid
210: * @throws RepositoryException if the operation otherwise fails
211: */
212: public And and(Constraint constraint1, Constraint constraint2)
213: throws InvalidQueryException, RepositoryException;
214:
215: /**
216: * Performs a logical disjunction of two other constraints.
217: *
218: * @param constraint1 the first constraint; non-null
219: * @param constraint2 the second constraint; non-null
220: * @return the <code>Or</code> constraint; non-null
221: * @throws InvalidQueryException if the query is invalid
222: * @throws RepositoryException if the operation otherwise fails
223: */
224: public Or or(Constraint constraint1, Constraint constraint2)
225: throws InvalidQueryException, RepositoryException;
226:
227: /**
228: * Performs a logical negation of another constraint.
229: *
230: * @param constraint the constraint to be negated; non-null
231: * @return the <code>Not</code> constraint; non-null
232: * @throws InvalidQueryException if the query is invalid
233: * @throws RepositoryException if the operation otherwise fails
234: */
235: public Not not(Constraint constraint) throws InvalidQueryException,
236: RepositoryException;
237:
238: /**
239: * Filters node-tuples based on the outcome of a binary operation.
240: *
241: * @param operand1 the first operand; non-null
242: * @param operator the operator; either
243: * <ul>
244: * <li>{@link #OPERATOR_EQUAL_TO},</li>
245: * <li>{@link #OPERATOR_NOT_EQUAL_TO},</li>
246: * <li>{@link #OPERATOR_LESS_THAN},</li>
247: * <li>{@link #OPERATOR_LESS_THAN_OR_EQUAL_TO},</li>
248: * <li>{@link #OPERATOR_GREATER_THAN},</li>
249: * <li>{@link #OPERATOR_GREATER_THAN_OR_EQUAL_TO}, or</li>
250: * <li>{@link #OPERATOR_LIKE}</li>
251: * </ul>
252: * @param operand2 the second operand; non-null
253: * @return the constraint; non-null
254: * @throws InvalidQueryException if the query is invalid
255: * @throws RepositoryException if the operation otherwise fails
256: */
257: public Comparison comparison(DynamicOperand operand1, int operator,
258: StaticOperand operand2) throws InvalidQueryException,
259: RepositoryException;
260:
261: /**
262: * Tests the existence of a property in the default selector.
263: *
264: * @param propertyName the property name; non-null
265: * @return the constraint; non-null
266: * @throws InvalidQueryException if the query has no default selector
267: * or is otherwise invalid
268: * @throws RepositoryException if the operation otherwise fails
269: */
270: public PropertyExistence propertyExistence(String propertyName) // CM
271: throws InvalidQueryException, RepositoryException;
272:
273: /**
274: * Tests the existence of a property in the specified selector.
275: *
276: * @param selectorName the selector name; non-null
277: * @param propertyName the property name; non-null
278: * @return the constraint; non-null
279: * @throws InvalidQueryException if the query is invalid
280: * @throws RepositoryException if the operation otherwise fails
281: */
282: public PropertyExistence propertyExistence(String selectorName,
283: String propertyName) throws InvalidQueryException,
284: RepositoryException;
285:
286: /**
287: * Performs a full-text search against the default selector.
288: *
289: * @param propertyName the property name, or null to search all
290: * full-text indexed properties of the node
291: * (or node subtree, in some implementations)
292: * @param fullTextSearchExpression the full-text search expression; non-null
293: * @return the constraint; non-null
294: * @throws InvalidQueryException if the query has no default selector
295: * or is otherwise invalid
296: * @throws RepositoryException if the operation otherwise fails
297: */
298: public FullTextSearch fullTextSearch(String propertyName,
299: String fullTextSearchExpression)
300: throws InvalidQueryException, RepositoryException; // CM
301:
302: /**
303: * Performs a full-text search against the specified selector.
304: *
305: * @param selectorName the selector name; non-null
306: * @param propertyName the property name, or null to search all
307: * full-text indexed properties of the node
308: * (or node subtree, in some implementations)
309: * @param fullTextSearchExpression the full-text search expression; non-null
310: * @return the constraint; non-null
311: * @throws InvalidQueryException if the query is invalid
312: * @throws RepositoryException if the operation otherwise fails
313: */
314: public FullTextSearch fullTextSearch(String selectorName,
315: String propertyName, String fullTextSearchExpression)
316: throws InvalidQueryException, RepositoryException;
317:
318: /**
319: * Tests whether a node in the default selector is reachable by a specified
320: * absolute path.
321: *
322: * @param path an absolute path; non-null
323: * @return the constraint; non-null
324: * @throws InvalidQueryException if the query has no default selector
325: * or is otherwise invalid
326: * @throws RepositoryException if the operation otherwise fails
327: */
328: public SameNode sameNode(String path) throws InvalidQueryException,
329: RepositoryException; // CM
330:
331: /**
332: * Tests whether a node in the specified selector is reachable by a specified
333: * absolute path.
334: *
335: * @param selectorName the selector name; non-null
336: * @param path an absolute path; non-null
337: * @return the constraint; non-null
338: * @throws InvalidQueryException if the query is invalid
339: * @throws RepositoryException if the operation otherwise fails
340: */
341: public SameNode sameNode(String selectorName, String path)
342: throws InvalidQueryException, RepositoryException;
343:
344: /**
345: * Tests whether a node in the default selector is a child of a node
346: * reachable by a specified absolute path.
347: *
348: * @param path an absolute path; non-null
349: * @return the constraint; non-null
350: * @throws InvalidQueryException if the query has no default selector
351: * or is otherwise invalid
352: * @throws RepositoryException if the operation otherwise fails
353: */
354: public ChildNode childNode(String path)
355: throws InvalidQueryException, RepositoryException; // CM
356:
357: /**
358: * Tests whether a node in the specified selector is a child of a node
359: * reachable by a specified absolute path.
360: *
361: * @param selectorName the selector name; non-null
362: * @param path an absolute path; non-null
363: * @return the constraint; non-null
364: * @throws InvalidQueryException if the query is invalid
365: * @throws RepositoryException if the operation otherwise fails
366: */
367: public ChildNode childNode(String selectorName, String path)
368: throws InvalidQueryException, RepositoryException;
369:
370: /**
371: * Tests whether a node in the default selector is a descendant of a node
372: * reachable by a specified absolute path.
373: *
374: * @param path an absolute path; non-null
375: * @return the constraint; non-null
376: * @throws InvalidQueryException if the query has no default selector
377: * or is otherwise invalid
378: * @throws RepositoryException if the operation otherwise fails
379: */
380: public DescendantNode descendantNode(String path)
381: throws InvalidQueryException, RepositoryException; // CM
382:
383: /**
384: * Tests whether a node in the specified selector is a descendant of a node
385: * reachable by a specified absolute path.
386: *
387: * @param selectorName the selector name; non-null
388: * @param path an absolute path; non-null
389: * @return the constraint; non-null
390: * @throws InvalidQueryException if the query is invalid
391: * @throws RepositoryException if the operation otherwise fails
392: */
393: public DescendantNode descendantNode(String selectorName,
394: String path) throws InvalidQueryException,
395: RepositoryException;
396:
397: ///
398: /// OPERAND
399: ///
400:
401: /**
402: * Evaluates to the value (or values, if multi-valued) of a property of
403: * the default selector.
404: *
405: * @param propertyName the property name; non-null
406: * @return the operand; non-null
407: * @throws InvalidQueryException if the query has no default selector
408: * or is otherwise invalid
409: * @throws RepositoryException if the operation otherwise fails
410: */
411: public PropertyValue propertyValue(String propertyName) // CM
412: throws InvalidQueryException, RepositoryException;
413:
414: /**
415: * Evaluates to the value (or values, if multi-valued) of a property in the
416: * specified selector.
417: *
418: * @param selectorName the selector name; non-null
419: * @param propertyName the property name; non-null
420: * @return the operand; non-null
421: * @throws InvalidQueryException if the query is invalid
422: * @throws RepositoryException if the operation otherwise fails
423: */
424: public PropertyValue propertyValue(String selectorName,
425: String propertyName) throws InvalidQueryException,
426: RepositoryException;
427:
428: /**
429: * Evaluates to the length (or lengths, if multi-valued) of a property.
430: *
431: * @param propertyValue the property value for which to compute the length;
432: * non-null
433: * @return the operand; non-null
434: * @throws InvalidQueryException if the query is invalid
435: * @throws RepositoryException if the operation otherwise fails
436: */
437: public Length length(PropertyValue propertyValue)
438: throws InvalidQueryException, RepositoryException;
439:
440: /**
441: * Evaluates to a <code>NAME</code> value equal to the prefix-qualified name
442: * of a node in the default selector.
443: *
444: * @return the operand; non-null
445: * @throws InvalidQueryException if the query has no default selector
446: * or is otherwise invalid
447: * @throws RepositoryException if the operation otherwise fails
448: */
449: public NodeName nodeName() // CM
450: throws InvalidQueryException, RepositoryException;
451:
452: /**
453: * Evaluates to a <code>NAME</code> value equal to the prefix-qualified name
454: * of a node in the specified selector.
455: *
456: * @param selectorName the selector name; non-null
457: * @return the operand; non-null
458: * @throws InvalidQueryException if the query is invalid
459: * @throws RepositoryException if the operation otherwise fails
460: */
461: public NodeName nodeName(String selectorName)
462: throws InvalidQueryException, RepositoryException;
463:
464: /**
465: * Evaluates to a <code>NAME</code> value equal to the local (unprefixed)
466: * name of a node in the default selector.
467: *
468: * @return the operand; non-null
469: * @throws InvalidQueryException if the query has no default selector
470: * or is otherwise invalid
471: * @throws RepositoryException if the operation otherwise fails
472: */
473: public NodeLocalName nodeLocalName() // CM
474: throws InvalidQueryException, RepositoryException;
475:
476: /**
477: * Evaluates to a <code>NAME</code> value equal to the local (unprefixed)
478: * name of a node in the specified selector.
479: *
480: * @param selectorName the selector name; non-null
481: * @return the operand; non-null
482: * @throws InvalidQueryException if the query is invalid
483: * @throws RepositoryException if the operation otherwise fails
484: */
485: public NodeLocalName nodeLocalName(String selectorName)
486: throws InvalidQueryException, RepositoryException;
487:
488: /**
489: * Evaluates to a <code>DOUBLE</code> value equal to the full-text search
490: * score of a node in the default selector.
491: *
492: * @return the operand; non-null
493: * @throws InvalidQueryException if the query has no default selector
494: * or is otherwise invalid
495: * @throws RepositoryException if the operation otherwise fails
496: */
497: public FullTextSearchScore fullTextSearchScore() // CM
498: throws InvalidQueryException, RepositoryException;
499:
500: /**
501: * Evaluates to a <code>DOUBLE</code> value equal to the full-text search
502: * score of a node in the specified selector.
503: *
504: * @param selectorName the selector name; non-null
505: * @return the operand; non-null
506: * @throws InvalidQueryException if the query is invalid
507: * @throws RepositoryException if the operation otherwise fails
508: */
509: public FullTextSearchScore fullTextSearchScore(String selectorName)
510: throws InvalidQueryException, RepositoryException;
511:
512: /**
513: * Evaluates to the lower-case string value (or values, if multi-valued)
514: * of an operand.
515: *
516: * @param operand the operand whose value is converted to a
517: * lower-case string; non-null
518: * @return the operand; non-null
519: * @throws InvalidQueryException if the query is invalid
520: * @throws RepositoryException if the operation otherwise fails
521: */
522: public LowerCase lowerCase(DynamicOperand operand)
523: throws InvalidQueryException, RepositoryException;
524:
525: /**
526: * Evaluates to the upper-case string value (or values, if multi-valued)
527: * of an operand.
528: *
529: * @param operand the operand whose value is converted to a
530: * upper-case string; non-null
531: * @return the operand; non-null
532: * @throws InvalidQueryException if the query is invalid
533: * @throws RepositoryException if the operation otherwise fails
534: */
535: public UpperCase upperCase(DynamicOperand operand)
536: throws InvalidQueryException, RepositoryException;
537:
538: /**
539: * Evaluates to the value of a bind variable.
540: *
541: * @param bindVariableName the bind variable name; non-null
542: * @return the operand; non-null
543: * @throws InvalidQueryException if the query is invalid
544: * @throws RepositoryException if the operation otherwise fails
545: */
546: public BindVariableValue bindVariable(String bindVariableName)
547: throws InvalidQueryException, RepositoryException;
548:
549: ///
550: /// ORDERING
551: ///
552:
553: /**
554: * Orders by the value of the specified operand, in ascending order.
555: *
556: * @param operand the operand by which to order; non-null
557: * @return the ordering
558: * @throws InvalidQueryException if the query is invalid
559: * @throws RepositoryException if the operation otherwise fails
560: */
561: public Ordering ascending(DynamicOperand operand)
562: throws InvalidQueryException, RepositoryException;
563:
564: /**
565: * Orders by the value of the specified operand, in descending order.
566: *
567: * @param operand the operand by which to order; non-null
568: * @return the ordering
569: * @throws InvalidQueryException if the query is invalid
570: * @throws RepositoryException if the operation otherwise fails
571: */
572: public Ordering descending(DynamicOperand operand)
573: throws InvalidQueryException, RepositoryException;
574:
575: ///
576: /// COLUMN
577: ///
578:
579: /**
580: * Identifies a property in the default selector to include in the tabular
581: * view of query results.
582: * <p/>
583: * The column name is the property name.
584: *
585: * @param propertyName the property name, or null to include a column
586: * for each single-value non-residual property of
587: * the selector's node type
588: * @return the column; non-null
589: * @throws InvalidQueryException if the query has no default selector
590: * or is otherwise invalid
591: * @throws RepositoryException if the operation otherwise fails
592: */
593: public Column column(String propertyName) // CM
594: throws InvalidQueryException, RepositoryException;
595:
596: /**
597: * Identifies a property in the default selector to include in the tabular
598: * view of query results.
599: *
600: * @param propertyName the property name, or null to include a column
601: * for each single-value non-residual property of
602: * the selector's node type
603: * @param columnName the column name; must be null if
604: * <code>propertyName</code> is null
605: * @return the column; non-null
606: * @throws InvalidQueryException if the query has no default selector
607: * or is otherwise invalid
608: * @throws RepositoryException if the operation otherwise fails
609: */
610: public Column column(String propertyName, String columnName) // CM
611: throws InvalidQueryException, RepositoryException;
612:
613: /**
614: * Identifies a property in the specified selector to include in the tabular
615: * view of query results.
616: *
617: * @param selectorName the selector name; non-null
618: * @param propertyName the property name, or null to include a column
619: * for each single-value non-residual property of
620: * the selector's node type
621: * @param columnName the column name; if null, defaults to
622: * <code>propertyName</code>; must be null if
623: * <code>propertyName</code> is null
624: * @throws InvalidQueryException if the query is invalid
625: * @throws RepositoryException if the operation otherwise fails
626: */
627: public Column column(String selectorName, String propertyName,
628: String columnName) throws InvalidQueryException,
629: RepositoryException;
630: }
631:
632: // EOF
|