javax.infobus
Interface RowsetAccess

All Known Subinterfaces:
ScrollableRowsetAccess

public abstract interface RowsetAccess

DataItems that implement the RowsetAcess interface represent a set of rows resulting from a query against a database. The RowsetAccess interface contains methods to get metadata (number of columns, plus column names and datatypes), to read the rows, to extract column values, to update rows, to validate changes and send changes to the database, and to obtain a DbAccess object for the associated database.


Method Summary
 boolean canDelete()
          Determine if deleting rows is allowed
 boolean canInsert()
          Determine if inserting rows is allowed
 boolean canUpdate()
          Returns true if modifying the items in all columns in the existing rows is allowed, false otherwise.
 boolean canUpdate(int columnNumber)
          Returns true if modifying the items in the specified column is allowed, false otherwise.
 boolean canUpdate(java.lang.String columnName)
          Returns true if modifying the items in the specified column is allowed, false otherwise.
 void deleteRow()
          Delete the current row.
 void flush()
          Flush all changes to the underlying database.
 int getColumnCount()
          Returns the number of columns in the rowset.
 java.lang.String getColumnDatatypeName(int columnIndex)
          Given the one based column index, returns the column's data source specific type name.
 int getColumnDatatypeNumber(int columnIndex)
          Given the one based columnIndex, returns the data type for the column using the encoding specified by java.sql.Types
 java.lang.Object getColumnItem(int columnIndex)
          Given the one based column index, returns an Object which can be used to obtain the current value of the specified column.
 java.lang.Object getColumnItem(java.lang.String columnName)
          Given the name of the column, returns an Object which can be used to obtain the current value of the column.
 java.lang.String getColumnName(int columnIndex)
          Returns the name of the column indicated by columnIndex if a name is available.
 DbAccess getDb()
          Get the RowsetAccess item's database
 int getHighWaterMark()
          Return the total number of rows known to the producer so far.
 boolean hasMoreRows()
          Return true if there may be more rows to fetch.
 void lockRow()
          Lock the current row.
 void newRow()
          Create a new, empty row and set the row cursor to this row.
 boolean next()
          Advances the row cursor to the next row.
 void setColumnValue(int columnIndex, java.lang.Object object)
          Given the one-based index of a column, set the value of the column in the current row.
 void setColumnValue(java.lang.String columnName, java.lang.Object object)
          Given the name of a column, set the value of the column in the current row.
 

Method Detail

getColumnCount

public int getColumnCount()
Returns the number of columns in the rowset.
Returns:
number of columns

getColumnName

public java.lang.String getColumnName(int columnIndex)
                               throws java.lang.IndexOutOfBoundsException
Returns the name of the column indicated by columnIndex if a name is available. Some calculated columns may have no name.
Parameters:
columnIndex - a one-based index of a rowset column
Returns:
the name of the corresponding column, or null if no name is available
Throws:
java.lang.IndexOutOfBoundsException - if columnIndex falls outside the range of valid indexes for this rowset

getColumnDatatypeNumber

public int getColumnDatatypeNumber(int columnIndex)
                            throws java.lang.IndexOutOfBoundsException
Given the one based columnIndex, returns the data type for the column using the encoding specified by java.sql.Types
Parameters:
columnIndex - a one-based index of a rowset column
Returns:
the encoding for the indicated column. See java.sql.types.
Throws:
java.lang.IndexOutOfBoundsException - if columnIndex falls outside the range of valid indexes for this rowset

getColumnDatatypeName

public java.lang.String getColumnDatatypeName(int columnIndex)
                                       throws java.lang.IndexOutOfBoundsException
Given the one based column index, returns the column's data source specific type name. See java.sql.ResultSetMetaData.
Parameters:
columnIndex - a one-based index of a rowset column
Returns:
the source specific type name
Throws:
java.lang.IndexOutOfBoundsException - if columnIndex falls outside the range of valid indexes for this rowset

next

public boolean next()
             throws java.sql.SQLException,
                    RowsetValidationException
Advances the row cursor to the next row. Returns true if the call has advanced the cursor to a new row, false if the call has advanced the cursor beyond the last row. It is valid for a rowset to contain zero rows, so the first call to nextRow may return false. Changing the row cursor may propagate a new or updated row to the backing store, and this may cause an exception.
Returns:
true if the new row is available, false if the cursor has advanced past the last row
Throws:
java.sql.SQLException - if a new or updated row implicitly submitted to the backend is rejected.
RowsetValidationException - if a new or updated row implicitly submitted to the data producer is invalid.

getHighWaterMark

public int getHighWaterMark()
Return the total number of rows known to the producer so far. This is generally be less than the total number of rows until the last row or "chunk" of rows has been fetched by the producer. This should not throw an exception.
Returns:
number of rows

hasMoreRows

public boolean hasMoreRows()
Return true if there may be more rows to fetch. This is conservative -- the producer may return true after fetching the last row before discovering it was the last row.
Returns:
true if there may be more rows to fetch.

getColumnItem

public java.lang.Object getColumnItem(int columnIndex)
                               throws java.lang.IndexOutOfBoundsException,
                                      java.sql.SQLException
Given the one based column index, returns an Object which can be used to obtain the current value of the specified column. The Object usually implments the ImmediateAccess interface. The value changes as nextRow is called, that is the Object tracks the current row.
Parameters:
columnIndex - the index of the column desired
Returns:
the data in that column
Throws:
java.lang.IndexOutOfBoundsException - if columnIndex falls outside the range of valid indexes for this rowset
java.sql.SQLException - if a new or updated row implicitly submitted to the backend is rejected, and also for other backend errors.

getColumnItem

public java.lang.Object getColumnItem(java.lang.String columnName)
                               throws ColumnNotFoundException,
                                      DuplicateColumnException,
                                      java.sql.SQLException
Given the name of the column, returns an Object which can be used to obtain the current value of the column. This Object usually implements the ImmediateAccess interface. The value changes as nextRow is called, that is the Object tracks the current row.
Parameters:
columnName - the name of the column desired
Returns:
the data in that column
Throws:
ColumnNotFoundException - if a column matching colName is not present in the rowset
DuplicateColumnException - if more than one column in the rowset matches colName
java.sql.SQLException - if a new or updated row implicitly submitted to the backend is rejected, and also for other backend errors.

newRow

public void newRow()
            throws java.sql.SQLException,
                   RowsetValidationException
Create a new, empty row and set the row cursor to this row. May implicitly submit a previous new or modified row to the backend, and this may cause an exception.
Throws:
java.sql.SQLException - if a new or updated row implicitly submitted to the backend is rejected, and also for other backend errors.
RowsetValidationException - if a new or updated row implicitly submitted to the data producer is invalid.

setColumnValue

public void setColumnValue(int columnIndex,
                           java.lang.Object object)
                    throws java.lang.IndexOutOfBoundsException,
                           java.sql.SQLException,
                           RowsetValidationException
Given the one-based index of a column, set the value of the column in the current row. Note that this may also be done via ImmediateAccess.setValue.
Parameters:
columnIndex - one-based column number
object - new value for the column
Throws:
java.lang.IndexOutOfBoundsException - if the column index is not valid
java.sql.SQLException - if the backend rejects the change
RowsetValidationException - if the new value is invalid

setColumnValue

public void setColumnValue(java.lang.String columnName,
                           java.lang.Object object)
                    throws ColumnNotFoundException,
                           DuplicateColumnException,
                           java.sql.SQLException,
                           RowsetValidationException
Given the name of a column, set the value of the column in the current row.
Parameters:
columnName - the name of the column
object - new value for column
Throws:
ColumnNotFoundException - if a column matching colName is not present in the rowset
DuplicateColumnException - if more than one column in the rowset matches colName
java.sql.SQLException - if the backend rejects the change
RowsetValidationException - if the new value is invalid

deleteRow

public void deleteRow()
               throws java.sql.SQLException,
                      RowsetValidationException
Delete the current row.
Throws:
java.sql.SQLException - if the backend rejects the deletion
RowsetValidationException - if the deletion is invalid

flush

public void flush()
           throws java.sql.SQLException,
                  RowsetValidationException
Flush all changes to the underlying database.
Throws:
java.sql.SQLException - if the backend rejects some change
RowsetValidationException - if the change is invalid

lockRow

public void lockRow()
             throws java.sql.SQLException,
                    RowsetValidationException
Lock the current row. Does nothing if this is not supported by the producer.
Throws:
java.sql.SQLException - if a backend error occurred
RowsetValidationException - if the operation is invalid

canInsert

public boolean canInsert()
Determine if inserting rows is allowed
Returns:
true if inserting rows is allowed, false otherwise

canUpdate

public boolean canUpdate()
Returns true if modifying the items in all columns in the existing rows is allowed, false otherwise.
Returns:
true if updating all rows is allowed, false otherwise

canUpdate

public boolean canUpdate(java.lang.String columnName)
                  throws ColumnNotFoundException,
                         DuplicateColumnException
Returns true if modifying the items in the specified column is allowed, false otherwise.
Returns:
true if updating the specified column is allowed, false otherwise
Throws:
ColumnNotFoundException - if the named column was not found
DuplicateColumnNameException - if there of multiple columns with the specified name.

canUpdate

public boolean canUpdate(int columnNumber)
                  throws java.lang.IndexOutOfBoundsException
Returns true if modifying the items in the specified column is allowed, false otherwise.
Returns:
true if updating the specified column is allowed, false otherwise
Throws:
java.lang.IndexOutOfBoundsException - if the supplied column number is out of range

canDelete

public boolean canDelete()
Determine if deleting rows is allowed
Returns:
true if deleting rows is allowed, false otherwise

getDb

public DbAccess getDb()
Get the RowsetAccess item's database
Returns:
an instance of DbAccess representing the database associated with the RowsetAccess item and returns null if the producer does not support the DbAccess interface.