001: package org.odmg;
002:
003: /**
004:
005: * The base interface for all ODMG collections.
006:
007: * The ODMG collections are based on JavaSoft’s collection interfaces.
008:
009: * All of the operations defined by the JavaSoft <code>Collection</code>
010:
011: * interface are supported by an ODMG implementation of <code>DCollection</code>;
012:
013: * the exception <code>UnsupportedOperationException</code> is not thrown when a
014:
015: * call is made to any of the <code>Collection</code> methods.
016:
017: * <p>
018:
019: * <code>DCollection</code> contains methods used to perform queries on the collection.
020:
021: * The OQL query predicate is given as a string with the syntax of the
022:
023: * <code>where</code> clause of OQL. The predefined OQL variable <code>this</code>
024:
025: * is used inside the predicate to denote the current element of the collection.
026:
027: * @author David Jordan (as Java Editor of the Object Data Management Group)
028:
029: * @version ODMG 3.0
030:
031: */
032:
033: // * @see com.sun.java.util.collections.UnsupportedOperationException
034:
035: public interface DCollection extends java.util.Collection
036:
037: {
038:
039: /**
040:
041: * Selects the single element of the collection for which the provided OQL query
042:
043: * predicate is true.
044:
045: * @param predicate An OQL boolean query predicate.
046:
047: * @return The element that evaluates to true for the predicate. If no element
048:
049: * evaluates to true, null is returned.
050:
051: * @exception QueryInvalidException The query predicate is invalid.
052:
053: */
054:
055: public Object selectElement(String predicate)
056: throws QueryInvalidException;
057:
058: /**
059:
060: * Access all of the elements of the collection that evaluate to true for the
061:
062: * provided query predicate.
063:
064: * @param predicate An OQL boolean query predicate.
065:
066: * @return An iterator used to iterate over the elements that evaluated true for the predicate.
067:
068: * @exception QueryInvalidException The query predicate is invalid.
069:
070: */
071:
072: public java.util.Iterator select(String predicate)
073: throws QueryInvalidException;
074:
075: /**
076:
077: * Evaluate the boolean query predicate for each element of the collection and
078:
079: * return a new collection that contains each element that evaluated to true.
080:
081: * @param predicate An OQL boolean query predicate.
082:
083: * @return A new collection containing the elements that evaluated true for the predicate.
084:
085: * @exception QueryInvalidException The query predicate is invalid.
086:
087: */
088:
089: public DCollection query(String predicate)
090: throws QueryInvalidException;
091:
092: /**
093:
094: * Determines whether there is an element of the collection that evaluates to true
095:
096: * for the predicate.
097:
098: * @param predicate An OQL boolean query predicate.
099:
100: * @return True if there is an element of the collection that evaluates to true
101:
102: * for the predicate, otherwise false.
103:
104: * @exception QueryInvalidException The query predicate is invalid.
105:
106: */
107:
108: public boolean existsElement(String predicate)
109: throws QueryInvalidException;
110:
111: }
|