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

All Superinterfaces:
  IQuery

public interface IAdvancedQuery
extends IQuery

An optional, extended query interface for more advanced query capabilities. It may have complex input parameters, scalar or complex output parameters, and/or return a single or multiple result sets.

A result set may be extended to be referenced by name. An input parameter may be extended to support the structure or table data type. An output parameter may be of scalar or structure data type.
All advanced query implementations (e.g. stored procedures, SAP R/3 BAPI's) should implement this interface.

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

Note: All IAdvancedQuery interface methods should only be called after IQuery.prepare() has been called.

Method Summary
`boolean` `execute()` Executes the query's prepared query that may return multiple result sets.
`int` `findOutParameter(java.lang.String parameterName)` Returns the 1-based index of the specified scalar or structure output parameter.
`java.math.BigDecimal` `getBigDecimal(int parameterId)` Returns the decimal value from the designated output parameter.
`java.math.BigDecimal` `getBigDecimal(java.lang.String parameterName)` Returns the decimal value from the designated output parameter.
`IBlob` `getBlob(int parameterId)` Returns the IBlob value from the designated output parameter.
`IBlob` `getBlob(java.lang.String parameterName)` Returns the IBlob value from the designated output parameter.
`IClob` `getClob(int parameterId)` Returns the IClob value from the designated output parameter.
`IClob` `getClob(java.lang.String parameterName)` Returns the IClob value from the designated output parameter.
`java.sql.Date` `getDate(int parameterId)` Returns the java.sql.Date value from the designated output parameter.
`java.sql.Date` `getDate(java.lang.String parameterName)` Returns the java.sql.Date value from the designated output parameter.
`double` `getDouble(int parameterId)` Returns the double value from the designated output parameter.
`double` `getDouble(java.lang.String parameterName)` Returns the double value from the designated output parameter.
`int` `getInt(int parameterId)` Returns the integer value from the designated output parameter.
`int` `getInt(java.lang.String parameterName)` Returns the integer value from the designated output parameter.
`IResultSetMetaData` `getMetaDataOf(java.lang.String resultSetName)` Returns the metadata of the expected named result.
`boolean` `getMoreResults()` Moves to the query's next result set.
`IResultSet` `getResultSet()` Returns the current result as an IResultSet object.
`IResultSet` `getResultSet(java.lang.String resultSetName)` Returns the named result as an IResultSet object, or null if none is available.
`java.lang.String[]` `getResultSetNames()` Returns the names of result sets that can be returned by this IAdvancedQuery.
`IParameterRowSet` `getRow(int parameterId)` Returns the structure value from the designated output parameter.
`IParameterRowSet` `getRow(java.lang.String parameterName)` Returns the structure value from the designated output parameter.
`SortSpec` `getSortSpec(java.lang.String resultSetName)` Returns the sort specification associated with the named result set of this `IAdvancedQuery`.
`java.lang.String` `getString(int parameterId)` Returns the String value from the designated output parameter.
`java.lang.String` `getString(java.lang.String parameterName)` Returns the String value from the designated output parameter.
`java.sql.Time` `getTime(int parameterId)` Returns the java.sql.Time value from the designated output parameter.
`java.sql.Time` `getTime(java.lang.String parameterName)` Returns the java.sql.Time value from the designated output parameter.
`java.sql.Timestamp` `getTimestamp(int parameterId)` Returns the java.sql.Timestamp value from the designated output parameter.
`java.sql.Timestamp` `getTimestamp(java.lang.String parameterName)` Returns the java.sql.Timestamp value from the designated output parameter.
`IParameterRowSet` `setNewRow(int parameterId)` Returns an IParameterRowSet object that contains a single row representing the specified structure input parameter.
`IParameterRowSet` `setNewRow(java.lang.String parameterName)` Returns an IParameterRowSet object that contains a single row representing the named structure input parameter.
`IParameterRowSet` `setNewRowSet(int parameterId)` Returns an empty IParameterRowSet object that represents the specified table input parameter.
`IParameterRowSet` `setNewRowSet(java.lang.String parameterName)` Returns an empty IParameterRowSet object that represents the named table input parameter.
`void` `setSortSpec(java.lang.String resultSetName, SortSpec sortBy)` Specifies the sort specification for the named result set of this `IAdvancedQuery`.
`boolean` `wasNull()` Returns whether the value read from the previous get<type> method was null.

Methods inherited from interface org.eclipse.datatools.connectivity.oda.IQuery
`clearInParameters, close, executeQuery, findInParameter, getMaxRows, getMetaData, getParameterMetaData, getSortSpec, prepare, setAppContext, setBigDecimal, setBigDecimal, setDate, setDate, setDouble, setDouble, setInt, setInt, setMaxRows, setProperty, setSortSpec, setString, setString, setTime, setTime, setTimestamp, setTimestamp`

Method Detail

### execute

    public boolean execute()
                    throws OdaException

  Executes the query's prepared query that may return multiple result sets. Note: This should only be called after prepare().

  Returns:
    true if the next result is an IResultSet object; false if there are no result sets.
  Throws:
    `OdaException` - if data source error occurs.

### getResultSet

    public IResultSet getResultSet()
                            throws OdaException

  Returns the current result as an IResultSet object. Note: This method should be called only once per result.

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

### getMoreResults

    public boolean getMoreResults()
                           throws OdaException

  Moves to the query's next result set. This method also implicitly closes the current IResultSet object obtained from the previous call to getResultSet().

  Returns:
    true, if there are more results in this query object.
  Throws:
    `OdaException` - if data source error occurs.

### getResultSetNames

    public java.lang.String[] getResultSetNames()
                                         throws OdaException

  Returns the names of result sets that can be returned by this IAdvancedQuery.
  An optional method; only applicable to a query that can retrieve multiple named result sets.

  Returns:
    an array of result set names.
  Throws:
    `OdaException` - if data source error occurs.

### getMetaDataOf

    public IResultSetMetaData getMetaDataOf(java.lang.String resultSetName)
                                     throws OdaException

  Returns the metadata of the expected named result.

  Parameters:
    `resultSetName` - the name of the result.
  Returns:
    an IResultSetMetaData object.
  Throws:
    `OdaException` - if data source error occurs.

### getResultSet

    public IResultSet getResultSet(java.lang.String resultSetName)
                            throws OdaException

  Returns the named result as an IResultSet object, or null if none is available. Note: This method should be called only once per result.

  Parameters:
    `resultSetName` - the name of the target result set.
  Returns:
    an IResultSet object.
  Throws:
    `OdaException` - if data source error occurs.

### setNewRow

    public IParameterRowSet setNewRow(java.lang.String parameterName)
                               throws OdaException

  Returns an IParameterRowSet object that contains a single row representing the named structure input parameter. Client will then use the IParameterRowSet setter methods to populate the input parameter values. For example:
  `
  IParameterRowSet myStruct = myQuery.setNewRow( "MyStructureName" );
  myStruct.next();
  myStruct.setString( 1, "myValue" );
  `
  An optional method; applicable only if named structure input parameters are supported.

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

### setNewRow

    public IParameterRowSet setNewRow(int parameterId)
                               throws OdaException

  Returns an IParameterRowSet object that contains a single row representing the specified structure input parameter. Client will then use the IParameterRowSet setter methods to populate the input parameter values.
  An optional method; applicable only if structure input parameters are supported.

  Parameters:
    `parameterId` - id of the parameter (1-based).
  Returns:
    an IParameterRowSet object.
  Throws:
    `OdaException` - if data source error occurs.

### setNewRowSet

    public IParameterRowSet setNewRowSet(java.lang.String parameterName)
                                  throws OdaException

  Returns an empty IParameterRowSet object that represents the named table input parameter. Client will then use the IParameterRowSet setter methods to populate each row of the input parameter values. For example:
  `
  IParameterRowSet myTable = myQuery.setNewRowSet( "MyTableName" );
  myTable.add();
  myTable.setString( 1, "myValue1" );
  myTable.add();
  myTable.setString( 1, "myValue2" );
  `
  An optional method; applicable only if named table input parameters are supported.

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

### setNewRowSet

    public IParameterRowSet setNewRowSet(int parameterId)
                                  throws OdaException

  Returns an empty IParameterRowSet object that represents the specified table input parameter. Client will then use the IParameterRowSet setter methods to populate each row of the input parameter values.
  An optional method; applicable only if table input parameters are supported.

  Parameters:
    `parameterId` - id of the parameter (1-based).
  Returns:
    an IParameterRowSet object.
  Throws:
    `OdaException` - if data source error occurs.

### getInt

    public int getInt(java.lang.String parameterName)
               throws OdaException

  Returns the integer value from the designated output parameter.

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

### getInt

    public int getInt(int parameterId)
               throws OdaException

  Returns the integer value from the designated output parameter.

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

### getDouble

    public double getDouble(java.lang.String parameterName)
                     throws OdaException

  Returns the double value from the designated output parameter.

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

### getDouble

    public double getDouble(int parameterId)
                     throws OdaException

  Returns the double value from the designated output parameter.

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

### getBigDecimal

    public java.math.BigDecimal getBigDecimal(java.lang.String parameterName)
                                       throws OdaException

  Returns the decimal value from the designated output parameter.

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

### getBigDecimal

    public java.math.BigDecimal getBigDecimal(int parameterId)
                                       throws OdaException

  Returns the decimal value from the designated output parameter.

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

### getString

    public java.lang.String getString(java.lang.String parameterName)
                               throws OdaException

  Returns the String value from the designated output parameter. An ODA runtime driver may or may not support getString() on a non-String type parameter. The format of the returned string is implementation- dependent.

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

### getString

    public java.lang.String getString(int parameterId)
                               throws OdaException

  Returns the String value from the designated output parameter. An ODA runtime driver may or may not support getString() on a non-String type parameter. The format of the returned string is implementation- dependent.

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

### getDate

    public java.sql.Date getDate(java.lang.String parameterName)
                          throws OdaException

  Returns the java.sql.Date value from the designated output parameter.

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

### getDate

    public java.sql.Date getDate(int parameterId)
                          throws OdaException

  Returns the java.sql.Date value from the designated output parameter.

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

### getTime

    public java.sql.Time getTime(java.lang.String parameterName)
                          throws OdaException

  Returns the java.sql.Time value from the designated output parameter.

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

### getTime

    public java.sql.Time getTime(int parameterId)
                          throws OdaException

  Returns the java.sql.Time value from the designated output parameter.

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

### getTimestamp

    public java.sql.Timestamp getTimestamp(java.lang.String parameterName)
                                    throws OdaException

  Returns the java.sql.Timestamp value from the designated output parameter.

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

### getTimestamp

    public java.sql.Timestamp getTimestamp(int parameterId)
                                    throws OdaException

  Returns the java.sql.Timestamp value from the designated output parameter.

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

### getBlob

    public IBlob getBlob(java.lang.String parameterName)
                  throws OdaException

  Returns the IBlob value from the designated output parameter.

  Note: The driver must guarantee that the returned IBlob object and its BLOB data would remain valid and accessible until this query instance is closed.

  Parameters:
    `parameterName` - name of the parameter.
  Returns:
    an IBlob object that represents the BLOB value; or `null` if the specific parameter has null value.
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.0

### getBlob

    public IBlob getBlob(int parameterId)
                  throws OdaException

  Returns the IBlob value from the designated output parameter.

  Note: The driver must guarantee that the returned IBlob object and its BLOB data would remain valid and accessible until this query instance is closed.

  Parameters:
    `parameterId` - id of the parameter (1-based).
  Returns:
    an IBlob object that represents the BLOB value; or `null` if the specific parameter has null value.
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.0

### getClob

    public IClob getClob(java.lang.String parameterName)
                  throws OdaException

  Returns the IClob value from the designated output parameter.

  Note: The driver must guarantee that the returned IClob object and its CLOB data would remain valid and accessible until this query instance is closed.

  Parameters:
    `parameterName` - name of the parameter.
  Returns:
    an IClob object that represents the CLOB value; or `null` if the specific parameter has null value.
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.0

### getClob

    public IClob getClob(int parameterId)
                  throws OdaException

  Returns the IClob value from the designated output parameter.

  Note: The driver must guarantee that the returned IClob object and its CLOB data would remain valid and accessible until this query instance is closed.

  Parameters:
    `parameterId` - id of the parameter (1-based).
  Returns:
    an IClob object that represents the CLOB value; or `null` if the specific parameter has null value.
  Throws:
    `OdaException` - if data source error occurs
  Since:
    3.0

### getRow

    public IParameterRowSet getRow(java.lang.String parameterName)
                            throws OdaException

  Returns the structure value from the designated output parameter. This is not intended to return table structures.
  An optional method; applicable only if named structure output parameters are supported.

  Parameters:
    `parameterName` - name of the parameter.
  Returns:
    an IParameterRowSet object with a single row.
  Throws:
    `OdaException` - if data source error occurs.

### getRow

    public IParameterRowSet getRow(int parameterId)
                            throws OdaException

  Returns the structure value from the designated output parameter.
  An optional method; applicable only if structure output parameters are supported.

  Parameters:
    `parameterId` - id of the parameter (1-based).
  Returns:
    an IParameterRowSet object with a single row.
  Throws:
    `OdaException` - if data source error occurs.

### findOutParameter

    public int findOutParameter(java.lang.String parameterName)
                         throws OdaException

  Returns the 1-based index of the specified scalar or structure output parameter.

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

### wasNull

    public boolean wasNull()
                    throws OdaException

  Returns whether the value read from the previous get<type> method was null.

  Returns:
    true, if the last get<type> call was null.
  Throws:
    `OdaException` - if data source error occurs.

### setSortSpec

    public void setSortSpec(java.lang.String resultSetName,
                            SortSpec sortBy)
                     throws OdaException

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

  It is up to individual ODA runtime drivers to validate the type of sort specification that are acceptable to the 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:
    `resultSetName` - name of the result set.
    `sortBy` - the sort specification to apply to the specified result set.
  Throws:
    `OdaException` - if data source error occurs.

### getSortSpec

    public SortSpec getSortSpec(java.lang.String resultSetName)
                         throws OdaException

  Returns the sort specification associated with the named result set of this `IAdvancedQuery`.

  Parameters:
    `resultSetName` - name of the result set.
  Returns:
    the `SortSpec` associated with the specified result set; `null` if no `SortSpec` was explicitly set.
  Throws:
    `OdaException` - if data source error occurs.

Copyright © 2006 Actuate, IBM Corporation, Sybase, Inc. and others. All rights reserved.