Overview | Package | Class | Use | Tree | Deprecated | Index | Help
|  | BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## weblogic.db.jdbc
Class TableDataSet

    java.lang.Object
      |
      +--weblogic.db.jdbc.DataSet
            |
            +--weblogic.db.jdbc.TableDataSet

public final class TableDataSet
extends DataSet

A TableDataSet holds the results of an SQL query on a single table. The results are available as a collection of Records accessible by an integer index. Each record has all the attributes of the specified table, unless a subset of attributes is specified. The API allows you to specify the WHERE and ORDER BY clauses as well.

You can update values in the Records, add new Records, and mark Records for deletion. After making such changes, you can save the changes to a database. You can execute TableDataSet.save() to save all the changes made to a TableDataset, or you can execute Record.save() to save changes to a single record.

If you intend to save updates or deletes to a database, you must provide a KeyDef object in the TableDataSet constructor. The KeyDef object is used to specify a unique key that is the basis for forming the WHERE clause automatically generated in the UPDATE and DELETE statements. A KeyDef object is not necessary if only inserts take place, since they are performed without a WHERE clause.

Each TableDataSet also has a default SelectStmt object that can be used to take advantage of QBE functionality.

If you do not want to save changes to a database, or if you want to execute an arbitrary SQL query involving more than one table, use a QueryDataSet instead.

The following example shows how to create a TableDataSet, add 10 records to it, and insert the records into the database. Note that the TableDataSet must be closed when work with it is completed.

       TableDataSet tds = new TableDataSet(conn, "emp");
       for (int i = 0; i < 10; i++) {
         Record rec = tds.addRecord();
         rec.setValue("recnum", i)
            .setValue("firstname", "joe")
            .setValue("lastname",  "smith");
       tds.save();
       tds.close();  // This must be called

For more implementation and usage see the Developers Guide.

Author:
  Copyright (c) 1995-1998 by WebLogic, Inc. All Rights Reserved., Copyright (c) 1998-1999 by BEA Systems, Inc. All Rights Reserved.
See Also:
  `KeyDef`, `DataSet`, `QueryDataSet`, `SelectStmt`, Serialized Form

Field Summary
`protected KeyDef` | `keydefval`

Fields inherited from class weblogic.db.jdbc.DataSet
`cached, resetable, resultval, stmt`

Constructor Summary
`TableDataSet()` Private - used for serialization
`TableDataSet(java.sql.Connection conn, Schema schema, KeyDef key)` Constructs a TableDataSet from the specified Schema and KeyDef.
`TableDataSet(java.sql.Connection conn, java.lang.String tablename)` Constructs a TableDataSet from the specified table.
`TableDataSet(java.sql.Connection conn, java.lang.String tablename, KeyDef key)` Constructs a TableDataSet from the specified table, and sets its KeyDef, which is used to specify a unique key for updates and deletes.
`TableDataSet(java.sql.Connection conn, java.lang.String tablename, java.lang.String attributes)` Constructs a TableDataSet from the specified table, limited to the specified set of attributes (columns).
`TableDataSet(java.sql.Connection conn, java.lang.String tablename, java.lang.String attributes, KeyDef key)` Constructs a TableDataSet from the specified table, limited to the specified set of attributes (columns).

Method Summary
`java.lang.String` | `attributes()` Returns the set of attributes with which a TableDataSet was constructed.
`java.lang.String` | `debugInfo()` Returns information about a TableDataSet object for debugging purposes.
`DataSet` | `fetchRecords(int start, int maxrecs)` Fetches at most the specified number of records starting at the specified record.
`java.lang.String` | `getSelectString()` Returns the SQL SELECT string of the query that was used to populate a TableDataSet.
`KeyDef` | `keydef()` Returns the KeyDef for a TableDataSet.
`java.lang.String` | `optimisticLockingCol()`
`TableDataSet` | `order(java.lang.String str)` Sets the ORDER BY clause for a TableDataSet.
`protected java.lang.String` | `orderstr()`
`TableDataSet` | `other(java.lang.String str)` Sets additional SQL clause for a TableDataSet.
`void` | `refresh(java.sql.Connection conn)` Refreshes all of the records in the TableDataSet from the DBMS.
`boolean` | `refreshOnSave()` Returns the current setting of setRefreshOnSave(), which is False by default.
`void` | `removeDeletedRecords()` Removes deleted records from the TableDataSet.
`java.sql.ResultSet` | `resultSet()` Returns the JDBC ResultSet associated with a TableDataSet.
`int` | `save()` Saves changes made in a TableDataSet to a database using the default Connection.
`int` | `save(boolean intransaction)` Saves changes made in a TableDataSet to a database using the default Connection.
`int` | `save(java.sql.Connection conn, boolean intransaction)` Saves changes made in a TableDataSet to a database using the specified Connection.
`int` | `saveWithoutStatusUpdate(java.sql.Connection conn)`
`Schema` | `schema()` Returns the Schema of a TableDataSet.
`SelectStmt` | `selectStmt()` Returns the SelectStmt object associated with a TableDataSet.
`void` | `setOptimisticLockingColumn(java.lang.String colName)` Identifies the table column used for optimistic locking.
`void` | `setRefreshOnSave(boolean yesOrNo)` Sets TableDataSet so that every record inserted or updated during a save is immediately refreshed from the DBMS contents.
`java.lang.String` | `tableName()` Returns the database table name with which a TableDataSet was created.
`TableDataSet` | `tableQualifier(java.lang.String str)` Sets additional SQL for the table name clause.
`void` | `updateStatus()` Updates the save status of the rows in the TableDataSet.
`TableDataSet` | `where(java.lang.String str)` Sets the WHERE clause for a TableDataSet.

Methods inherited from class weblogic.db.jdbc.DataSet
`addRecord, allRecordsRetrieved, clearRecords, close, connection, containsRecord, destroy, fetchRecords, fetchRecords, getRecord, getResultSet, initialize, lastFetchSize, maxColumnWidths, readExternal, releaseRecords, removeRecord, reset, size, toString, writeExternal`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### keydefval

    protected KeyDef keydefval

Constructor Detail

### TableDataSet

    public TableDataSet(java.sql.Connection conn,
                        java.lang.String tablename)
                 throws java.sql.SQLException,
                        DataSetException

  Constructs a TableDataSet from the specified table.

  Parameters:
    `conn` - Connection object
    `tablename` - Table name in the database
  Throws:
    DataSetException - if there is a data error
    java.sql.SQLException - if there is a SQL error

### TableDataSet

    public TableDataSet(java.sql.Connection conn,
                        java.lang.String tablename,
                        java.lang.String attributes)
                 throws java.sql.SQLException,
                        DataSetException

  Constructs a TableDataSet from the specified table, limited to the specified set of attributes (columns).

  Parameters:
    `conn` - Connection object
    `tablename` - Table name in the database
    `attributes` - Attributes of the table to use
  Throws:
    DataSetException - if there is a data error
    java.sql.SQLException - if there is a SQL error

### TableDataSet

    public TableDataSet(java.sql.Connection conn,
                        java.lang.String tablename,
                        KeyDef key)
                 throws DataSetException,
                        java.sql.SQLException

  Constructs a TableDataSet from the specified table, and sets its KeyDef, which is used to specify a unique key for updates and deletes.

  Parameters:
    `conn` - Connection object
    `tablename` - Table name in the database
    `key` - KeyDef object
  Throws:
    DataSetException - if there is a data error
    java.sql.SQLException - if there is a SQL error

### TableDataSet

    public TableDataSet(java.sql.Connection conn,
                        java.lang.String tablename,
                        java.lang.String attributes,
                        KeyDef key)
                 throws DataSetException,
                        java.sql.SQLException

  Constructs a TableDataSet from the specified table, limited to the specified set of attributes (columns). The KeyDef is used to specify a unique key for updates and deletes.

  Parameters:
    `conn` - Connection object
    `tablename` - Table name in the database
    `attributes` - Attributes of the table to use
    `key` - KeyDef object
  Throws:
    DataSetException - if there is a data error
    java.sql.SQLException - if there is a SQL error

### TableDataSet

    public TableDataSet(java.sql.Connection conn,
                        Schema schema,
                        KeyDef key)
                 throws DataSetException,
                        java.sql.SQLException

  Constructs a TableDataSet from the specified Schema and KeyDef. The KeyDef is used to specify a unique key for updates and deletes.

  Parameters:
    `conn` - Connection object
    `schema` - Schema from previous TDS
    `key` - KeyDef object
  Throws:
    DataSetException - if there is a data error
    java.sql.SQLException - if there is a SQL error

### TableDataSet

    public TableDataSet()

  Private - used for serialization

Method Detail

### fetchRecords

    public DataSet fetchRecords(int start,
                                int maxrecs)
                         throws java.sql.SQLException,
                                DataSetException

  Fetches at most the specified number of records starting at the specified record.

  Parameters:
    `start` - Position of first record to fetch
    `maxrecs` - Maximum number of records to fetch
  Throws:
    DataSetException - if there is a problem with the DataSet
    java.sql.SQLException - if the records cannot be retrieved
  Overrides:
    fetchRecords in class DataSet

### setRefreshOnSave

    public void setRefreshOnSave(boolean yesOrNo)

  Sets TableDataSet so that every record inserted or updated during a save is immediately refreshed from the DBMS contents. This is useful where columns are either automatically created by the DBMS, such as a Microsoft SQL Serer identity column, or when triggers may alter the the row as a side effect of the insert or update.

  Parameters:
    `yesOrNo` - True to enable refresh on save

### refreshOnSave

    public boolean refreshOnSave()

  Returns the current setting of setRefreshOnSave(), which is False by default.

### updateStatus

    public void updateStatus()
                      throws java.sql.SQLException,
                             DataSetException

  Updates the save status of the rows in the TableDataSet. Call this method after committing a transaction that includes rows updated by a call to saveWithoutStatusUpdate().

  Throws:
    DataSetException - if there is a data error
    java.sql.SQLException - if there is a SQL error

### refresh

    public void refresh(java.sql.Connection conn)
                 throws java.sql.SQLException,
                        DataSetException

  Refreshes all of the records in the TableDataSet from the DBMS.

  Parameters:
    `conn` - Connection object
  Throws:
    java.sql.SQLException - if there is a SQL error
    DataSetException - if there is a data error

### keydef

    public KeyDef keydef()

  Returns the KeyDef for a TableDataSet. The KeyDef is used to specify a unique key for updates and deletes.

  Returns:
    KeyDef object

### tableName

    public java.lang.String tableName()

  Returns the database table name with which a TableDataSet was created.

  Returns:
    Name of the table

### attributes

    public java.lang.String attributes()

  Returns the set of attributes with which a TableDataSet was constructed. A TableDataSet can be constructed with a subset of the attributes of the DBMS table.

  Returns:
    Attribute names

### schema

    public Schema schema()

  Returns the Schema of a TableDataSet.

  Returns:
    Schema object
  Overrides:
    schema in class DataSet

### save

    public int save()
             throws java.sql.SQLException,
                    DataSetException

  Saves changes made in a TableDataSet to a database using the default Connection.

  Returns:
    Number of records updated, deleted, or inserted
  Throws:
    DataSetException - if there is an error in the DataSet
    java.sql.SQLException - if there is a SQL error

### save

    public int save(boolean intransaction)
             throws java.sql.SQLException,
                    DataSetException

  Saves changes made in a TableDataSet to a database using the default Connection.

  Parameters:
    `intransaction` - True if in a transaction
  Returns:
    Number of records updated, deleted, or inserted
  Throws:
    DataSetException - if there is an error in the DataSet
    java.sql.SQLException - if there is a SQL error

### save

    public int save(java.sql.Connection conn,
                    boolean intransaction)
             throws java.sql.SQLException,
                    DataSetException

  Saves changes made in a TableDataSet to a database using the specified Connection. Set intransaction to True if you call this method within a transaction. The method does not update status in the TableDataSet status until it has updated all of the corresponding rows in the database. If a rollback occurs, then the TableDataSet status matches the database.

  Set intransaction to False (the default) if you call this method without starting a transaction. In this case, the method updates a row in the database, then updates the status of the corresponding row in the TableDataSet so that the database status matches the TableDataSet status.

  Parameters:
    `conn` - Connection object
    `intransaction` - True if in a transaction
  Returns:
    Number of records updated, deleted, or inserted
  Throws:
    DataSetException - if there is an error in the DataSet
    java.sql.SQLException - if there is a SQL error

### saveWithoutStatusUpdate

    public int saveWithoutStatusUpdate(java.sql.Connection conn)
                                throws java.sql.SQLException,
                                       DataSetException

### removeDeletedRecords

    public void removeDeletedRecords()
                              throws DataSetException

  Removes deleted records from the TableDataSet. These records have already been deleted from the database, but remain in the TableDataSet marked as Zombie records. Zombie records remain after deletion to avoid corrupting record indexes in application programs.

  Throws:
    DataSetException - if there is an error removing deleted records

### getSelectString

    public java.lang.String getSelectString()

  Returns the SQL SELECT string of the query that was used to populate a TableDataSet.

  Returns:
    SQL select string
  Overrides:
    getSelectString in class DataSet

### where

    public TableDataSet where(java.lang.String str)

  Sets the WHERE clause for a TableDataSet.

  Parameters:
    `str` - Specifies the WHERE clause
  Returns:
    TableDataSet object

### order

    public TableDataSet order(java.lang.String str)

  Sets the ORDER BY clause for a TableDataSet.

  Parameters:
    `str` - Specifies the ORDER BY clause
  Returns:
    TableDataSet Object

### orderstr

    protected java.lang.String orderstr()

### other

    public TableDataSet other(java.lang.String str)

  Sets additional SQL clause for a TableDataSet. The string appears after the ORDER clause. Oracle users would set this to "FOR UPDATE" to achieve record locking.

  Parameters:
    `str` - Specifies the ORDER BY clause
  Returns:
    TableDataSet Object

### tableQualifier

    public TableDataSet tableQualifier(java.lang.String str)

  Sets additional SQL for the table name clause. The string appears after the table name. Sybase users would set this to "HOLDLOCK" to acheive repeatable reads.

  Parameters:
    `str` - Specifies the table clause qualifier
  Returns:
    TableDataSet Object

### debugInfo

    public java.lang.String debugInfo()

  Returns information about a TableDataSet object for debugging purposes.

  Returns:
    Table name, WHERE clause, ORDER BY clause, and number of records

### selectStmt

    public SelectStmt selectStmt()

  Returns the SelectStmt object associated with a TableDataSet. This allows QBE (query-by-example) functionality for a TableDataSet.

  Returns:
    SelectStmt object
  See Also:
    `SelectStmt`

### resultSet

    public java.sql.ResultSet resultSet()
                                 throws java.sql.SQLException,
                                        DataSetException

  Returns the JDBC ResultSet associated with a TableDataSet.

  Returns:
    JDBC ResultSet
  Throws:
    DataSetException - if there is a data error
    java.sql.SQLException - if there is a SQL error
  Overrides:
    resultSet in class DataSet

### setOptimisticLockingColumn

    public void setOptimisticLockingColumn(java.lang.String colName)
                                    throws DataSetException

  Identifies the table column used for optimistic locking.

  Parameters:
    `colName` - The column name that is used for optimistic locking.
  Throws:
    DataSetException - if there is a data error

### optimisticLockingCol

    public java.lang.String optimisticLockingCol()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Documentation is available at http://e-docs.bea.com/wls/docs70
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 BEA Systems, Inc. All Rights Reserved.
WebLogic Server 7.0 API Reference