1 package org.odmg;
2
3
4
5
6
7 /**
8
9 * The base interface for all ODMG collections.
10
11 * The ODMG collections are based on JavaSoft�s collection interfaces.
12
13 * All of the operations defined by the JavaSoft <code>Collection</code>
14
15 * interface are supported by an ODMG implementation of <code>DCollection</code>;
16
17 * the exception <code>UnsupportedOperationException</code> is not thrown when a
18
19 * call is made to any of the <code>Collection</code> methods.
20
21 * <p>
22
23 * <code>DCollection</code> contains methods used to perform queries on the collection.
24
25 * The OQL query predicate is given as a string with the syntax of the
26
27 * <code>where</code> clause of OQL. The predefined OQL variable <code>this</code>
28
29 * is used inside the predicate to denote the current element of the collection.
30
31 * @author David Jordan (as Java Editor of the Object Data Management Group)
32
33 * @version ODMG 3.0
34
35 */
36
37 // * @see com.sun.java.util.collections.UnsupportedOperationException
38
39
40
41 public interface DCollection extends java.util.Collection
42
43 {
44
45 /**
46
47 * Selects the single element of the collection for which the provided OQL query
48
49 * predicate is true.
50
51 * @param predicate An OQL boolean query predicate.
52
53 * @return The element that evaluates to true for the predicate. If no element
54
55 * evaluates to true, null is returned.
56
57 * @exception QueryInvalidException The query predicate is invalid.
58
59 */
60
61 public Object selectElement(String predicate) throws QueryInvalidException;
62
63
64
65 /**
66
67 * Access all of the elements of the collection that evaluate to true for the
68
69 * provided query predicate.
70
71 * @param predicate An OQL boolean query predicate.
72
73 * @return An iterator used to iterate over the elements that evaluated true for the predicate.
74
75 * @exception QueryInvalidException The query predicate is invalid.
76
77 */
78
79 public java.util.Iterator select(String predicate) throws QueryInvalidException;
80
81
82
83 /**
84
85 * Evaluate the boolean query predicate for each element of the collection and
86
87 * return a new collection that contains each element that evaluated to true.
88
89 * @param predicate An OQL boolean query predicate.
90
91 * @return A new collection containing the elements that evaluated true for the predicate.
92
93 * @exception QueryInvalidException The query predicate is invalid.
94
95 */
96
97 public DCollection query(String predicate) throws QueryInvalidException;
98
99
100
101 /**
102
103 * Determines whether there is an element of the collection that evaluates to true
104
105 * for the predicate.
106
107 * @param predicate An OQL boolean query predicate.
108
109 * @return True if there is an element of the collection that evaluates to true
110
111 * for the predicate, otherwise false.
112
113 * @exception QueryInvalidException The query predicate is invalid.
114
115 */
116
117 public boolean existsElement(String predicate) throws QueryInvalidException;
118
119 }
120