BEA Systems, Inc.

WebLogic Server 5.1.0 API Reference

weblogic.db.jdbc
Class TableDataSet

java.lang.Object
  |
  +--weblogic.db.jdbc.DataSet
        |
        +--weblogic.db.jdbc.TableDataSet
Direct Known Subclasses:
EventfulTableDataSet

public 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.
Copyright © 2000 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, readObject, releaseRecords, removeRecord, reset, size, toString, writeObject
 
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()

Documentation is available at
http://www.weblogic.com/docs51