org.odmg
Interface OQLQuery

All Known Subinterfaces:

EnhancedOQLQuery

All Known Implementing Classes:

OQLQueryImpl

public interface OQLQuery

The interface to an OQL query object.

Version:

ODMG 3.0

Author:

David Jordan (as Java Editor of the Object Data Management Group)

Method Summary

void	bind(Object parameter) Bind a parameter to the query.
void	create(String query) Create an OQL query from the string parameter.
Object	execute() Execute the query.

Method Detail

create

void create(String query)
            throws QueryInvalidException

Create an OQL query from the string parameter. In order to execute a query, an 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.

Parameters:

query - An OQL query.

Throws:

QueryInvalidException - The query syntax is invalid.

bind

void bind(Object parameter)
          throws QueryParameterCountInvalidException,
                 QueryParameterTypeInvalidException

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.

Throws:

QueryParameterCountInvalidException - The number of calls to bind has exceeded the number of parameters in the query.

QueryParameterTypeInvalidException - The type of the parameter does not correspond with the type of the parameter in the query.

execute

Object execute()
               throws QueryException

Execute the query. After executing a query, the parameter list is reset. Some implementations may throw additional exceptions that are also derived from ODMGException.

Returns:

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).

Throws:

QueryException - An exception has occurred while executing the query.