01: package org.odmg;
02:
03: /**
04: * The base interface for all ODMG collections.
05: * The ODMG collections are based on JavaSoft’s collection interfaces.
06: * All of the operations defined by the JavaSoft <code>Collection</code>
07: * interface are supported by an ODMG implementation of <code>DCollection</code>;
08: * the exception <code>UnsupportedOperationException</code> is not thrown when a
09: * 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: public interface DCollection extends java.util.Collection {
20: /**
21: * Selects the single element of the collection for which the provided OQL query
22: * predicate is true.
23: * @param predicate An OQL boolean query predicate.
24: * @return The element that evaluates to true for the predicate. If no element
25: * evaluates to true, null is returned.
26: * @exception QueryInvalidException The query predicate is invalid.
27: */
28: public Object selectElement(String predicate)
29: throws QueryInvalidException;
30:
31: /**
32: * Access all of the elements of the collection that evaluate to true for the
33: * provided query predicate.
34: * @param predicate An OQL boolean query predicate.
35: * @return An iterator used to iterate over the elements that evaluated true for the predicate.
36: * @exception QueryInvalidException The query predicate is invalid.
37: */
38: public java.util.Iterator select(String predicate)
39: 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)
49: throws QueryInvalidException;
50:
51: /**
52: * Determines whether there is an element of the collection that evaluates to true
53: * for the predicate.
54: * @param predicate An OQL boolean query predicate.
55: * @return True if there is an element of the collection that evaluates to true
56: * for the predicate, otherwise false.
57: * @exception QueryInvalidException The query predicate is invalid.
58: */
59: public boolean existsElement(String predicate)
60: throws QueryInvalidException;
61: }
|