OQLQuery
object must be created
* by calling Implementation.newOQLQuery
, then calling the
* create
method with the query string.
* The create
method might throw QueryInvalidException
* if the query could not be compiled properly. Some implementations may not want
* to compile the query before execute
is called. In this case
* QueryInvalidException
is thrown when execute
is called.
* @param query An OQL query.
* @exception QueryInvalidException The query syntax is invalid.
*/
public void create(String query) throws QueryInvalidException;
/**
* Bind a parameter to the query.
* A parameter is denoted in the query string passed to create
by $i,
* where i is the rank of the parameter, beginning with 1.
* The parameters are set consecutively by calling this method bind
.
* The ith variable is set by the ith call to the bind
method.
* If any of the $i are not set by a call to bind
at the point
* execute
is called, QueryParameterCountInvalidException
is thrown.
* The parameters must be objects, and the result is an Object
.
* Objects must be used instead of primitive types (Integer
instead
* of int
) for passing the parameters.
*
* If the parameter is of the wrong type,
* QueryParameterTypeInvalidException
is thrown.
* After executing a query, the parameter list is reset.
* @param parameter A value to be substituted for a query parameter.
* @exception QueryParameterCountInvalidException The number of calls to
* bind
has exceeded the number of parameters in the query.
* @exception QueryParameterTypeInvalidException The type of the parameter does
* not correspond with the type of the parameter in the query.
*/
public void bind(Object parameter) throws QueryParameterCountInvalidException,
QueryParameterTypeInvalidException;
/**
* Execute the query.
* After executing a query, the parameter list is reset.
* Some implementations may throw additional exceptions that are also derived
* from ODMGException
.
* @return The object that represents the result of the query.
* The returned data, whatever its OQL type, is encapsulated into an object.
* For instance, when OQL returns an integer, the result is put into an
* Integer
object. When OQL returns a collection (literal or object),
* the result is always a Java collection object of the same kind
* (for instance, a DList
).
* @exception QueryException An exception has occurred while executing the query.
*/
public Object execute() throws QueryException;
}