Source code: org/odmg/DCollection.java
1 package org.odmg;
2
3 /**
4 * The base interface for all ODMG collections.
5 * The ODMG collections are based on JavaSoft’s collection interfaces.
6 * All of the operations defined by the JavaSoft <code>Collection</code>
7 * interface are supported by an ODMG implementation of <code>DCollection</code>;
8 * the exception <code>UnsupportedOperationException</code> is not thrown when a
9 * call is made to any of the <code>Collection</code> methods.
10 * <p>
11 * <code>DCollection</code> contains methods used to perform queries on the collection.
12 * The OQL query predicate is given as a string with the syntax of the
13 * <code>where</code> clause of OQL. The predefined OQL variable <code>this</code>
14 * is used inside the predicate to denote the current element of the collection.
15 * @author David Jordan (as Java Editor of the Object Data Management Group)
16 * @version ODMG 3.0
17 */
18 // * @see com.sun.java.util.collections.UnsupportedOperationException
19
20 public interface DCollection extends java.util.Collection
21 {
22 /**
23 * Selects the single element of the collection for which the provided OQL query
24 * predicate is true.
25 * @param predicate An OQL boolean query predicate.
26 * @return The element that evaluates to true for the predicate. If no element
27 * evaluates to true, null is returned.
28 * @exception QueryInvalidException The query predicate is invalid.
29 */
30 public Object selectElement(String predicate) throws QueryInvalidException;
31
32 /**
33 * Access all of the elements of the collection that evaluate to true for the
34 * provided query predicate.
35 * @param predicate An OQL boolean query predicate.
36 * @return An iterator used to iterate over the elements that evaluated true for the predicate.
37 * @exception QueryInvalidException The query predicate is invalid.
38 */
39 public java.util.Iterator select(String predicate) throws QueryInvalidException;
40
41 /**
42 * Evaluate the boolean query predicate for each element of the collection and
43 * return a new collection that contains each element that evaluated to true.
44 * @param predicate An OQL boolean query predicate.
45 * @return A new collection containing the elements that evaluated true for the predicate.
46 * @exception QueryInvalidException The query predicate is invalid.
47 */
48 public DCollection query(String predicate) throws QueryInvalidException;
49
50 /**
51 * Determines whether there is an element of the collection that evaluates to true
52 * for the predicate.
53 * @param predicate An OQL boolean query predicate.
54 * @return True if there is an element of the collection that evaluates to true
55 * for the predicate, otherwise false.
56 * @exception QueryInvalidException The query predicate is invalid.
57 */
58 public boolean existsElement(String predicate) throws QueryInvalidException;
59 }