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