BEA Systems, Inc.
WebLogic Server 6.1 API Reference

weblogic.db.jdbc
Class Record

java.lang.Object
  |
  +--weblogic.db.jdbc.Record
Direct Known Subclasses:
EventfulRecord
public class Record
extends java.lang.Object
implements java.io.Serializable

A Record object is a collection of Value objects. A row returned from a database query maps to a Record object.

A Record object is contained in a DataSet, which is a collection of Records. The Schema object of the parent DataSet describes the name, data type, size, and order of each field in a Record.

For 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 © 2001 BEA Systems, Inc. All Rights Reserved.
See Also:
DataSet, Value, Serialized Form

Field Summary
protected  boolean[] isclean
           
protected  int numcols
           
protected  DataSet parentdataset
           
protected  Value[] values
           
 
Constructor Summary
Record()
          Private constructor used for serialization - do not use.
Record(DataSet ds)
          Record constructor used when adding records to an existing DataSet object.
 
Method Summary
 java.lang.String asFormattedString(java.lang.String valueseparator, int[] maxwidths)
          Returns the value of each column in a Record as a formatted String.
 DataSet dataset()
          Returns the parent DataSet of a Record.
 java.lang.String getRefreshQueryString()
           
 java.lang.String getSaveString()
          Returns the SQL String used to save a Record to the database.
 Value getValue(int pos)
          Returns the Value at the specified 1-based index position in a Record.
 Value getValue(java.lang.String colname)
          Returns the Value for the specified column name in a Record.
 boolean isAZombie()
          Determines whether a Record is a zombie.
protected  void markAsDelete()
           
protected  void markAsInsert()
           
protected  void markAsUpdate()
           
protected  void markAsZombie()
           
 void markForInsert()
           
 void markForUpdate()
           
 void markRecordClean()
           
 Record markToBeDeleted()
          Marks a Record object for deletion.
 void markValueClean(int pos)
           
 void markValueClean(java.lang.String colname)
           
 void markValueDirty(int pos)
           
 void markValueDirty(java.lang.String colname)
           
 boolean needsToBeSaved()
          Determines whether a Record needs to be saved.
 boolean recordIsClean()
          Determines whether any Value in a Record needs to be saved to the database.
 void refresh(java.sql.Connection conn)
          Reloads the data for the row from the DBMS.
 int save()
          Saves a Record to the database using the default Connection.
 int save(java.sql.Connection conn)
          Saves a Record to the database using the specified Connection.
 int saveWithoutStatusUpdate(java.sql.Connection conn)
          Saves a Record to the database using the specified Connection but without updating the status.
 Schema schema()
          Returns the Schema associated with a Record.
 Record setValue(int pos, java.math.BigDecimal val)
          Sets the Value at the specified index position to a java.math.BigDecimal.
 Record setValue(int pos, boolean val)
          Sets the Value at the specified index position to a boolean.
 Record setValue(int pos, byte[] val)
          Sets the Value at the specified index position to a byte[].
 Record setValue(int pos, java.util.Date val)
          Sets the Value at the specified index position to a java.util.Date.
 Record setValue(int pos, java.sql.Date val)
          Sets the Value at the specified index position to java.sql.Date.
 Record setValue(int pos, double val)
          Sets the Value at the specified index position to a double.
 Record setValue(int pos, float val)
          Sets the Value at the specified index position to a float.
 Record setValue(int pos, int val)
          Sets the Value at the specified index position to a int.
 Record setValue(int pos, long val)
          Sets the Value at the specified index position to a long.
 Record setValue(int pos, java.lang.String val)
          Sets the Value at the specified index position to a String.
 Record setValue(int pos, java.sql.Time val)
          Sets the Value at the specified index position to java.sql.Time.
 Record setValue(int pos, java.sql.Timestamp val)
          Sets the Value at the specified index position to java.sql.Timestamp.
 Record setValue(int pos, Value val)
          Sets the Value at the specified index position to a Value.
 Record setValue(java.lang.String colname, java.math.BigDecimal val)
          Sets the Value at the specified column name to a BigDecimal.
 Record setValue(java.lang.String colname, boolean val)
          Sets the Value at the specified column name to a boolean.
 Record setValue(java.lang.String colname, byte[] val)
          Sets the Value at the specified column name to a byte[].
 Record setValue(java.lang.String colname, java.sql.Date val)
          Sets the Value at the specified column name to java.sql.Date.
 Record setValue(java.lang.String colname, java.util.Date dateval)
          Sets the Value at the specified column name to java.util.Date.
 Record setValue(java.lang.String colname, double val)
          Sets the Value at the specified column name to a double.
 Record setValue(java.lang.String colname, float val)
          Sets the Value at the specified column name to a float.
 Record setValue(java.lang.String colname, int val)
          Sets the Value at the specified column name to a int.
 Record setValue(java.lang.String colname, long val)
          Sets the Value at the specified column name to a long.
 Record setValue(java.lang.String colname, java.lang.String val)
          Sets the Value at the specified column name to a String.
 Record setValue(java.lang.String colname, java.sql.Time val)
          Sets the Value at the specified column name to java.sql.Time.
 Record setValue(java.lang.String colname, java.sql.Timestamp val)
          Sets the Value at the specified column name to java.sql.Timestamp.
 Record setValue(java.lang.String colname, Value val)
          Sets the Value at the specified column name to a Value.
 Record setValueNull(int pos)
          Sets the Value at the specified index position to NULL.
 Record setValueNull(java.lang.String colname)
          Sets the Value at the specified column name to NULL.
 int size()
          Returns the number of columns in a Record.
 boolean toBeSavedWithDelete()
          Determines whether a Record will be saved with an SQL DELETE statement.
 boolean toBeSavedWithInsert()
          Determines whether a Record will be saved with an SQL INSERT statement.
 boolean toBeSavedWithUpdate()
          Determines whether a Record will be saved with an SQL UPDATE statement.
 java.lang.String toString()
          Returns a string representation of a Record.
 Record unmarkToBeDeleted()
          Unmarks a Record that has been marked for deletion.
 void updateStatus()
          Updates the save status of the record after a saveWithoutStatusUpdate().
 boolean valueIsClean(int pos)
          Determines whether a Value at a particular index in a Record needs to be saved to the database.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

parentdataset

protected DataSet parentdataset

values

protected Value[] values

isclean

protected boolean[] isclean

numcols

protected int numcols
Constructor Detail

Record

public Record()
Private constructor used for serialization - do not use.

Record

public Record(DataSet ds)
       throws DataSetException,
              java.sql.SQLException
Record constructor used when adding records to an existing DataSet object. This is the equivalent of calling DataSet.addRecord().

Parameters:
ds - DataSet object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if you try to create the record before calling fetchRecords() on the DataSet object to get its Schema
See Also:
DataSet.addRecord()
Method Detail

refresh

public void refresh(java.sql.Connection conn)
             throws DataSetException,
                    java.sql.SQLException
Reloads the data for the row from the DBMS. All fields will be updated to mach the DBMS and marked clean. If the record has no representation in the DBMS, an exception will be thrown.

Throws:
DataSetException - if there is an error
java.sql.SQLException - if there is an error

getRefreshQueryString

public java.lang.String getRefreshQueryString()
                                       throws DataSetException,
                                              java.sql.SQLException

needsToBeSaved

public boolean needsToBeSaved()
Determines whether a Record needs to be saved.

Returns:
True if Record is updatable and needs to be saved

toBeSavedWithUpdate

public boolean toBeSavedWithUpdate()
Determines whether a Record will be saved with an SQL UPDATE statement.

Returns:
True if UPDATE will be performed

toBeSavedWithDelete

public boolean toBeSavedWithDelete()
Determines whether a Record will be saved with an SQL DELETE statement.

Returns:
True if DELETE will be performed

toBeSavedWithInsert

public boolean toBeSavedWithInsert()
Determines whether a Record will be saved with an SQL INSERT statement.

Returns:
True if INSERT will be performed

isAZombie

public boolean isAZombie()
Determines whether a Record is a zombie. Zombie status indicates that the Record has been deleted but not yet removed from the DataSet.

Returns:
True if the Record is a zombie

unmarkToBeDeleted

public Record unmarkToBeDeleted()
Unmarks a Record that has been marked for deletion.

Returns:
Record object
See Also:
markToBeDeleted()

markToBeDeleted

public Record markToBeDeleted()
                       throws DataSetException
Marks a Record object for deletion. The next time Record.save() or TableDataSet.save() is invoked on this Record, a DELETE statement will be sent to the database corresponding to the key of this Record.

Returns:
Record object
Throws:
DataSetException - if the record is contained in a QueryDataSet
See Also:
unmarkToBeDeleted()

dataset

public DataSet dataset()
Returns the parent DataSet of a Record.

Returns:
DataSet object

size

public int size()
Returns the number of columns in a Record.

Returns:
Number of columns

schema

public Schema schema()
              throws java.sql.SQLException,
                     DataSetException
Returns the Schema associated with a Record.

Returns:
Schema object
Throws:
DataSetException - if there is an error with the DataSet
java.sql.SQLException - if there is a SQL error

toString

public java.lang.String toString()
Returns a string representation of a Record.

Returns:
String object after the format "Column name : value"
Overrides:
toString in class java.lang.Object

asFormattedString

public java.lang.String asFormattedString(java.lang.String valueseparator,
                                          int[] maxwidths)
                                   throws DataSetException
Returns the value of each column in a Record as a formatted String.

Parameters:
valueseparator - Delimiter character
maxwidths - Array of ints that represent the widths of the columns in the Record object
Returns:
String representation of the widths of the columns in the Record object
Throws:
DataSetException - if there is an internal IO error

getValue

public Value getValue(int pos)
               throws DataSetException
Returns the Value at the specified 1-based index position in a Record.

Parameters:
pos - 1-based ndex position of a column in the Record object
Returns:
Value object
Throws:
DataSetException - if column index is invalid

getValue

public Value getValue(java.lang.String colname)
               throws java.sql.SQLException,
                      DataSetException
Returns the Value for the specified column name in a Record.

Parameters:
colname - Name of a column
Returns:
Value object
Throws:
java.sql.SQLException - if there is an error
DataSetException - if the column name is invalid

markRecordClean

public void markRecordClean()

setValue

public Record setValue(int pos,
                       Value val)
                throws DataSetException
Sets the Value at the specified index position to a Value.

Parameters:
pos - 1-based index into the Record object
val - Value value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       Value val)
                throws java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to a Value.

Parameters:
colname - Column name in the Record object
val - Value value
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       java.util.Date val)
                throws DataSetException
Sets the Value at the specified index position to a java.util.Date.

Parameters:
pos - 1-based index into the Record object
val - java.util.Date value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       boolean val)
                throws DataSetException
Sets the Value at the specified index position to a boolean.

Parameters:
pos - 1-based index into the Record object
val - boolean value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       java.lang.String val)
                throws DataSetException
Sets the Value at the specified index position to a String.

Parameters:
pos - 1-based index into the Record object
val - String value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       int val)
                throws DataSetException
Sets the Value at the specified index position to a int.

Parameters:
pos - 1-based index into the Record object
val - Int value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       long val)
                throws DataSetException
Sets the Value at the specified index position to a long.

Parameters:
pos - 1-based index into the Record object
val - long value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       float val)
                throws DataSetException
Sets the Value at the specified index position to a float.

Parameters:
pos - 1-based index into the Record object
val - Float value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       double val)
                throws DataSetException
Sets the Value at the specified index position to a double.

Parameters:
pos - 1-based index into the Record object
val - Double value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       java.sql.Time val)
                throws DataSetException,
                       InvalidDateException
Sets the Value at the specified index position to java.sql.Time.

Parameters:
pos - 1-based index into the Record object
val - java.sql.Time value
Returns:
Record object
Throws:
DataSetException - if the set operation fails
InvalidDateException - if a date earlier than 1970 is encountered

setValue

public Record setValue(int pos,
                       java.sql.Date val)
                throws DataSetException,
                       InvalidDateException
Sets the Value at the specified index position to java.sql.Date.

Parameters:
pos - 1-based index into the Record object
val - java.sql.Date value
Returns:
Record object
Throws:
DataSetException - if the set operation fails
InvalidDateException - if a date earlier than 1970 is encountered

setValue

public Record setValue(int pos,
                       java.sql.Timestamp val)
                throws DataSetException,
                       InvalidDateException
Sets the Value at the specified index position to java.sql.Timestamp.

Parameters:
pos - 1-based index into the Record object
val - java.sql.Timestamp value
Returns:
Record object
Throws:
DataSetException - if the set operation fails
InvalidDateException - if a date earlier than 1970 is encountered

setValue

public Record setValue(int pos,
                       byte[] val)
                throws DataSetException
Sets the Value at the specified index position to a byte[].

Parameters:
pos - 1-based index into the Record object
val - byte[] value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValue

public Record setValue(int pos,
                       java.math.BigDecimal val)
                throws DataSetException
Sets the Value at the specified index position to a java.math.BigDecimal.

Parameters:
pos - 1-based index into the Record object
val - java.math.BigDecimal value
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValueNull

public Record setValueNull(int pos)
                    throws DataSetException
Sets the Value at the specified index position to NULL.

Parameters:
pos - 1-based index into the Record object
Returns:
Record object
Throws:
DataSetException - if the set operation fails

setValueNull

public Record setValueNull(java.lang.String colname)
                    throws java.sql.SQLException,
                           DataSetException
Sets the Value at the specified column name to NULL.

Parameters:
colname - Column name in the Record object
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       boolean val)
                throws java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to a boolean.

Parameters:
colname - Column name in the Record object
val - boolean value
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       java.lang.String val)
                throws java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to a String.

Parameters:
colname - Column name in the Record object
val - String value
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       int val)
                throws java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to a int.

Parameters:
colname - Column name in the Record object
val - Int value
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       long val)
                throws java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to a long.

Parameters:
colname - Column name in the Record object
val - long value
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       float val)
                throws java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to a float.

Parameters:
colname - Column name in the Record object
val - Float value
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       double val)
                throws java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to a double.

Parameters:
colname - Column name in the Record object
val - Double value
Returns:
Record object
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       java.sql.Time val)
                throws InvalidDateException,
                       java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to java.sql.Time.

Parameters:
colname - Column name in the Record object
val - java.sql.Time value
Returns:
Record object
Throws:
InvalidDateException - if a date earlier than 1970 is encountered
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       java.sql.Date val)
                throws InvalidDateException,
                       java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to java.sql.Date.

Parameters:
colname - Column name in the Record object
val - java.sql.Date value
Returns:
Record object
Throws:
InvalidDateException - if a date earlier than 1970 is encountered
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       java.sql.Timestamp val)
                throws InvalidDateException,
                       java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to java.sql.Timestamp.

Parameters:
colname - Column name in the Record object
val - java.sql.Timestamp value
Returns:
Record object
Throws:
InvalidDateException - if a date earlier than 1970 is encountered
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       java.util.Date dateval)
                throws InvalidDateException,
                       java.sql.SQLException,
                       DataSetException
Sets the Value at the specified column name to java.util.Date.

Parameters:
colname - Column name in the Record object
val - java.util.Date value
Returns:
Record object
Throws:
InvalidDateException - if a date earlier than 1970 is encountered
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

setValue

public Record setValue(java.lang.String colname,
                       byte[] val)
                throws DataSetException,
                       java.sql.SQLException
Sets the Value at the specified column name to a byte[].

Parameters:
colname - Column name in the Record object
val - byte[] value
Returns:
Record object
Throws:
DataSetException - if the set operation fails
java.sql.SQLException - if there is a SQL error

setValue

public Record setValue(java.lang.String colname,
                       java.math.BigDecimal val)
                throws DataSetException,
                       java.sql.SQLException
Sets the Value at the specified column name to a BigDecimal.

Parameters:
colname - Column name in the Record object
val - BigDecimal value
Returns:
Record object
Throws:
DataSetException - if the set operation fails
java.sql.SQLException - if there is a SQL error

markValueDirty

public void markValueDirty(int pos)
                    throws DataSetException

markValueDirty

public void markValueDirty(java.lang.String colname)
                    throws java.sql.SQLException,
                           DataSetException

valueIsClean

public boolean valueIsClean(int pos)
Determines whether a Value at a particular index in a Record needs to be saved to the database.

Parameters:
pos - 1-based index into the Record object
Returns:
False if there are unsaved changes to a Value in the Record object

recordIsClean

public boolean recordIsClean()
Determines whether any Value in a Record needs to be saved to the database.

Returns:
False if there are unsaved changes to any Value in the Record object

getSaveString

public java.lang.String getSaveString()
                               throws java.sql.SQLException,
                                      DataSetException
Returns the SQL String used to save a Record to the database. The string may be an UPDATE, DELETE, or INSERT statement.

Returns:
SQL String
Throws:
java.sql.SQLException - if there is a SQL error
DataSetException - if the set operation fails

save

public int save()
         throws DataSetException,
                java.sql.SQLException
Saves a Record to the database using the default Connection.

Returns:
1 if the record was changed in the database
Throws:
DataSetException - if no saves are allowed
java.sql.SQLException - if there is a SQL error

save

public int save(java.sql.Connection conn)
         throws DataSetException,
                java.sql.SQLException
Saves a Record to the database using the specified Connection.

Parameters:
conn - Connection object
Returns:
1 if the record was changed in the database
Throws:
DataSetException - if no saves are allowed
java.sql.SQLException - if there is a SQL error

saveWithoutStatusUpdate

public int saveWithoutStatusUpdate(java.sql.Connection conn)
                            throws DataSetException,
                                   java.sql.SQLException
Saves a Record to the database using the specified Connection but without updating the status.

Parameters:
conn - Connection object
Returns:
1 if the record was changed in the database
Throws:
DataSetException - if no saves are allowed
java.sql.SQLException - if there is a SQL error

markValueClean

public void markValueClean(int pos)

markValueClean

public void markValueClean(java.lang.String colname)
                    throws java.sql.SQLException,
                           DataSetException

markAsUpdate

protected void markAsUpdate()

markAsInsert

protected void markAsInsert()

markAsDelete

protected void markAsDelete()

markAsZombie

protected void markAsZombie()

markForInsert

public void markForInsert()

markForUpdate

public void markForUpdate()

updateStatus

public void updateStatus()
                  throws java.sql.SQLException,
                         DataSetException
Updates the save status of the record after a saveWithoutStatusUpdate(). This method should be used when a transaction is either ready to commit, or directly after it is committed.

Throws:
DataSetException - if no saves are allowed
java.sql.SQLException - if there is a SQL error
Documentation is available at
http://download.oracle.com/docs/cd/E13222_01/wls/docs61
WebLogic classes and methods that do not appear in this reference are not public and are not supported.