## org.eclipse.datatools.connectivity.oda
Interface IQuery

All Known Subinterfaces:
  IAdvancedQuery

    public interface IQuery

The base query interface to prepare and execute a query text to retrieve data. This base interface covers most basic query capabilities, such as returning data rows in a single result set, and may support scalar input parameters.

Note: An IQuery object must always be prepared before it can be executed. For example:

`query.prepare( "SELECT * FROM TABLE" );
// prepare succeeded, no exception was thrown
query.executeQuery();`

An input parameter may be referenced by name or position.
The case-sensitivity of a name is implementation-dependent. All indices in this interface are 1-based.

Method Summary
`void` `cancel()` Cancels this query to abort its execution if supported by the underlying data source.
`void` `clearInParameters()` An optional method to clear the current input parameter values immediately.
`void` `close()` Attempts to close this IQuery.
`IResultSet` `executeQuery()` Executes the query's prepared query text and returns a single IResultSet object.
`int` `findInParameter(java.lang.String parameterName)` Returns the 1-based index of the specified input parameter.
`java.lang.String` `getEffectiveQueryText()` Gets the current effective query text that this query has prepared.
`int` `getMaxRows()` Returns the maximum number of rows that can be fetched from the query's result set(s).
`IResultSetMetaData` `getMetaData()` Returns the metadata of the current result set for this prepared IQuery.
`IParameterMetaData` `getParameterMetaData()` Returns the count, data types, and other metadata attributes of the parameters defined in this prepared IQuery object.
`SortSpec` `getSortSpec()` Returns the sort specification associated with this `IQuery`.
`QuerySpecification` `getSpecification()` Gets the current specification of query characteristics to apply when this query is prepared and executed.
`void` `prepare(java.lang.String queryText)` Performs necessary checks to determine whether the query text is of a valid format supported by this IQuery implementation.
`void` `setAppContext(java.lang.Object context)` Sets the query context passed through from an application.
`void` `setBigDecimal(int parameterId, java.math.BigDecimal value)` Sets the designated parameter to the given decimal value.
`void` `setBigDecimal(java.lang.String parameterName, java.math.BigDecimal value)` Sets the designated parameter to the given decimal value.
`void` `setBoolean(int parameterId, boolean value)` Sets the designated parameter to the given boolean value.
`void` `setBoolean(java.lang.String parameterName, boolean value)` Sets the designated parameter to the given boolean value.
`void` `setDate(int parameterId, java.sql.Date value)` Sets the designated parameter to the given Date value.
`void` `setDate(java.lang.String parameterName, java.sql.Date value)` Sets the designated parameter to the given Date value.
`void` `setDouble(int parameterId, double value)` Sets the designated parameter to the given double value.
`void` `setDouble(java.lang.String parameterName, double value)` Sets the designated parameter to the given double value.
`void` `setInt(int parameterId, int value)` Sets the designated parameter to the given integer value.
`void` `setInt(java.lang.String parameterName, int value)` Sets the designated parameter to the given integer value.
`void` `setMaxRows(int max)` Specifies the maximum number of rows that can be fetched from the query's result set(s).
`void` `setNull(int parameterId)` Sets the designated parameter to a null value.
`void` `setNull(java.lang.String parameterName)` Sets the designated parameter to a null value.
`void` `setObject(int parameterId, java.lang.Object value)` Sets the value of the designated parameter with the given object.
`void` `setObject(java.lang.String parameterName, java.lang.Object value)` Sets the value of the designated parameter with the given object.
`void` `setProperty(java.lang.String name, java.lang.String value)` Sets the named property with the specified value.
`void` `setSortSpec(SortSpec sortBy)` Specifies the sort specification for this `IQuery`.
`void` `setSpecification(QuerySpecification querySpec)` Specifies the query characteristics to apply when this query is prepared and executed.
`void` `setString(int parameterId, java.lang.String value)` Sets the designated parameter to the given string value.
`void` `setString(java.lang.String parameterName, java.lang.String value)` Sets the designated parameter to the given string value.
`void` `setTime(int parameterId, java.sql.Time value)` Sets the designated parameter to the given Time value.
`void` `setTime(java.lang.String parameterName, java.sql.Time value)` Sets the designated parameter to the given Time value.
`void` `setTimestamp(int parameterId, java.sql.Timestamp value)` Sets the designated parameter to the given Timestamp value.
`void` `setTimestamp(java.lang.String parameterName, java.sql.Timestamp value)` Sets the designated parameter to the given Timestamp value.

Method Detail

### prepare

    void prepare(java.lang.String queryText)
                 throws OdaException

  Performs necessary checks to determine whether the query text is of a valid format supported by this IQuery implementation.

  Parameters:
    `queryText` - a query text to prepare or pre-compile; it cannot be null.
  Throws:
    `OdaException` - if data source error occurs

### setAppContext

    void setAppContext(java.lang.Object context)
                       throws OdaException

  Sets the query context passed through from an application. Its handling is specific to individual driver implementation. The context argument could be null. The method may be called by an ODA consumer application with a null argument, i.e. passing a null context object to this instance, only if a non-null context was previously passed through to the same instance.
  Note: This method should be called before prepare().
  An optional method. If any part of the context is not recognized by the driver, it should simply ignore, and not throw an exception.

  Parameters:
    `context` - Application context object of this instance.
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.0

### setProperty

    void setProperty(java.lang.String name,
                     java.lang.String value)
                     throws OdaException

  Sets the named property with the specified value. Multiple calls using the same property name may be allowed to assign multiple values to the same property. Its handling is specific to individual driver implementation. If a property name is not recognized by the driver, it should simply ignore, and not throw an exception.
  Each ODA extension property defined for a data set triggers an ODA consumer to call this method with corresponding property value, which may be null. An ODA consumer does not distinguish whether a property value is not set or explicitly set to null. Its handling is specific to individual driver implementation.
  Note: This method should be called after `prepare(String)`, and before `executeQuery()` or other extended execution method(s).
  An optional method.

  Parameters:
    `name` - name of the property.
    `value` - value to assign to the named property; may be null.
  Throws:
    `OdaException` - if data source error occurs

### close

    void close()
               throws OdaException

  Attempts to close this IQuery.

  Throws:
    `OdaException` - if data source error occurs

### setMaxRows

    void setMaxRows(int max)
                    throws OdaException

  Specifies the maximum number of rows that can be fetched from the query's result set(s).
  An optional method.

  Parameters:
    `max` - the maximum number of rows that can be fetched from each result set of this IQuery; zero means there is no limit.
  Throws:
    `OdaException` - if data source error occurs

### getMaxRows

    int getMaxRows()
                   throws OdaException

  Returns the maximum number of rows that can be fetched from the query's result set(s).
  An optional method.

  Returns:
    the maximum number of rows that can be fetched from each result set of this IQuery; zero means there is no limit.
  Throws:
    `OdaException` - if data source error occurs

### getMetaData

    IResultSetMetaData getMetaData()
                                   throws OdaException

  Returns the metadata of the current result set for this prepared IQuery. This can be called only after prepare(). If the method is called before the IQuery is executed, the returned metadata refers to its first result set.

  Returns:
    an IResultSetMetaData object.
  Throws:
    `OdaException` - if data source error occurs

### executeQuery

    IResultSet executeQuery()
                            throws OdaException

  Executes the query's prepared query text and returns a single IResultSet object. Note: This should only be called after prepare().

  Returns:
    an IResultSet object.
  Throws:
    `OdaException` - if data source error occurs

### clearInParameters

    void clearInParameters()
                           throws OdaException

  An optional method to clear the current input parameter values immediately.

  In general, input parameter values remain in force for repeated use of a query. Setting a parameter value automatically clears its previous value. However, to reset all the parameters to their default values without explicitly setting new values, use this method.

  Throws:
    `OdaException` - if data source error occurs
    `java.lang.UnsupportedOperationException` - if this operation is not supported

### setInt

    void setInt(java.lang.String parameterName,
                int value)
                throws OdaException

  Sets the designated parameter to the given integer value.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - integer value.
  Throws:
    `OdaException` - if data source error occurs

### setInt

    void setInt(int parameterId,
                int value)
                throws OdaException

  Sets the designated parameter to the given integer value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - integer value.
  Throws:
    `OdaException` - if data source error occurs

### setDouble

    void setDouble(java.lang.String parameterName,
                   double value)
                   throws OdaException

  Sets the designated parameter to the given double value.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - double value.
  Throws:
    `OdaException` - if data source error occurs

### setDouble

    void setDouble(int parameterId,
                   double value)
                   throws OdaException

  Sets the designated parameter to the given double value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - double value.
  Throws:
    `OdaException` - if data source error occurs

### setBigDecimal

    void setBigDecimal(java.lang.String parameterName,
                       java.math.BigDecimal value)
                       throws OdaException

  Sets the designated parameter to the given decimal value.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - decimal value.
  Throws:
    `OdaException` - if data source error occurs

### setBigDecimal

    void setBigDecimal(int parameterId,
                       java.math.BigDecimal value)
                       throws OdaException

  Sets the designated parameter to the given decimal value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - decimal value.
  Throws:
    `OdaException` - if data source error occurs

### setString

    void setString(java.lang.String parameterName,
                   java.lang.String value)
                   throws OdaException

  Sets the designated parameter to the given string value. An ODA runtime driver may or may not support setString() on a non-String type parameter. The format of the string parameter is implementation-dependent.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - string value.
  Throws:
    `OdaException` - if data source error occurs

### setString

    void setString(int parameterId,
                   java.lang.String value)
                   throws OdaException

  Sets the designated parameter to the given string value. An ODA runtime driver may or may not support setString() on a non-String type parameter. The format of the string parameter is implementation-dependent.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - string value.
  Throws:
    `OdaException` - if data source error occurs

### setDate

    void setDate(java.lang.String parameterName,
                 java.sql.Date value)
                 throws OdaException

  Sets the designated parameter to the given Date value.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - the java.sql.Date value.
  Throws:
    `OdaException` - if data source error occurs

### setDate

    void setDate(int parameterId,
                 java.sql.Date value)
                 throws OdaException

  Sets the designated parameter to the given Date value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - the java.sql.Date value.
  Throws:
    `OdaException` - if data source error occurs

### setTime

    void setTime(java.lang.String parameterName,
                 java.sql.Time value)
                 throws OdaException

  Sets the designated parameter to the given Time value.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - the java.sql.Time value.
  Throws:
    `OdaException` - if data source error occurs

### setTime

    void setTime(int parameterId,
                 java.sql.Time value)
                 throws OdaException

  Sets the designated parameter to the given Time value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - the java.sql.Time value.
  Throws:
    `OdaException` - if data source error occurs

### setTimestamp

    void setTimestamp(java.lang.String parameterName,
                      java.sql.Timestamp value)
                      throws OdaException

  Sets the designated parameter to the given Timestamp value.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - the java.sql.Timestamp value.
  Throws:
    `OdaException` - if data source error occurs

### setTimestamp

    void setTimestamp(int parameterId,
                      java.sql.Timestamp value)
                      throws OdaException

  Sets the designated parameter to the given Timestamp value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - the java.sql.Timestamp value.
  Throws:
    `OdaException` - if data source error occurs

### setBoolean

    void setBoolean(java.lang.String parameterName,
                    boolean value)
                    throws OdaException

  Sets the designated parameter to the given boolean value.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - boolean value.
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.1

### setBoolean

    void setBoolean(int parameterId,
                    boolean value)
                    throws OdaException

  Sets the designated parameter to the given boolean value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - boolean value
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.1

### setObject

    void setObject(java.lang.String parameterName,
                   java.lang.Object value)
                   throws OdaException

  Sets the value of the designated parameter with the given object.

  Parameters:
    `parameterName` - name of the parameter.
    `value` - an `Object` holding the input parameter value
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.2 (DTP 1.7)

### setObject

    void setObject(int parameterId,
                   java.lang.Object value)
                   throws OdaException

  Sets the value of the designated parameter with the given object.

  Parameters:
    `parameterId` - id of the parameter (1-based).
    `value` - an `Object` holding the input parameter value
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.2 (DTP 1.7)

### setNull

    void setNull(java.lang.String parameterName)
                 throws OdaException

  Sets the designated parameter to a null value.

  Parameters:
    `parameterName` - name of the parameter.
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.1

### setNull

    void setNull(int parameterId)
                 throws OdaException

  Sets the designated parameter to a null value.

  Parameters:
    `parameterId` - id of the parameter (1-based).
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.1

### findInParameter

    int findInParameter(java.lang.String parameterName)
                        throws OdaException

  Returns the 1-based index of the specified input parameter.

  Parameters:
    `parameterName` - name of the parameter.
  Returns:
    index of the parameter.
  Throws:
    `OdaException` - if data source error occurs

### getParameterMetaData

    IParameterMetaData getParameterMetaData()
                                            throws OdaException

  Returns the count, data types, and other metadata attributes of the parameters defined in this prepared IQuery object. Its implementation is required for ODA runtime drivers.

  Note: This should only be called after prepare() is called.

  Returns:
    an IParameterMetaData object that contains information about this prepared IQuery object's parameters.
  Throws:
    `OdaException` - if data source error occurs

### setSortSpec

    void setSortSpec(SortSpec sortBy)
                     throws OdaException

  Specifies the sort specification for this `IQuery`. This method must be called before this `IQuery` is executed or before `IAdvancedQuery.getMoreResults()` is called. More sort keys can be added to the SortSpec after it is associated with the query. The final sort specification is then applied to subsequent result set(s) at execution.

  It is up to individual ODA runtme drivers to validate the type of sort specification that are acceptable to its data provider, based on its level of dynamic sorting support. An `OdaException` should be thrown if the specified sort specification is not valid or not supported by the driver.

  Parameters:
    `sortBy` - the sort specification assigned to this `IQuery`.
  Throws:
    `OdaException` - if data source error occurs

### getSortSpec

    SortSpec getSortSpec()
                         throws OdaException

  Returns the sort specification associated with this `IQuery`.

  Returns:
    the `SortSpec` assigned to this `IQuery`; `null` if no `SortSpec` was explicitly set.
  Throws:
    `OdaException` - if data source error occurs

### setSpecification

    void setSpecification(QuerySpecification querySpec)
                          throws OdaException,
                                 java.lang.UnsupportedOperationException

  Specifies the query characteristics to apply when this query is prepared and executed. It takes effect only if set prior to preparing a query text on `prepare(String)`.

  An optional method. Driver implementation that does not support this method should throw an UnsupportedOperationException.

  Parameters:
    `querySpec` - specification of query characteristics to apply when this is prepared and executed
  Throws:
    `OdaException` - if data source error occurs
    `java.lang.UnsupportedOperationException` - if this method is not supported
  Since:
    3.2 (DTP 1.7)

### getSpecification

    QuerySpecification getSpecification()

  Gets the current specification of query characteristics to apply when this query is prepared and executed.

  Returns:
    the current `QuerySpecification`, or null if none is effective or available
  Since:
    3.2 (DTP 1.7)

### getEffectiveQueryText

    java.lang.String getEffectiveQueryText()

  Gets the current effective query text that this query has prepared. The effective query text may be different from the argument of `prepare(String)`, having been adjusted based on the `QuerySpecification` set by `setSpecification(QuerySpecification)`. This may be requested by a consumer before executing this query.
  An optional method.

  Returns:
    the current effective query text, or null if no query text is effective or available at the current query state
  Since:
    3.2 (DTP 1.7)

### cancel

    void cancel()
                throws OdaException,
                       java.lang.UnsupportedOperationException

  Cancels this query to abort its execution if supported by the underlying data source. This method can be used by one thread to cancel a query that is being executed by another thread.

  An optional method. Driver implementation that does not support this operation should throw an UnsupportedOperationException.

  Throws:
    `OdaException` - if data source error occurs or this method is called at an invalid state
    `java.lang.UnsupportedOperationException` - if this operation is not supported at any state
  Since:
    3.2 (DTP 1.7)