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.
 boolean getBoolean(int parameterId)
          Returns the boolean value from the designated output parameter.
 boolean getBoolean(java.lang.String parameterName)
          Returns the boolean 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, setBoolean, setBoolean, setDate, setDate, setDouble, setDouble, setInt, setInt, setMaxRows, setNull, setNull, setProperty, setSortSpec, setString, setString, setTime, setTime, setTimestamp, setTimestamp
 

Method Detail

execute

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

getBoolean

boolean getBoolean(java.lang.String parameterName)
                   throws OdaException
Returns the boolean value from the designated output parameter.

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

getBoolean

boolean getBoolean(int parameterId)
                   throws OdaException
Returns the boolean value from the designated output parameter.

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

getRow

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

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

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

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

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

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 -- 2008 Actuate, IBM Corporation, Sybase, Inc. and others. All rights reserved.