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