org.apache.empire.db
Class DBRecord

java.lang.Object
  extended by org.apache.empire.commons.ErrorObject
      extended by org.apache.empire.db.DBObject
          extended by org.apache.empire.db.DBRecordData
              extended by org.apache.empire.db.DBRecord
All Implemented Interfaces:
java.lang.Cloneable, ErrorInfo, Record, RecordData

public class DBRecord
extends DBRecordData
implements Record, java.lang.Cloneable

This class handles one record from a database table.


Field Summary
static int REC_EMTPY
           
static int REC_INVALID
           
static int REC_MODIFIED
           
static int REC_NEW
           
static int REC_VALID
           
 
Constructor Summary
DBRecord()
          Create a new DBRecord object.
 
Method Summary
 boolean addColumnDesc(org.w3c.dom.Element parent)
          This function set the field descriptions to the the XML tag.
 boolean addRowValues(org.w3c.dom.Element parent)
          Add the values of this record to the specified XML Element object.
 DBRecord clone()
           
 void close()
          Closes the record by releasing all resources and resetting the record's state to invalid.
 boolean create(DBRowSet table)
          Creates a new record for the given table.
 boolean create(DBRowSet table, java.sql.Connection conn)
          Creates a new record for the given table.
 boolean delete(java.sql.Connection conn)
          This helper function calls the DBRowset.deleteRecord method to delete the record.
 int fillMissingDefaults(java.sql.Connection conn)
          Initialisieren the field with the values (NO_VALUE) of the vector 'field'.
 Column getColumn(int index)
          Implements the Record Interface getColumn method.
 ColumnExpr getColumnExpr(int index)
          Returns a DBColumnExpr object by a specified index value.
 DBDatabase getDatabase()
          Returns the current DBDatabase object.
 DBColumn getDBColumn(int index)
          Returns the DBColumn for the field at the given index.
 int getFieldCount()
          Returns the number of the columns.
 int getFieldIndex(ColumnExpr column)
          Returns the index value by a specified DBColumnExpr object.
 int getFieldIndex(java.lang.String column)
          Returns the index value by a specified column name.
 Options getFieldOptions(Column column)
          Gets the possbile Options for a field in the context of the current record.
 Options getFieldOptions(DBColumn column)
          Gets the possbile Options for a field in the context of the current record.
 Column[] getKeyColumns()
          returns an array of key columns which uniquely identify the record.
 java.lang.Object[] getKeyValues()
          Returns the array of primary key columns.
 DBRowSet getRowSet()
          Returns the DBRowSet object.
 java.lang.Object getRowSetData()
          Returns the DBRowSet object.
 int getState()
          Returns the record state.
 java.lang.Object getValue(int index)
          Returns the value for the given column or null if either the index is out of range or the value is not valid (see isValueValid(int))
 org.w3c.dom.Document getXmlDocument()
          Returns a XML document with the field descriptiona an values of this record.
 boolean init(DBRowSet table, java.lang.Object[] keyValues, boolean insert)
          Initializes this record object by attaching it to a rowset, setting its primary key values and setting the record state.
 boolean initNew(DBRowSet table)
          Deprecated. use create(DBRowSet)
 boolean initNew(DBRowSet table, java.sql.Connection conn)
          Deprecated. use create(DBRowSet, Connection)
 boolean isFieldReadOnly(Column column)
          returns whether a field is read only or not
 boolean isFieldReadOnly(DBColumn column)
          returns whether a field is read only or not
 boolean isFieldVisible(Column column)
          returns whether a field is read only or not
 boolean isFieldVisible(DBColumn column)
          returns whether a field is visible to the client or not May be overridden to implement context specific logic.
 boolean isModified()
          Returns true if the record is modified.
 boolean isNew()
          Returns true if this record is a new record.
 boolean isValid()
          Returns true if the record is valid.
 boolean isValueValid(int index)
          Returns whether a field value is provided i.e. the value is not DBRowSet.NO_VALUE
This function is only useful in cases where records are partically loaded.
 void modifyValue(int i, java.lang.Object value)
          Modifies a column value bypassing all checks made by setValue.
 boolean read(DBRowSet table, java.lang.Object[] keys, java.sql.Connection conn)
          Loads a record from the database identified by it's primary key.
 boolean read(DBRowSet table, java.lang.Object id, java.sql.Connection conn)
          Loads a record from the database identified by it's primary key.
 boolean setBeanValues(java.lang.Object bean)
          Sets record values from the suppied java bean.
 boolean setBeanValues(java.lang.Object bean, java.util.Collection<Column> ignoreList)
          Sets record values from the suppied java bean.
 void setModified(DBColumn column, boolean isModified)
          Sets the modified state of a column.
 boolean setValue(Column column, java.lang.Object value)
          Sets the value of the column in the record.
 boolean setValue(int i, java.lang.Object value)
          Sets the value of the column in the record.
 boolean update(java.sql.Connection conn)
          Updates the record and saves all changes in the database.
 boolean wasModified(Column column)
          Returns true if the field was modified.
 boolean wasModified(int index)
          Returns true if the field was modified.
 
Methods inherited from class org.apache.empire.db.DBRecordData
getBeanProperties, getBeanProperties, getBoolean, getBoolean, getDateTime, getDateTime, getDouble, getDouble, getInt, getInt, getLong, getLong, getString, getString, getValue, isNull, isNull
 
Methods inherited from class org.apache.empire.commons.ErrorObject
clearError, getErrorMessage, getErrorParams, getErrorSource, getErrorType, getMessage, hasError, isExceptionsEnabled, setExceptionsEnabled
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.empire.data.RecordData
getBeanProperties, getBeanProperties, getValue, isNull, isNull
 

Field Detail

REC_INVALID

public static final int REC_INVALID
See Also:
Constant Field Values

REC_EMTPY

public static final int REC_EMTPY
See Also:
Constant Field Values

REC_VALID

public static final int REC_VALID
See Also:
Constant Field Values

REC_MODIFIED

public static final int REC_MODIFIED
See Also:
Constant Field Values

REC_NEW

public static final int REC_NEW
See Also:
Constant Field Values
Constructor Detail

DBRecord

public DBRecord()
Create a new DBRecord object.
The record is not attachted to a RowSet and the record's state is intitially set to REC_INVALID. Please derive your own Objects from this class.

Method Detail

close

public void close()
Closes the record by releasing all resources and resetting the record's state to invalid.

Specified by:
close in class DBRecordData

clone

public DBRecord clone()
Overrides:
clone in class java.lang.Object
See Also:
Object.clone()

getDatabase

public DBDatabase getDatabase()
Returns the current DBDatabase object.

Specified by:
getDatabase in class DBObject
Returns:
the current DBDatabase object

getRowSet

public DBRowSet getRowSet()
Returns the DBRowSet object.

Returns:
the DBRowSet object

getRowSetData

public java.lang.Object getRowSetData()
Returns the DBRowSet object.

Returns:
the DBRowSet object

getState

public int getState()
Returns the record state.

Returns:
the record state

isValid

public boolean isValid()
Returns true if the record is valid.

Specified by:
isValid in interface Record
Returns:
true if the record is valid

isModified

public boolean isModified()
Returns true if the record is modified.

Specified by:
isModified in interface Record
Returns:
true if the record is modified

isNew

public boolean isNew()
Returns true if this record is a new record.

Specified by:
isNew in interface Record
Returns:
true if this record is a new record

getFieldCount

public int getFieldCount()
Returns the number of the columns.

Specified by:
getFieldCount in interface RecordData
Specified by:
getFieldCount in class DBRecordData
Returns:
the number of the columns

getFieldIndex

public int getFieldIndex(ColumnExpr column)
Returns the index value by a specified DBColumnExpr object.

Specified by:
getFieldIndex in interface RecordData
Specified by:
getFieldIndex in class DBRecordData
Parameters:
column - the column for which to return the index
Returns:
the index value

getFieldIndex

public int getFieldIndex(java.lang.String column)
Returns the index value by a specified column name.

Specified by:
getFieldIndex in interface RecordData
Specified by:
getFieldIndex in class DBRecordData
Parameters:
column - the name of the column for which to return the index
Returns:
the index value

getDBColumn

public DBColumn getDBColumn(int index)
Returns the DBColumn for the field at the given index.

Returns:
the index value

getColumn

public final Column getColumn(int index)
Implements the Record Interface getColumn method.
Internally calls getDBColumn()

Specified by:
getColumn in interface Record
Parameters:
index - index of a requested column
Returns:
the Column at the specified index

getColumnExpr

public final ColumnExpr getColumnExpr(int index)
Returns a DBColumnExpr object by a specified index value.

Specified by:
getColumnExpr in interface RecordData
Specified by:
getColumnExpr in class DBRecordData
Parameters:
index - field index of the column expression
Returns:
the index value

wasModified

public boolean wasModified(int index)
Returns true if the field was modified.

Returns:
true if the field was modified

wasModified

public final boolean wasModified(Column column)
Returns true if the field was modified.

Specified by:
wasModified in interface Record
Parameters:
column - the requested column
Returns:
true if the field was modified

setModified

public void setModified(DBColumn column,
                        boolean isModified)
Sets the modified state of a column.
This will force the field to be updated in the database.


getKeyColumns

public Column[] getKeyColumns()
returns an array of key columns which uniquely identify the record.

Specified by:
getKeyColumns in interface Record
Returns:
the array of key columns if any

getKeyValues

public java.lang.Object[] getKeyValues()
Returns the array of primary key columns.

Returns:
the array of primary key columns

getValue

public java.lang.Object getValue(int index)
Returns the value for the given column or null if either the index is out of range or the value is not valid (see isValueValid(int))

Specified by:
getValue in interface RecordData
Specified by:
getValue in class DBRecordData
Parameters:
index - the field index for which to return the value
Returns:
the index value

isValueValid

public boolean isValueValid(int index)
Returns whether a field value is provided i.e. the value is not DBRowSet.NO_VALUE
This function is only useful in cases where records are partically loaded.

Returns:
true if a valid value is supplied for the given field or false if value is ObjectUtils.NO_VALUE

getFieldOptions

public Options getFieldOptions(DBColumn column)
Gets the possbile Options for a field in the context of the current record.


getFieldOptions

public final Options getFieldOptions(Column column)
Gets the possbile Options for a field in the context of the current record.
Same as getFieldOptions(DBColumn)

Specified by:
getFieldOptions in interface Record
Parameters:
column - the column to check for visibility
Returns:
the Option

modifyValue

public void modifyValue(int i,
                        java.lang.Object value)
Modifies a column value bypassing all checks made by setValue. Use this to explicitly set invalid values i.e. for temporary storage.

Parameters:
i - index of the column
value - the column value

setValue

public boolean setValue(int i,
                        java.lang.Object value)
Sets the value of the column in the record. The functions checks if the column and the value are valid and whether the value has changed.

Specified by:
setValue in interface Record
Parameters:
i - the index of the column
value - the value
Returns:
true if successful

setValue

public final boolean setValue(Column column,
                              java.lang.Object value)
Sets the value of the column in the record. The functions checks if the column and the value are valid and whether the value has changed.

Specified by:
setValue in interface Record
Parameters:
column - a DBColumn object
value - the value
Returns:
true if successful

isFieldReadOnly

public boolean isFieldReadOnly(DBColumn column)
returns whether a field is read only or not


isFieldReadOnly

public final boolean isFieldReadOnly(Column column)
returns whether a field is read only or not

Specified by:
isFieldReadOnly in interface Record
Parameters:
column - the requested column
Returns:
true if the field is read-only

isFieldVisible

public boolean isFieldVisible(DBColumn column)
returns whether a field is visible to the client or not

May be overridden to implement context specific logic.

Parameters:
column - the column which to check for visibility
Returns:
true if the column is visible or false if not

isFieldVisible

public final boolean isFieldVisible(Column column)
returns whether a field is read only or not

Specified by:
isFieldVisible in interface Record
Parameters:
column - the column to check for visibility
Returns:
true if the field is visible to the client

init

public boolean init(DBRowSet table,
                    java.lang.Object[] keyValues,
                    boolean insert)
Initializes this record object by attaching it to a rowset, setting its primary key values and setting the record state.
This function is useful for updating a record without prior reading.

Parameters:
table - the rowset
keyValues - a Object array, the primary key(s)
insert - if true change the state of this object to REC_NEW
Returns:
true if successful or false otherwise

initNew

@Deprecated
public final boolean initNew(DBRowSet table,
                                        java.sql.Connection conn)
Deprecated. use create(DBRowSet, Connection)


initNew

@Deprecated
public final boolean initNew(DBRowSet table)
Deprecated. use create(DBRowSet)


create

public boolean create(DBRowSet table,
                      java.sql.Connection conn)
Creates a new record for the given table.
All record fields will be filled with their default values. The record's state is set to NEW

If a connection is supplied sequence generated values will be obtained
Otherwise the sequence will be generated later.

Parameters:
table - the table for which to create a record
conn - a valid JDBC connection
Returns:
true if successful

create

public boolean create(DBRowSet table)
Creates a new record for the given table.
All record fields will be filled with their default values.
The record's state is set to NEW

Parameters:
table - the table for which to create a record
Returns:
true if successful

read

public boolean read(DBRowSet table,
                    java.lang.Object[] keys,
                    java.sql.Connection conn)
Loads a record from the database identified by it's primary key. After sucessful reading the record will be valid and all values will be accessible.

Parameters:
table - the rowset from which to read the record
keys - an array of the primary key values
conn - a valid connection to the database.
Returns:
true if the record was sucessfully loaded or false if the record was not found or an error occurred.
See Also:
DBRowSet.readRecord(DBRecord, Object[], Connection)

read

public final boolean read(DBRowSet table,
                          java.lang.Object id,
                          java.sql.Connection conn)
Loads a record from the database identified by it's primary key. After sucessful reading the record will be valid and all values will be accessible.

Parameters:
table - the rowset from which to read the record
id - the primary key of the record to load.
conn - a valid connection to the database.
Returns:
true if the record was sucessfully loaded or false if the record was not found or an error occurred.
See Also:
DBRowSet.readRecord(DBRecord, Object[], Connection)

update

public boolean update(java.sql.Connection conn)
Updates the record and saves all changes in the database.

Parameters:
conn - a valid connection to the database.
Returns:
true if successful
See Also:
DBRowSet.updateRecord(DBRecord, Connection)

delete

public boolean delete(java.sql.Connection conn)
This helper function calls the DBRowset.deleteRecord method to delete the record. WARING: There is no guarantee that it ist called Implement delete logic in the table's deleteRecord method if possible

Parameters:
conn - a valid connection to the database.
Returns:
true if successful
See Also:
DBTable.deleteRecord(Object[], Connection)

addColumnDesc

public boolean addColumnDesc(org.w3c.dom.Element parent)
This function set the field descriptions to the the XML tag.

Specified by:
addColumnDesc in class DBRecordData
Returns:
true if successful

addRowValues

public boolean addRowValues(org.w3c.dom.Element parent)
Add the values of this record to the specified XML Element object.

Specified by:
addRowValues in class DBRecordData
Parameters:
parent - the XML Element object
Returns:
true if successful

getXmlDocument

public org.w3c.dom.Document getXmlDocument()
Returns a XML document with the field descriptiona an values of this record.

Specified by:
getXmlDocument in class DBRecordData
Returns:
the new XML Document object

fillMissingDefaults

public int fillMissingDefaults(java.sql.Connection conn)
Initialisieren the field with the values (NO_VALUE) of the vector 'field'.


setBeanValues

public boolean setBeanValues(java.lang.Object bean,
                             java.util.Collection<Column> ignoreList)
Sets record values from the suppied java bean.

Specified by:
setBeanValues in interface Record
Parameters:
bean - the Java Bean from which to read the value from
ignoreList - list of column to ignore
Returns:
true if at least one value has been set sucessfully

setBeanValues

public final boolean setBeanValues(java.lang.Object bean)
Sets record values from the suppied java bean.

Specified by:
setBeanValues in interface Record
Parameters:
bean - the Java Bean from which to read the value from
Returns:
true if at least one value has been set sucessfully