Package org.apache.empire.db

Class DBRecordBase

java.lang.Object
org.apache.empire.db.DBObject
org.apache.empire.db.DBRecordData
org.apache.empire.db.DBRecordBase
All Implemented Interfaces:
Serializable, Cloneable, Record, RecordData, DBContextAware
Direct Known Subclasses:
DBRecord, DBRecordBean
public abstract class DBRecordBase extends DBRecordData implements Record, Cloneable, Serializable
This abstract class provides write access to the fields of a record The class provides methods that are useful for frontend-form development like - providing information about the allowed values for a field (field options) - providing information about whether or not a field is visible to the user - providing information about whether or not a field is required (mandantory) - providing information about whether or not a field is read-only - providing information about whether a particular field value is valid - providing information about whether a field was modified since it was read from the database - providing information about whether the record was modified Also, field value changes, can be handled using the onFieldChanged event.
See Also:

  • Field Details

    • validateFieldValues

      protected boolean validateFieldValues

    • allowReadOnlyUpdate

      protected boolean allowReadOnlyUpdate

  • Constructor Details

    • DBRecordBase

      protected DBRecordBase()
      Internal constructor for DBRecord May be used by derived classes to provide special behaviour

  • Method Details

    • checkValid

      protected void checkValid()
      helper to check if the object is valid
      Throws:
      ObjectNotValidException - if the object is not valid

    • checkValid

      protected void checkValid(int fieldIndex)
      helper to check if the object is valid
      Parameters:
      fieldIndex - the field index
      Throws:
      ObjectNotValidException - if the object is not valid

    • close

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

    • clone

      public DBRecordBase clone()
      Overrides:
      clone in class Object

    • getRowSet

      public abstract DBRowSet getRowSet()
      Returns the DBRowSet object.
      Returns:
      the DBRowSet object

    • isRollbackHandlingEnabled

      public abstract boolean isRollbackHandlingEnabled()
      Returns whether or not RollbackHandling is enabled for this record
      Returns:
      true if rollback handling is enabled or false otherwise

    • getEntity

      public Entity getEntity()
      returns true if this record is a new record.
      Specified by:
      getEntity in interface Record
      Returns:
      true if this record is a new record

    • getDatabase

      public DBDatabase getDatabase()
      Returns the current DBDatabase object.
      Specified by:
      getDatabase in class DBObject
      Returns:
      the current DBDatabase object

    • getState

      public DBRecordBase.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

    • isExists

      public boolean isExists()
      Returns true if this record is a existing record (valid but not new). This may be used from expression language instead of the not allowed property "new"
      Returns:
      true if this record is a existing record (valid but not new).

    • 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

    • getColumn

      public DBColumn getColumn(int index)
      Implements the Record Interface getColumn method.
      Internally calls getDBColumn()
      Specified by:
      getColumn in interface Record
      Specified by:
      getColumn in interface RecordData
      Parameters:
      index - field index of the column expression
      Returns:
      the Column at the specified index

    • 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

    • wasAnyModified

      public final boolean wasAnyModified(Column... columns)
      Returns true if any of the given fields was modified.
      Parameters:
      columns - the columns to check
      Returns:
      true if any of the given fields were modified or false otherwise

    • 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

    • 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

    • getKey

      public Object[] getKey()
      Returns a array of key columns by a specified DBRecord object.
      Specified by:
      getKey in interface Record
      Returns:
      a array of 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
      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

    • validateAllValues

      public void validateAllValues()
      validates all modified values of a record

    • setValue

      public void setValue(int index, Object value)
      Sets the value of a 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

      @Deprecated public DBRecordBase setValue(Column column, Object value)
      Deprecated.
      Deprecated Renamed to set(...)
      Parameters:
      column - a DBColumn object
      value - the value
      Returns:
      returns self (this)

    • set

      public DBRecordBase set(Column column, Object value)
      Sets the value of a column in the record. The functions checks if the column and the value are valid and whether the value has changed.
      Specified by:
      set in interface Record
      Parameters:
      column - a DBColumn object
      value - the value
      Returns:
      returns self (this)

    • 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

    • 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

    • setRecordValues

      public int setRecordValues(Object bean, Collection<Column> ignoreList)
      Sets record values from the supplied java bean.
      Specified by:
      setRecordValues 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

    • setRecordValues

      public final int setRecordValues(Object bean)
      Sets record values from the suppied java bean.
      Specified by:
      setRecordValues 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 successfully

    • setParentRecord

      public void setParentRecord(DBColumn parentIdColumn, DBRecordBase record)
      For DBMS with IDENTITY-columns defer setting the parent-id until the record is inserted The parent record must have a one-column primary key
      Parameters:
      parentIdColumn - the column for which to set the parent
      record - the parent record to be set for the column

    • isSame

      public boolean isSame(DBRecordBase other)
      Compares the record to another one
      Parameters:
      other - the record to compare this record with
      Returns:
      true if it is the same record (but maybe a different instance)

    • addXmlMeta

      public int addXmlMeta(Element parent)
      This function set the field descriptions to the the XML tag.
      Specified by:
      addXmlMeta in class DBRecordData
      Returns:
      the number of column descriptions added to the element

    • addXmlData

      public int addXmlData(Element parent)
      Add the values of this record to the specified XML Element object.
      Specified by:
      addXmlData in class DBRecordData
      Parameters:
      parent - the XML Element object
      Returns:
      the number of row values added to the element

    • 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

    • 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

    • changeState

      protected void changeState(DBRecordBase.State newState)
      changes the state of the record
      Parameters:
      newState - the new record state

    • createRollbackHandler

      protected DBRollbackHandler createRollbackHandler()
      Factory function to create createRollbackHandler();
      Returns:
      the DBRollbackHandler

    • initData

      protected void initData(boolean newRecord)
      This method is used internally by the RowSet to initialize the record's properties
      Parameters:
      newRecord - flag whether the record is new (non-existing) in the database

    • initData

      protected void initData(DBRecordBase other)
      This method may be used to copy the record in order to preserve its state
      Parameters:
      other - the record to be copied

    • updateComplete

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

    • checkUpdateable

      protected void checkUpdateable()
      Checks whether the record is updateable If its read-only a RecordReadOnlyException is thrown
      Throws:
      RecordReadOnlyException - exception thrown if record cannot be updated

    • 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

    • modifyValue

      protected void modifyValue(int index, 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:
      index - index of the column
      value - the column value
      fireChangeEvent - flag whether to fire the onFieldChanged event

    • setFieldModified

      protected void setFieldModified(int index, boolean modifiedFlag)
      Sets a fields modified status
      Parameters:
      index - the field index
      modifiedFlag - flag indicating whether or not the field was modified

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

    • setRecordValue

      protected void setRecordValue(Column column, Object bean)
      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
      column - the column for which to set the record value

    • assignParentIdentities

      protected void assignParentIdentities()
      For DBMS with IDENTITY-columns the deferred parent-keys are set by this functions The parent records must have been previously set using setParentRecord

    • isColumn

      protected boolean isColumn(int index, DBColumn... column)
      helper function to check if a given field index corresponds to one of the given columns
      Parameters:
      index - the field index
      column - one or more columns to check
      Returns:
      true if the index is for one of the columns or false otherwise

    • getXmlDictionary

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