org.apache.empire.db
Class DBRecord

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

public class DBRecord
extends DBRecordData
implements Record, Cloneable

This class handles one record from a database table.

See Also:
Serialized Form

Nested Class Summary
static class DBRecord.State
           
 
Field Summary
protected static org.slf4j.Logger log
           
 
Constructor Summary
DBRecord()
          Create a new DBRecord object.
The record is not attached to a RowSet and the record's state is initially set to REC_INVALID.
DBRecord(DBRowSet initialRowset)
           
 
Method Summary
 int addColumnDesc(Element parent)
          This function set the field descriptions to the the XML tag.
 int addRowValues(Element parent)
          Add the values of this record to the specified XML Element object.
protected  boolean allowFieldChange(DBColumn column)
          Checks whether or not this field can be changed at all.
protected  void changeState(DBRecord.State newState)
          changes the state of the record
 DBRecord clone()
          
 void close()
          Closes the record by releasing all resources and resetting the record's state to invalid.
 void 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
 void create(DBRowSet table, Connection conn)
          Creates a new record for the given table.
All record fields will be filled with their default values.
 void delete(Connection conn)
          This helper function calls the DBRowset.deleteRecord method to delete the record.
 int fillMissingDefaults(Connection conn)
          Set the record default value for the fields with the value ObjectUtils.NO_VALUE
 Column getColumn(int index)
          Implements the Record Interface getColumn method.
Internally calls getDBColumn()
 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(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.
Same as getFieldOptions(DBColumn)
 Options getFieldOptions(DBColumn column)
          Gets the possbile Options for a field in the context of the current record.
protected  Object[] getFields()
          This function provides direct access to the record fields.
This method is used internally be the RowSet to fill the data.
 Column[] getKeyColumns()
          returns an array of key columns which uniquely identify the record.
 Object[] getKeyValues()
          Returns the array of primary key columns.
 DBRowSet getRowSet()
          Returns the DBRowSet object.
 Object getRowSetData()
          Returns the DBRowSet object.
 DBRecord.State getState()
          Returns the record state.
 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))
protected  DBXmlDictionary getXmlDictionary()
          returns the DBXmlDictionary that should used to generate XMLDocuments
 Document getXmlDocument()
          Returns a XML document with the field description an values of this record.
 void init(DBRowSet table, 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.
protected  void initData(DBRowSet rowset, Object rowSetData, boolean newRecord)
          This method is used internally by the RowSet to initialize the record's properties
 boolean isFieldReadOnly(Column column)
          returns whether a field is read only or not
 boolean isFieldRequired(Column column)
          returns whether a field is required or not
 boolean isFieldVisible(Column column)
          returns whether a field is visible to the client or not
 boolean isModified()
          Returns true if the record is modified.
 boolean isNew()
          Returns true if this record is a new record.
 boolean isReadOnly()
          Returns true if the record is valid.
 boolean isValid()
          Returns true if the record is valid.
 boolean isValidateFieldValues()
          Returns whether or not values are checked for validity when calling setValue().
 boolean isValueValid(int index)
          Returns whether a field value is provided i.e.
protected  void modifyValue(int i, Object value, boolean fireChangeEvent)
          Modifies a column value bypassing all checks made by setValue.
protected  void onFieldChanged(int i)
          Override this to get notified when a field value changes
protected  void onRecordChanged()
          Override this to do extra handling when the record changes
protected  void onRowSetChanged()
          Override this to do extra handling when the rowset for this record changes
 void read(DBRowSet table, Object[] keys, Connection conn)
          Loads a record from the database identified by it's primary key.
 void read(DBRowSet table, Object id, Connection conn)
          Loads a record from the database identified by it's primary key.
protected  void setBeanValue(Object bean, String property, Column column)
          set a record value from a particular bean property.
 int setBeanValues(Object bean)
          Sets record values from the suppied java bean.
 int setBeanValues(Object bean, Collection<Column> ignoreList)
          Sets record values from the supplied java bean.
 void setModified(DBColumn column, boolean isModified)
          Sets the modified state of a column.
This will force the field to be updated in the database, if set to TRUE.
 void setValidateFieldValues(boolean validateFieldValues)
          Set whether or not values are checked for validity when calling setValue().
 void setValue(Column column, Object value)
          Sets the value of the column in the record.
 void setValue(int index, Object value)
          Sets the value of the column in the record.
 void update(Connection conn)
          Updates the record and saves all changes in the database.
protected  void updateComplete(Object rowSetData)
          This method is used internally to indicate that the record update has completed
This will set change the record's state to Valid
 Object validateValue(Column column, Object value)
          Validates a value before it is set in the record.
 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, getBeanProperty, getBoolean, getBoolean, getDateTime, getDateTime, getDecimal, getDecimal, getDouble, getDouble, getInt, getInt, getLong, getLong, getString, getString, getValue, isNull, isNull
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.empire.data.RecordData
getBeanProperties, getBeanProperties, getValue, isNull, isNull
 

Field Detail

log

protected static final org.slf4j.Logger log
Constructor Detail

DBRecord

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


DBRecord

public DBRecord(DBRowSet initialRowset)
Method Detail

initData

protected void initData(DBRowSet rowset,
                        Object rowSetData,
                        boolean newRecord)
This method is used internally by the RowSet to initialize the record's properties

Parameters:
rowset - the rowset to which to attach this record
rowSetData - any further RowSet specific data
newRecord -

changeState

protected void changeState(DBRecord.State newState)
changes the state of the record

Parameters:
newState -

getFields

protected Object[] getFields()
This function provides direct access to the record fields.
This method is used internally be the RowSet to fill the data.

Returns:
an array of field values

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 Object

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 Object getRowSetData()
Returns the DBRowSet object.

Returns:
the DBRowSet object

getState

public DBRecord.State 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

isReadOnly

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

Specified by:
isReadOnly 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(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.

Parameters:
index - the field 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.

Parameters:
index - the field index
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, if set to TRUE.

Parameters:
column - the column
isModified - modified or not

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 Object[] getKeyValues()
Returns the array of primary key columns.

Returns:
the array of primary key columns

getValue

public 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 partially loaded.

Parameters:
index - the filed index
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.

Parameters:
column - the database field column
Returns:
the field options

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

protected void modifyValue(int i,
                           Object value,
                           boolean fireChangeEvent)
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 void setValue(int index,
                     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:
index - the index of the column
value - the value

setValue

public final void setValue(Column column,
                           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

allowFieldChange

protected boolean allowFieldChange(DBColumn column)
Checks whether or not this field can be changed at all. Note: This is not equivalent to isFieldReadOnly()

Parameters:
column - the column that needs to be changed
Returns:
true if it is possible to change this field for this record context

validateValue

public Object validateValue(Column column,
                            Object value)
Validates a value before it is set in the record. By default, this method simply calls column.validate()

Specified by:
validateValue in interface Record
Parameters:
column - the column that needs to be changed
value - the new value
Returns:
the value

isValidateFieldValues

public boolean isValidateFieldValues()
Returns whether or not values are checked for validity when calling setValue(). If set to true validateValue() is called to check validity

Returns:
true if the validity of values is checked or false otherwise

setValidateFieldValues

public void setValidateFieldValues(boolean validateFieldValues)
Set whether or not values are checked for validity when calling setValue(). If set to true validateValue() is called to check validity, otherwise not.

Parameters:
validateFieldValues - flag whether to check validity

isFieldVisible

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

May be overridden to implement context specific logic.

Specified by:
isFieldVisible in interface Record
Parameters:
column - the column which to check for visibility
Returns:
true if the column is visible or false if not

isFieldReadOnly

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

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

isFieldRequired

public boolean isFieldRequired(Column column)
returns whether a field is required or not

Specified by:
isFieldRequired in interface Record
Parameters:
column - the database column
Returns:
true if the field is required

init

public void init(DBRowSet table,
                 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

create

public void create(DBRowSet table,
                   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

create

public final void 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

read

public void read(DBRowSet table,
                 Object[] keys,
                 Connection conn)
Loads a record from the database identified by it's primary key. After successful 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.
See Also:
DBRowSet.readRecord(DBRecord, Object[], Connection)

read

public final void read(DBRowSet table,
                       Object id,
                       Connection conn)
Loads a record from the database identified by it's primary key. After successful 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.
See Also:
DBRowSet.readRecord(DBRecord, Object[], Connection)

update

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

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

updateComplete

protected void updateComplete(Object rowSetData)
This method is used internally to indicate that the record update has completed
This will set change the record's state to Valid

Parameters:
rowSetData - additional data held by the rowset for this record (optional)

delete

public void delete(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.
See Also:
DBTable.deleteRecord(Object[], Connection)

addColumnDesc

public int addColumnDesc(Element parent)
This function set the field descriptions to the the XML tag.

Specified by:
addColumnDesc in class DBRecordData
Returns:
the number of column descriptions added to the element

addRowValues

public int addRowValues(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:
the number of row values added to the element

getXmlDictionary

protected DBXmlDictionary getXmlDictionary()
returns the DBXmlDictionary that should used to generate XMLDocuments

Returns:
the DBXmlDictionary

getXmlDocument

public Document getXmlDocument()
Returns a XML document with the field description an values of this record.

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

fillMissingDefaults

public int fillMissingDefaults(Connection conn)
Set the record default value for the fields with the value ObjectUtils.NO_VALUE

Parameters:
conn - the sql connection
Returns:
the number of fields set to default

setBeanValue

protected void setBeanValue(Object bean,
                            String property,
                            Column column)
set a record value from a particular bean property.

For a property called FOO this is equivalent of calling
setValue(column, bean.getFOO())

Parameters:
bean - the Java Bean from which to read the value from
property - the name of the property
column - the column for which to set the record value

setBeanValues

public int setBeanValues(Object bean,
                         Collection<Column> ignoreList)
Sets record values from the supplied 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 successfully

setBeanValues

public final int setBeanValues(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

onRowSetChanged

protected void onRowSetChanged()
Override this to do extra handling when the rowset for this record changes


onRecordChanged

protected void onRecordChanged()
Override this to do extra handling when the record changes


onFieldChanged

protected void onFieldChanged(int i)
Override this to get notified when a field value changes



Copyright © 2008–2014 Apache Software Foundation. All rights reserved.