001    package org.odmg;
002    
003    
004    
005    /**
006    
007     * The interface to an OQL query object.
008    
009     * @author      David Jordan (as Java Editor of the Object Data Management Group)
010    
011     * @version ODMG 3.0
012    
013     */
014    
015    
016    
017    public interface OQLQuery
018    
019    {
020    
021    
022    
023        /**
024    
025         * Create an OQL query from the string parameter.
026    
027         * In order to execute a query, an <code>OQLQuery</code> object must be created
028    
029         * by calling <code>Implementation.newOQLQuery</code>, then calling the
030    
031         * <code>create</code> method with the query string.
032    
033         * The <code>create</code> method might throw <code>QueryInvalidException</code>
034    
035         * if the query could not be compiled properly. Some implementations may not want
036    
037         * to compile the query before <code>execute</code> is called. In this case
038    
039         * <code>QueryInvalidException</code> is thrown when <code>execute</code> is called.
040    
041         * @param   query   An OQL query.
042    
043         * @exception       QueryInvalidException   The query syntax is invalid.
044    
045         */
046    
047        public void create(String query) throws QueryInvalidException;
048    
049    
050    
051        /**
052    
053         * Bind a parameter to the query.
054    
055         * A parameter is denoted in the query string passed to <code>create</code> by <i>$i</i>,
056    
057         * where <i>i</i> is the rank of the parameter, beginning with 1.
058    
059         * The parameters are set consecutively by calling this method <code>bind</code>.
060    
061         * The <i>ith</i> variable is set by the <i>ith</i> call to the <code>bind</code> method.
062    
063         * If any of the <i>$i</i> are not set by a call to <code>bind</code> at the point
064    
065         * <code>execute</code> is called, <code>QueryParameterCountInvalidException</code> is thrown.
066    
067         * The parameters must be objects, and the result is an <code>Object</code>.
068    
069         * Objects must be used instead of primitive types (<code>Integer</code> instead
070    
071         * of <code>int</code>) for passing the parameters.
072    
073         * <p>
074    
075         * If the parameter is of the wrong type,
076    
077         * <code>QueryParameterTypeInvalidException</code> is thrown.
078    
079         * After executing a query, the parameter list is reset.
080    
081         * @parameter       A value to be substituted for a query parameter.
082    
083         * @exception QueryParameterCountInvalidException The number of calls to
084    
085         * <code>bind</code> has exceeded the number of parameters in the query.
086    
087         * @exception QueryParameterTypeInvalidException The type of the parameter does
088    
089         * not correspond with the type of the parameter in the query.
090    
091         */
092    
093        public void bind(Object parameter) throws QueryParameterCountInvalidException,
094    
095                QueryParameterTypeInvalidException;
096    
097    
098    
099        /**
100    
101         * Execute the query.
102    
103         * After executing a query, the parameter list is reset.
104    
105         * Some implementations may throw additional exceptions that are also derived
106    
107         * from <code>ODMGException</code>.
108    
109         * @return  The object that represents the result of the query.
110    
111         * The returned data, whatever its OQL type, is encapsulated into an object.
112    
113         * For instance, when OQL returns an integer, the result is put into an
114    
115         * <code>Integer</code> object. When OQL returns a collection (literal or object),
116    
117         * the result is always a Java collection object of the same kind
118    
119         * (for instance, a <code>DList</code>).
120    
121         * @exception       QueryException  An exception has occurred while executing the query.
122    
123         */
124    
125        public Object execute() throws QueryException;
126    
127    }
128