Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
jACOB 2.7 API Documentation.
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

de.tif.jacob.core.data
Interface IDataTable

All Superinterfaces:
IDataRecordSet
public interface IDataTable
extends IDataRecordSet

A data table represents a record set containing data table records, i.e. instances of IDataTableRecord. The structure of each record contained is determined by the ITableDefinition of the underlying ITableAlias.

A data table instance could be obtained by means of

  • IDataAccessor.getTable(ITableAlias),
  • IDataAccessor.getTable(String).

    Field Summary
     
    Fields inherited from interface de.tif.jacob.core.data.IDataRecordSet
    UNLIMITED_RECORDS
     
    Method Summary
     void clear()
              Clears all records populated.
     long count()
              Counts the records which match the current QBE settings of this table.
     long count(IRelationSet relationSet)
              Same behaviour than count() except that QBE constraints of related data tables determined by the given relation set and the conditions of the related table aliases, if existing
    are also considered.
     long count(java.lang.String relationSetName)
              Same behaviour than count() except that QBE constraints of related data tables determined by the given relation set and the conditions of the related table aliases, if existing
    are also considered.
     boolean exists()
              Checks whether at least one record exists which matches the current QBE settings.
     boolean exists(ITableField tableField, java.lang.Object value)
              Checks whether at least one record exists which matches the given field value expression.
     boolean exists(java.lang.String tableFieldName, java.lang.Object value)
              Checks whether at least one record exists which matches the given field value expression.
     void fastDelete(IDataTransaction trans)
              Deletes records of this table without retrieving them.
     java.lang.String getName()
              Returns the name of this data table, which equals to the name of the underlying ITableAlias.
     IDataTableRecord getRecord(IDataKeyValue primaryKey)
              Returns the data table record given by its primary key.
     IDataTableRecord getRecord(int index)
              Returns the data table record given by its index.
     IDataTableRecord getSelectedRecord()
              Returns the selected record of this table.
     IDataTransaction getTableTransaction()
               
     IDataTableRecord loadRecord(IDataKeyValue primaryKey)
              Loades the data table record given by its primary key from the data source.
     IDataTableRecord newRecord(IDataTransaction trans)
              Creates a new record in the underlying data source.
     void qbeClear()
              Removes all QBE constraints which have been set for this data table.
     boolean qbeHasConstraint()
              Checks whether any constraint is set on any table field.
     void qbeSetKeyValue(IKey key, IDataKeyValue keyValue)
              Sets the QBE constraint values for all table fields of the given key to the given key value.
     void qbeSetKeyValue(ITableField tableField, java.lang.Object value)
              Sets a QBE constraint value for the given table field.
     void qbeSetKeyValue(java.lang.String tableFieldName, java.lang.Object value)
              Sets a QBE constraint value for the given table field.
     void qbeSetOptional()
              Marks all QBE constraints as optional.
     void qbeSetPrimaryKeyValue(IDataKeyValue primaryKeyValue)
              Sets the QBE values for all table fields of the table's primary key to the given primary key value.
     void qbeSetValue(ITableField tableField, java.lang.Object value)
              Sets a QBE constraint value for the given table field.
     void qbeSetValue(java.lang.String tableFieldName, java.lang.Object value)
              Sets a QBE constraint value for the given table field.
     IDataTableRecord reloadSelectedRecord()
              Refreshes the selected record by means of reloading it from data source.
     int search()
              Populates the data table by means of performing a search operation, which will be constrained by QBE constraints which have been set for this table the condition of the related table alias, if existing.
     int search(IRelationSet relationSet)
              Populates the data table by means of performing a search operation, which will be constrained by QBE constraints which have been set for this table, QBE constraints of related data tables determined by the given relation set and the conditions of the related table aliases, if existing.
     int search(java.lang.String relationSetName)
              Populates the data table by means of performing a search operation, which will be constrained by QBE constraints which have been set for this table, QBE constraints of related data tables determined by the given relation set and the conditions of the related table aliases, if existing.
     int searchAndDelete(IDataTransaction trans)
              Deletes records of this table by means of retrieving them first.
     IDataTransaction startNewTransaction()
               
     
    Methods inherited from interface de.tif.jacob.core.data.IDataRecordSet
    getAccessor, getMaxRecords, getTableAlias, hasMoreRecords, recordCount, setMaxRecords
     

    Method Detail

    getName

    java.lang.String getName()
    Returns the name of this data table, which equals to the name of the underlying ITableAlias.

    Specified by:
    getName in interface IDataRecordSet
    Returns:
    the data table name

    clear

    void clear()
    Clears all records populated.

    Note that this method does not implicitly invoke qbeClear(), i.e. QBE constraints are not cleared.

    Specified by:
    clear in interface IDataRecordSet

    qbeClear

    void qbeClear()
    Removes all QBE constraints which have been set for this data table.

    This has the effect that a subsequent search call will either not be constrained at all or only be constrained by the condition of the underlying table alias, in case such a condition exists.

    Note that clear() does not implicitly invoke this method. Nevertheless, IDataAccessor.clear() executed on the parent data accessor does clear QBE constraints of all data tables as well.

    qbeSetOptional

    void qbeSetOptional()
    Marks all QBE constraints as optional.

    This has the effect that a search call performed on a linked table alias (either by searching on IDataTable or IDataBrowser) will result into an outer join (instead of an inner join). For search calls performed on the related table alias of this data table (see IDataRecordSet.getTableAlias()) marking QBE constraints as optional has no effect.

    By default QBE constraints are not marked as optional. Calling qbeClear() or IDataAccessor.qbeClearAll() will reset the optional flag, i.e. added QBE constraints will be mandatory.

    qbeHasConstraint

    boolean qbeHasConstraint()
    Checks whether any constraint is set on any table field.

    Returns:
    true if a constraint is set, otherwise false.

    qbeSetPrimaryKeyValue

    void qbeSetPrimaryKeyValue(IDataKeyValue primaryKeyValue)
    Sets the QBE values for all table fields of the table's primary key to the given primary key value.

    Parameters:
    primaryKeyValue - the primary key value

    qbeSetKeyValue

    void qbeSetKeyValue(IKey key,
                    IDataKeyValue keyValue)
    Sets the QBE constraint values for all table fields of the given key to the given key value.

    Note: Setting keyValue to null constrains a search in such a way that all key fields have to be null.

    Parameters:
    key - the key
    keyValue - the key value or null

    qbeSetKeyValue

    void qbeSetKeyValue(java.lang.String tableFieldName,
                    java.lang.Object value)
                    throws java.lang.NoSuchFieldException
    Sets a QBE constraint value for the given table field. In contrast to qbeSetValue(String, Object) search modifiers are not considered, i.e. for String values searching is always done on exact match basis.

    Note: Setting value to null is identical with qbeSetValue(tableFieldName, "NULL").

    Parameters:
    tableFieldName - the name of the table field
    value - the QBE value to set or null
    Throws:
    java.lang.NoSuchFieldException - if no such table field exists for this table

    qbeSetKeyValue

    void qbeSetKeyValue(ITableField tableField,
                    java.lang.Object value)
    Sets a QBE constraint value for the given table field. In contrast to qbeSetValue(ITableField, Object) search modifiers are not considered, i.e. for String values searching is always done on exact match basis.

    Note: Setting value to null is identical with qbeSetValue(tableField, "NULL").

    Parameters:
    tableField - the table field
    value - the QBE value to set or null

    qbeSetValue

    void qbeSetValue(java.lang.String tableFieldName,
                 java.lang.Object value)
                 throws java.lang.NoSuchFieldException
    Sets a QBE constraint value for the given table field. Search modifiers could be used by means of passing a appropriate String value to argument value. The following modifiers are existing:
      common modifiers:
          |         logical OR              Examples: john|liz or 1|2|6..10
          |         leading logical OR      Examples: |john or |6..10
                    i.e. grouping logical OR    Note: Explanation see below!
          !         logical NOT             Examples: !NULL or !completed
          NULL      field is empty          Examples: NULL|new or !NULL
 
  common modifiers (not for boolean values):
          >         greater than            Examples: >8 or >d
          >=        greater or equal than   Examples: >=1.1
          <         less than               Examples: <-4.5 or <0|>10
          <=        less or equal than      Examples: <=0
 
  text modifiers:
          =         enforce exact match     Examples: =completed
          ^         enforce left anchored   Examples: ^SELECT
          $         enforce right anchored  Examples: ing$
          &         logical AND             Examples: error&SQL
          *         wildcard                Examples: Bill*ates
          ?         single char wildcard    Examples: No.???
          "         escape text literals    Examples: "<tag>" (interpret > and < as normal characters)
 
  numerical modifiers:
          ..        range                   Examples: 0..100
 
  boolean modifiers:
          false     boolean false           Examples: false|NULL
          true      boolean true            Examples: true
 
  datetime modifiers:
          today     date value of today           Examples: <=today-7d
          now       timestamp value of now        Examples: >now-1h
          ..        range                         Examples: now-24h..now
          thisy     this year range               Examples: thisy or thisy-7d (previous year range)
          thisq     this quarter range            Examples: thisq or thisq-3m (previous quarter range)
          thism     this month range              Examples: thisq or thisq-1m (previous month range)
          thisw     this week range               Examples: thisw or thisw-7d (previous week range)
          ytd       this year to date range       Examples: ytd or ytd-1y (previous year to date range, e.g. 2004-01-01..2004-05-13)
          qtd       this quarter to date range    Examples: qtd or qtd-3m (previous quarter to date range, e.g. 2004-04-01..2004-06-03)
          mtd       this month to date range      Examples: mtd or mtd-1m (previous month to date range, e.g. 2004-05-01..2004-05-27)
          wtd       this week to date range       Examples: wtd or wtd-7d (previous week to date range)
          weekx     calendar week x of this year  Examples: week1 or week1..week10
          [+-]xsec  add/sub x seconds             Examples: now-30sec..now
          [+-]xmin  add/sub x minutes             Examples: now-10min
          [+-]xh    add/sub x hours               Examples: now-13h
          [+-]xd    add/sub x days                Examples: today-14d
          [+-]xm    add/sub x months              Examples: today-3m
          [+-]xy    add/sub x years               Examples: today-1y..today

    Grouping logical OR
    By default QBE constraints of different table fields are logically ANDed, if a search operation is performed. Nevertheless, by means of a grouping logical OR QBE constraints could be grouped to one logical OR group.
    Example: A call table has a status and a created table field. If you want to search for calls which are either created today or are in status new, you could do this by means of setting the QBE constraint value of status to "|new" and the QBE constraint value of created to "|today".

    Parameters:
    tableFieldName - the name of the table field
    value - the QBE value to set
    Throws:
    java.lang.NoSuchFieldException - if no such table field exists for this table

    qbeSetValue

    void qbeSetValue(ITableField tableField,
                 java.lang.Object value)
    Sets a QBE constraint value for the given table field. Search modifiers could be used by means of passing a appropriate String value to argument value. The following modifiers are existing: 
      common modifiers:
          |         logical OR              Examples: john|liz or 1|2|6..10
          |         leading logical OR      Examples: |john or |6..10
                    i.e. grouping logical OR    Note: Explanation see below!
          !         logical NOT             Examples: !NULL or !completed
          NULL      field is empty          Examples: NULL|new or !NULL
 
  common modifiers (not for boolean values):
          >         greater than            Examples: >8 or >d
          >=        greater or equal than   Examples: >=1.1
          <         less than               Examples: <-4.5 or <0|>10
          <=        less or equal than      Examples: <=0
 
  text modifiers:
          =         enforce exact match     Examples: =completed
          ^         enforce left anchored   Examples: ^SELECT
          $         enforce right anchored  Examples: ing$
          &         logical AND             Examples: error&SQL
          *         wildcard                Examples: Bill*ates
          ?         single char wildcard    Examples: No.???
          "         escape text literals    Examples: "<tag>" (interpret > and < as normal characters)
 
  numerical modifiers:
          ..        range                   Examples: 0..100
 
  boolean modifiers:
          false     boolean false           Examples: false|NULL
          true      boolean true            Examples: true
 
  datetime modifiers:
          today     date value of today           Examples: <=today-7d
          now       timestamp value of now        Examples: >now-1h
          ..        range                         Examples: now-24h..now
          thisy     this year range               Examples: thisy or thisy-7d (previous year range)
          thisq     this quarter range            Examples: thisq or thisq-3m (previous quarter range)
          thism     this month range              Examples: thisq or thisq-1m (previous month range)
          thisw     this week range               Examples: thisw or thisw-7d (previous week range)
          ytd       this year to date range       Examples: ytd or ytd-1y (previous year to date range, e.g. 2004-01-01..2004-05-13)
          qtd       this quarter to date range    Examples: qtd or qtd-3m (previous quarter to date range, e.g. 2004-04-01..2004-06-03)
          mtd       this month to date range      Examples: mtd or mtd-1m (previous month to date range, e.g. 2004-05-01..2004-05-27)
          wtd       this week to date range       Examples: wtd or wtd-7d (previous week to date range)
          weekx     calendar week x of this year  Examples: week1 or week1..week10
          [+-]xsec  add/sub x seconds             Examples: now-30sec..now
          [+-]xmin  add/sub x minutes             Examples: now-10min
          [+-]xh    add/sub x hours               Examples: now-13h
          [+-]xd    add/sub x days                Examples: today-14d
          [+-]xm    add/sub x months              Examples: today-3m
          [+-]xy    add/sub x years               Examples: today-1y..today

    Grouping logical OR
    By default QBE constraints of different table fields are logically ANDed, if a search operation is performed. Nevertheless, by means of a grouping logical OR QBE constraints could be grouped to one logical OR group.
    Example: A call table has a status and a created table field. If you want to search for calls which are either created today or are in status new, you could do this by means of setting the QBE constraint value of status to "|new" and the QBE constraint value of created to "|today".

    Parameters:
    tableField - the table field
    value - the QBE value to set

    getRecord

    IDataTableRecord getRecord(int index)
                           throws java.lang.IndexOutOfBoundsException
    Returns the data table record given by its index.

    Parameters:
    index - the index of the record to get.
    Returns:
    the desired record
    Throws:
    java.lang.IndexOutOfBoundsException - if 0 <= index < IDataRecordSet.recordCount() is not fulfilled

    getRecord

    IDataTableRecord getRecord(IDataKeyValue primaryKey)
                           throws RecordNotFoundException
    Returns the data table record given by its primary key.

    In contrast to loadRecord(IDataKeyValue) this method first looks into the record cache. If the record is not already cached, it is loaded from the data source.

    Parameters:
    primaryKey - the primary key value of the desired record
    Returns:
    the desired record
    Throws:
    RecordNotFoundException - if the record could not be retrieved from data source

    loadRecord

    IDataTableRecord loadRecord(IDataKeyValue primaryKey)
                            throws RecordNotFoundException
    Loades the data table record given by its primary key from the data source.

    In contrast to getRecord(IDataKeyValue) this method always retrieves the record from the physical data store, i.e. this method is more expensive than getRecord(IDataKeyValue).

    Parameters:
    primaryKey - the primary key value of the desired record
    Returns:
    the desired record
    Throws:
    RecordNotFoundException - if the record could not be retrieved from data source

    getSelectedRecord

    IDataTableRecord getSelectedRecord()
    Returns the selected record of this table. A selected record exists if this data table is exactly populated by one record.

    Returns:
    the selected record or null if no selected record exists.

    reloadSelectedRecord

    IDataTableRecord reloadSelectedRecord()
                                      throws RecordNotFoundException
    Refreshes the selected record by means of reloading it from data source.

    Returns:
    the reloaded record or null if no selected record exists
    Throws:
    RecordNotFoundException - if the record has already been deleted from data source

    newRecord

    IDataTableRecord newRecord(IDataTransaction trans)
    Creates a new record in the underlying data source.

    After this method has been called the returned record becomes the selected record of this table. Hence, previously populated records, which have been retrieved by one of the search methods, will be cleared!

    Call IDataTransaction.commit() to save this record to the data source.

    Parameters:
    trans - the transaction in which context this operation should be executed
    Returns:
    the record created
    See Also:
    getSelectedRecord()

    count

    long count()
           throws InvalidExpressionException
    Counts the records which match the current QBE settings of this table. If no QBE constraints are existing, the method returns the number of records of the underlying table alias. Table alias conditions are always considered.

    Attention: This method if much more efficient than first searching and then counting the records with IDataRecordSet.recordCount(). And also more accurate since the number of records could have been limited due to max record setting.

    Returns:
    the number of records matching the QBE constraints.
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression

    count

    long count(IRelationSet relationSet)
           throws InvalidExpressionException
    Same behaviour than count() except that
  • QBE constraints of related data tables determined by the given relation set and
  • the conditions of the related table aliases, if existing
    are also considered.

    Parameters:
    relationSet - the relation set
    Returns:
    the number of records matching the QBE constraints.
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression
    Since:
    2.6

    • count

    long count(java.lang.String relationSetName)
           throws InvalidExpressionException
    Same behaviour than count() except that
  • QBE constraints of related data tables determined by the given relation set and
  • the conditions of the related table aliases, if existing
    are also considered.

    Parameters:
    relationSetName - the name of the relation set
    Returns:
    the number of records matching the QBE constraints.
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression
    Since:
    2.6

    • exists

    boolean exists()
               throws InvalidExpressionException
    Checks whether at least one record exists which matches the current QBE settings. If no QBE constraints are existing, the method checks whether the underlying table alias has records at all. Table alias conditions are always considered.

    Returns:
    true one or more records are existing matching the current QBE settings, otherwise false.
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression

    exists

    boolean exists(java.lang.String tableFieldName,
               java.lang.Object value)
               throws InvalidExpressionException,
                      java.lang.NoSuchFieldException
    Checks whether at least one record exists which matches the given field value expression. Unlike exists() the current QBE settings are not taken into account for this operation. Nevertheless, table alias conditions are always considered.

    Parameters:
    tableFieldName - the field name
    value - the field value expression
    Returns:
    true one or more records are existing matching the given field value expression, otherwise false.
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression
    java.lang.NoSuchFieldException - if no such table field exists for this table

    exists

    boolean exists(ITableField tableField,
               java.lang.Object value)
               throws InvalidExpressionException
    Checks whether at least one record exists which matches the given field value expression. Unlike exists() the current QBE settings are not taken into account for this operation. Nevertheless, table alias conditions are always considered.

    Parameters:
    tableField - the table field
    value - the field value expression
    Returns:
    true one or more records are existing matching the given field value expression, otherwise false.
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression

    search

    int search()
           throws InvalidExpressionException
    Populates the data table by means of performing a search operation, which will be constrained by
  • QBE constraints which have been set for this table
  • the condition of the related table alias, if existing.

    Note that the number of records retrieved from data source is limited to the current maximum record setting.

    Returns:
    the number of records retrieved
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression
    See Also:
    IDataRecordSet.getMaxRecords(), IDataRecordSet.setMaxRecords(int)

    • search

    int search(java.lang.String relationSetName)
           throws InvalidExpressionException
    Populates the data table by means of performing a search operation, which will be constrained by
  • QBE constraints which have been set for this table,
  • QBE constraints of related data tables determined by the given relation set and
  • the conditions of the related table aliases, if existing.

    Note that the number of records retrieved from data source is limited to the current maximum record setting.

    Parameters:
    relationSetName - the name of the relation set
    Returns:
    the number of records retrieved
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression
    See Also:
    IDataRecordSet.getMaxRecords(), IDataRecordSet.setMaxRecords(int)

    • search

    int search(IRelationSet relationSet)
           throws InvalidExpressionException
    Populates the data table by means of performing a search operation, which will be constrained by
  • QBE constraints which have been set for this table,
  • QBE constraints of related data tables determined by the given relation set and
  • the conditions of the related table aliases, if existing.

    Note that the number of records retrieved from data source is limited to the current maximum record setting.

    Parameters:
    relationSet - the relation set
    Returns:
    the number of records retrieved
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression
    See Also:
    IDataRecordSet.getMaxRecords(), IDataRecordSet.setMaxRecords(int)

    • searchAndDelete

    int searchAndDelete(IDataTransaction trans)
                    throws InvalidExpressionException,
                           RecordLockedException
    Deletes records of this table by means of retrieving them first.
    To determine the records to be deleted, appropriate QBE constraints have to be set in advance! Table alias conditions are always considered.

    In contrast to fastDelete(IDataTransaction) records are deleted after locking them first, i.e. the operation will fail if at least one record has already been locked by means of another user. For each record deleted the appropriate hooks will be called when performing this operation. This means that this method has a significantly higher overhead than fastDelete(IDataTransaction).

    To perfom this operation IDataTransaction.commit() has to be called.

    Note that the number of records deleted from data source is not limited to the current maximum record setting.

    Parameters:
    trans - the transaction in which context this operation should be executed
    Returns:
    the number of records deleted
    Throws:
    InvalidExpressionException - if any given QBE constraint contains an invalid expression
    RecordLockedException - if at least one record is currently locked by another user.

    fastDelete

    void fastDelete(IDataTransaction trans)
    Deletes records of this table without retrieving them.
    To determine the records to be deleted, appropriate QBE constraints have to be set in advance! Table alias conditions are always considered.

    In contrast to searchAndDelete(IDataTransaction) records are deleted without trying to lock them first, i.e. locked records are deleted as well if they match the search conditions. There will also no hooks be called when performing this operation. To perfom this operation IDataTransaction.commit() has to be called.

    Parameters:
    trans - the transaction in which context this operation should be executed

    startNewTransaction

    IDataTransaction startNewTransaction()

    getTableTransaction

    IDataTransaction getTableTransaction()
    Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
    		jACOB 2.7 API Documentation.
     PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD