com.tietoenator.trip.jxp.data

## Class TdbTupleList

- java.lang.Object
- - com.tietoenator.trip.jxp.data.TdbTupleList

-     public class TdbTupleList
      extends java.lang.Object

  The TdbTupleList class is an abstraction of a collection of fields that form a conceptual table within a record. The rows in the table are TdbTuple objects.

  For an example of how to use the TdbTupleList class, please refer to the sample com.tietoenator.trip.jxp.examples.data.Tuples.

  Since:
    TRIPjxp 1.3-0
  See Also:
    `TdbTuple`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TdbTupleList(TdbSession session, TdbComponent cmp, java.lang.String strFieldList)` Create a new tuple list by using a list of field names.
    `TdbTupleList(TdbSession session, TdbComponent cmp, TdbDatabaseDesign db, java.lang.String fieldGroupName)` Create a new tuple list by using a field group.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TdbTuple` | `append()` Creates and appends a new tuple.
    `TdbTuple` | `get(int tupleIndex)` Get the row (tuple) at the specified index.
    `int` | `getColumnCount()` The number of columns (fields) defined for the TdbTupleList object.
    `java.lang.String` | `getColumnName(int index)` Returns the (field) name of the specified column.
    `TdbFieldType` | `getColumnType(int index)` Returns the (field) type of the specified column.
    `TdbComponent` | `getComponent()` Get the component that holds the fields in the tuple list.
    `java.lang.String` | `getDefinition()` The semi-colon delimited definition string that was used to create the tuple list.
    `int` | `getRowCount()` The number of rows (tuples) defined for the TdbTupleList instance.
    `TdbTuple` | `insert(int tupleIndex)` Creates and inserts a new tuple.
    `void` | `remove(int tupleIndex)` Removes a tuple.
    `void` | `setComponent(TdbComponent cmp)` Set the component that holds the fields in the tuple list.
    `void` | `setDefinition(java.lang.String strFieldList)` Modify the tuple list to use a new set of fields in the same component.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### TdbTupleList

          public TdbTupleList(TdbSession session,
                              TdbComponent cmp,
                              java.lang.String strFieldList)
                       throws TdbException

      Create a new tuple list by using a list of field names.

      Valid fields are fields that are represented by one ofthe TdbStructuredField sub classes, i.e. fields of all types except TEXT and STRING fields.

      The fields specified in the field list parameter (strFieldList) must exist in the specified TdbComponent object. If a tuple list is to be used on a new, not yet stored record, remember to use one of the the createField methods to create the appropriate TdbField objects for the component first.

      For an example of how to use the TdbTupleList class, please refer to the Programmer's Guide and the Tuples example provided with TRIPjxp.

      Parameters:
        `session` - Active session
        `cmp` - The component that contains the fields to use.
        `strFieldList` - Semicolon-delimited string of field names specifying which fields the tuple list should encompass.
      Throws:
        `TdbException` - If the field list could not be created, e.g. when one of the fields does not exist or is not retrieved or created in the component.
      See Also:
        `TdbComponent.createField(TdbFieldDesign)`, `TdbComponent.createField(String, TdbFieldType)`, `TdbStructuredField`

    - #### TdbTupleList

          public TdbTupleList(TdbSession session,
                              TdbComponent cmp,
                              TdbDatabaseDesign db,
                              java.lang.String fieldGroupName)
                       throws TdbException

      Create a new tuple list by using a field group.
      Parameters:
        `session` - Active session.
        `cmp` - The component that contains the fields to use.
        `db` - Database design associated with the component.
        `fieldGroupName` - Name of the field group that will be used to instantiate this tuple list.
      Throws:
        `TdbException` - If the tuple list could not be created.
      Since:
        TRIPjxp 8.0-0 The database design information is used to add the fields in the field group to the component if that has not already been done. This eliminates the need for the application to add the fields to the component in advance.

  - ### Method Detail

    - #### getDefinition

          public java.lang.String getDefinition()

      The semi-colon delimited definition string that was used to create the tuple list.
      Returns:
        Tuple list definition string.

    - #### setDefinition

          public void setDefinition(java.lang.String strFieldList)
                             throws TdbException

      Modify the tuple list to use a new set of fields in the same component.
      Parameters:
        `strFieldList` - Semi-colon delimited list of field names.
      Throws:
        `TdbException` - If reinitialization fails. If the definition string is different from the pre-existing one, the tuple list will be reinitialized with the fields in the new definition string. Any changes made to the values in the formerly tupled fields are kept uncommitted in the associatd TdbRecord object.
      See Also:
        `TdbRecord`

    - #### getComponent

          public TdbComponent getComponent()

      Get the component that holds the fields in the tuple list.
      Returns:
        TdbComponent reference

    - #### setComponent

          public void setComponent(TdbComponent cmp)
                            throws TdbException

      Set the component that holds the fields in the tuple list.
      Parameters:
        `cmp` - TdbComponent reference
      Throws:
        `TdbException` - If reinitialization fails. If the component is different from the pre-existing one, the tuple list will be reinitialized for the new component. Any changes made to the values in the tupled fields in the old component are kept uncommitted in the associated TdbRecord object.
      See Also:
        `TdbRecord`

    - #### getColumnCount

          public int getColumnCount()

      The number of columns (fields) defined for the TdbTupleList object.
      Returns:
        Number of columns (fields) in the tuple list.

    - #### getRowCount

          public int getRowCount()

      The number of rows (tuples) defined for the TdbTupleList instance.
      Returns:
        Number of rows (tuples) in the tuple list.

    - #### getColumnName

          public java.lang.String getColumnName(int index)
                                         throws TdbException

      Returns the (field) name of the specified column.
      Parameters:
        `index` - Zero-based index of the column whose name to retrieve.
      Returns:
        Field name
      Throws:
        `TdbException` - If the index is outside the valid range.

    - #### getColumnType

          public TdbFieldType getColumnType(int index)
                                     throws TdbException

      Returns the (field) type of the specified column.
      Parameters:
        `index` - Zero-based index of the column whose type to retrieve.
      Returns:
        Field type
      Throws:
        `TdbException` - If the index is outside the valid range.

    - #### get

          public TdbTuple get(int tupleIndex)
                       throws TdbException

      Get the row (tuple) at the specified index.
      Parameters:
        `tupleIndex` - Zero-based index of tuple to retrieve.
      Returns:
        TdbTuple object for the specified row.
      Throws:
        `TdbException` - If the index is outside the valid range.

    - #### insert

          public TdbTuple insert(int tupleIndex)
                          throws TdbException

      Creates and inserts a new tuple.
      Parameters:
        `tupleIndex` - Zero-based index at which to insert a new tuple.
      Returns:
        A TdbTuple instance representing the new tuple.
      Throws:
        `TdbException` - If the index is outside the valid range.

    - #### append

          public TdbTuple append()
                          throws TdbException

      Creates and appends a new tuple.
      Returns:
        A TdbTuple instance representing the new tuple.
      Throws:
        `TdbException`

    - #### remove

          public void remove(int tupleIndex)
                      throws TdbException

      Removes a tuple.
      Parameters:
        `tupleIndex` - Zero-based index of the tuple to be removed.
      Throws:
        `TdbException` - If the index is outside the valid range.