com.ebasetech.xi.api
Interface Table

All Superinterfaces:
Element, java.io.Serializable
All Known Subinterfaces:
WebFormTable

public interface Table
extends Element

The Table interface represents a table defined in a form, integration service or workflow job.

Individual tables can be accessed via the Tables interface.

Further documentation.

Since:
V4.4

Field Summary
static java.lang.String SORT_DIRECTION_ASCENDING
          A constant for sort direction ascending for use with the sort() methods
static java.lang.String SORT_DIRECTION_DESCENDING
          A constant for sort direction descending for use with the sort() methods
 
Method Summary
 void copyTable(Table fromTable, boolean removeExistingRows)
          Optionally removes all existing rows and then copies rows from the table specified by fromTable.
 boolean deleteRow()
          Deletes the current row (see getCurrentRow()) in the table.
 boolean deleteRow(int row)
          Deletes the specified row in the table.
 TableRowIterator fetchTable()
          Loads data into the table from the external resource specified as the backing resource, and sets the first row as the current row (see getCurrentRow()).
 TableRowIterator fetchTable(boolean noUpdate)
          Loads data into the table from the external resource specified as the backing resource, and sets the first row as the current row (see getCurrentRow()).
 int findRow(TableColumn column, java.lang.Object value)
          Returns the first row number with the specified column value, or -1 if no match is found.
 TableRowIterator findRows(java.util.Map<java.lang.String,java.lang.Object> parms)
          Returns a row iterator object containing all rows that match the search criteria specified by parms.
 TableColumn getColumn(java.lang.String columnName)
          Returns the specified table column or null if the column does not exist.
 TableColumn[] getColumns()
          Returns an array of all columns in the table.
 java.lang.Object getColumnValueOnRow(TableColumn column, int row)
          Returns an Object representing the value of the table cell at the specified column and row.
 int getCurrentRow()
          Returns the row number for the table's current row.
 int getRowCount()
          Returns the number of rows in the table.
 TableRowIterator getRows()
          Returns a row iterator object that can be used to traverse all table rows
 int insertRow()
          Inserts a new row into the table and sets this row as the current row of the table (see getCurrentRow()).
 boolean isRowDeletedByUser()
          Returns true if the current row (see getCurrentRow()) is marked as deleted by the user.
 boolean isRowDeletedByUser(int row)
          Returns true if the specified row is marked as deleted by the user.
 boolean isRowEmpty()
          Returns true if the current row (see getCurrentRow()) is marked as empty.
 boolean isRowEmpty(int row)
          Returns true if the specified row is marked as empty.
 boolean isRowInserted()
          Returns true if the current row (see getCurrentRow()) has been inserted.
 boolean isRowInserted(int row)
          Returns true if the specified row has been inserted.
 boolean isRowModified()
          Returns true if the current row (see getCurrentRow()) has been modified.
 boolean isRowModified(int row)
          Returns true if the specified row has been modified.
 boolean isRowSelected()
          Returns true if the current row (see getCurrentRow()) is marked as selected
 boolean isRowSelected(int row)
          Returns true if the specified row is marked as selected.
 void replaceTable(Table fromTable)
          Removes all existing rows and copies rows from the table specified by fromTable.
 void resetTable()
          Removes all rows from the table and resets the current row (see getCurrentRow()).
 void setColumnValueOnRow(TableColumn column, int row, java.lang.Object value)
          Sets a value for the table cell at the specified column and row.
 void setCurrentRow(int row)
          Sets the table's current row.
 void setRowDeletedByUser(boolean deleted)
          Sets the deleted by the user status for the current row (see getCurrentRow()).
 void setRowDeletedByUser(int row, boolean deleted)
          Sets the deleted by the user status for the specified row.
 void setRowEmpty(boolean empty)
          Sets the empty status for the current row (see getCurrentRow()).
 void setRowEmpty(int row, boolean empty)
          Sets the empty status for the current row (see getCurrentRow()).
 void setRowSelected(boolean selected)
          Sets the selected flag for the current row (see getCurrentRow()).
 void setRowSelected(int row, boolean selected)
          Sets the selected flag for the specified row.
 void sort(TableColumn column)
          Sorts the table rows using the single column specified by column in ascending order.
 void sort(TableColumn[] columns)
          Sorts the table rows using multiple columns in ascending order.
 void sort(TableColumn[] columns, java.lang.String[] directions)
          Sorts the table rows using multiple columns.
 void sort(TableColumn column, java.lang.String direction)
          Sorts the table rows using the single column specified by column in the order specified by direction.
 void updateTable()
          Updates the external resource specified as the backing resource for the table with the table data, deleting, inserting, and updating rows as required.
 
Methods inherited from interface com.ebasetech.xi.api.Element
getElementName, getElementType
 

Field Detail

SORT_DIRECTION_ASCENDING

static final java.lang.String SORT_DIRECTION_ASCENDING
A constant for sort direction ascending for use with the sort() methods

See Also:
Constant Field Values

SORT_DIRECTION_DESCENDING

static final java.lang.String SORT_DIRECTION_DESCENDING
A constant for sort direction descending for use with the sort() methods

See Also:
Constant Field Values
Method Detail

fetchTable

TableRowIterator fetchTable()
                            throws com.ebasetech.xi.exceptions.FormRuntimeException
Loads data into the table from the external resource specified as the backing resource, and sets the first row as the current row (see getCurrentRow()). All internal row numbers are reset.

Further documentation.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.fetchTable();
 while (rows.next())
 {
   orders.ORDER_VAT.value = orders.ORDER_VALUE.value * vatRate;
 }
 

Returns:
a row iterator object that can be used to traverse all table rows
Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
Since:
V4.4
See Also:
updateTable()

fetchTable

TableRowIterator fetchTable(boolean noUpdate)
                            throws com.ebasetech.xi.exceptions.FormRuntimeException
Loads data into the table from the external resource specified as the backing resource, and sets the first row as the current row (see getCurrentRow()). All internal row numbers are reset.

The noUpdate flag provides an optional optimization. When this flag is set to true, the amount of memory required to support the table content data is reduced by about 50%; however, it is not possible to use the updateTable() method. It is recommended that this option should be used for all read only tables.

Further documentation.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.fetchTable(true);
 while (rows.next())
 {
   orders.ORDER_VAT.value = orders.ORDER_VALUE.value * vatRate;
 }
 

Parameters:
noUpdate - when true indicates that the table will not be updated with updateTable()
Returns:
a row iterator object that can be used to traverse all table rows
Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
Since:
V4.4
See Also:
updateTable()

updateTable

void updateTable()
                 throws com.ebasetech.xi.exceptions.FormRuntimeException
Updates the external resource specified as the backing resource for the table with the table data, deleting, inserting, and updating rows as required. Any rows flagged as empty are ignored and are not written to the external resource. All internal row numbers are reset. The current row (see getCurrentRow()) may be changed by this command.

Further documentation.

Javascript example:

 tables.ORDERS.updateTable();
 

Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
Since:
V4.4
See Also:
fetchTable()

replaceTable

void replaceTable(Table fromTable)
                  throws com.ebasetech.xi.exceptions.FormRuntimeException
Removes all existing rows and copies rows from the table specified by fromTable. This method is equivalent to calling copyTable(fromTable, true). Rows flagged as empty in fromTable are ignored. Any rows in fromTable that have been deleted using the deleteRow() method are ignored. All other rows are copied.

All columns having the same name in each table are copied e.g. if T1 has columns A, B, C, D and T2 has columns B, C, X, Y, T1.replaceTable(T2) will result in data from columns B and C being copied. Any other columns in T1 will be set to null or the column's default value. The current row (see getCurrentRow()) is set to the first row after the copy.

The table specified by fromTable is unaffected and is not changed in any way.

Further documentation.

Javascript example:

 tables.ORDERS.replaceTable(tables.ORDERS_SAVE);
 

Parameters:
fromTable - the source table from which rows are copied
Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
Since:
V4.4
See Also:
fetchTable()

copyTable

void copyTable(Table fromTable,
               boolean removeExistingRows)
               throws com.ebasetech.xi.exceptions.FormRuntimeException
Optionally removes all existing rows and then copies rows from the table specified by fromTable. Rows flagged as empty in fromTable are ignored. Any rows in fromTable that have been deleted using the deleteRow() method are ignored. All other rows are copied.

All columns having the same name in each table are copied e.g. if T1 has columns A, B, C, D and T2 has columns B, C, X, Y, T1.copyTable(T2, true) will result in data from columns B and C being copied. Any other columns in T1 will be set to null or the column's default value. The current row (see getCurrentRow()) is set to the first row after the copy.

The table specified by fromTable is unaffected and is not changed in any way.

Further documentation.

Javascript example:

 tables.ORDERS.copyTable(tables.ORDERS_SAVE, false);
 

Parameters:
fromTable - the source table from which rows are copied
removeExistingRows - if true, all existing rows are removed from the table prior to copying
Throws:
com.ebasetech.xi.exceptions.FormRuntimeException
Since:
V4.4
See Also:
fetchTable()

resetTable

void resetTable()
Removes all rows from the table and resets the current row (see getCurrentRow()).

Note that any rows removed are not flagged as deleted in any backing resource specified for the table i.e. any subsequent updateTable() method will not remove these rows from the attached resource.

Further documentation.

Javascript example:

 tables.ORDERS.resetTable();
 

Since:
V4.4
See Also:
replaceTable(Table), updateTable()

getRows

TableRowIterator getRows()
Returns a row iterator object that can be used to traverse all table rows

Further documentation.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   orders.ORDER_VAT.value = orders.ORDER_VALUE.value * vatRate;
 }
 

Returns:
a row iterator object that can be used to traverse all table rows
Since:
V4.4
See Also:
fetchTable()

getRowCount

int getRowCount()
Returns the number of rows in the table.

Returns:
the number of rows in the table
Since:
V4.4
See Also:
fetchTable()

getColumn

TableColumn getColumn(java.lang.String columnName)
Returns the specified table column or null if the column does not exist. When columnName is a valid Java name, the column can more easily be accessed as tableName.columnName e.g. T1.COL1, however use of this method is the only way to access column names that are not valid Java names.

Javascript example:

 var col = tables.ORDERS.getColumn("2XX");
 

Returns:
a table column, or null if the column does not exist
Since:
V4.4

getColumns

TableColumn[] getColumns()
Returns an array of all columns in the table.

Javascript example:

 var cols = tables.ORDERS.getColumns();
 for each (var col in cols)
 {
   log(col.elementName + ": " + col.value);
 }
 

Returns:
an array of all columns in the table
Since:
V4.4

deleteRow

boolean deleteRow()
Deletes the current row (see getCurrentRow()) in the table.

When the table is backed by an external resource such as a database, the row will be deleted from this resource when a subsequent updateTable() method is invoked.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   if (shouldDeleteOrder())
   {
      orders.deleteRow();
   }
 }
 

Returns:
true if the row has been deleted which should always be the case
Since:
V4.4

isRowSelected

boolean isRowSelected()
Returns true if the current row (see getCurrentRow()) is marked as selected

A row can be marked as selected by:

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   if (orders.isRowSelected())
   {
      ..
   }
 }
 

Returns:
true if the row has been selected
Since:
V4.4

isRowDeletedByUser

boolean isRowDeletedByUser()
Returns true if the current row (see getCurrentRow()) is marked as deleted by the user.

A row can be marked as deleted by the user by:

Note that rows deleted using the deleteRow() or deleteRow(int) methods are not marked as deleted by the user.

Note that the deleted by the user status is removed when updateTable() is called.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   if (orders.isRowDeletedByUser())
   {
      ..
   }
 }
 

Returns:
true if the row has been marked as deleted by the user
Since:
V4.4

isRowInserted

boolean isRowInserted()
Returns true if the current row (see getCurrentRow()) has been inserted. Note that the inserted status is removed when updateTable() is called.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   if (orders.isRowInserted())
   {
      ..
   }
 }
 

Returns:
true if the row has been inserted
Since:
V4.4

isRowEmpty

boolean isRowEmpty()
Returns true if the current row (see getCurrentRow()) is marked as empty.

A row is marked as empty when:

Rows marked as empty are ignored by the updateTable() method.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   if (orders.isRowEmpty())
   {
      ..
   }
 }
 

Returns:
true if the row is marked as empty
Since:
V4.4

isRowModified

boolean isRowModified()
Returns true if the current row (see getCurrentRow()) has been modified. Note that inserted or deleted rows will always return false.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   if (orders.isRowModified())
   {
      ..
   }
 }
 

Returns:
true if the row has been modified
Since:
V4.4

deleteRow

boolean deleteRow(int row)
Deletes the specified row in the table.

When the table is backed by an external resource such as a database, the row will be deleted from this resource when a subsequent updateTable() method is invoked.

Javascript example:

 var deleted = tables.ORDERS.deleteRow(rowNum);
 

Parameters:
row - number
Returns:
true if the row has been deleted, false if the row does not exist
Since:
V4.4

isRowSelected

boolean isRowSelected(int row)
Returns true if the specified row is marked as selected. Throws an IllegalArgumentException if row is not a valid row number.

A row can be marked as selected by:

Javascript example:

 if (tables.ORDERS.isRowSelected(rowNum))
 {
    ..
 }
 

Parameters:
row - number
Returns:
true if the row has been selected
Since:
V4.4

isRowDeletedByUser

boolean isRowDeletedByUser(int row)
Returns true if the specified row is marked as deleted by the user. Throws an IllegalArgumentException if row is not a valid row number.

A row can be marked as deleted by the user by:

Note that rows deleted using the deleteRow() or deleteRow(int) methods are not marked as deleted by the user.

Note that the deleted by the user status is removed when updateTable() is called.

Javascript example:

 if (tables.ORDERS.isRowDeletedByUser(rowNum))
 {
    ..
 }
 

Parameters:
row - number
Returns:
true if the row has been marked as deleted by the user
Since:
V4.4

isRowInserted

boolean isRowInserted(int row)
Returns true if the specified row has been inserted. Throws an IllegalArgumentException if row is not a valid row number. Note that the inserted status is removed when updateTable() is called.

Javascript example:

 if (orders.isRowInserted(rowNum))
 {
    ..
 }
 

Parameters:
row - number
Returns:
true if the row has been inserted
Since:
V4.4

isRowEmpty

boolean isRowEmpty(int row)
Returns true if the specified row is marked as empty. Throws an IllegalArgumentException if row is not a valid row number.

A row is marked as empty when:

Rows marked as empty are ignored by the updateTable() method.

Javascript example:

 if (orders.isRowEmpty(rowNum))
 {
    ..
 }
 

Parameters:
row - number
Returns:
true if the row is marked as empty
Since:
V4.4
See Also:
updateTable()

isRowModified

boolean isRowModified(int row)
Returns true if the specified row has been modified. Throws an IllegalArgumentException if row is not a valid row number. Note that inserted or deleted rows will always return false.

Javascript example:

 if (orders.isRowModified(rowNum))
 {
    ..
 }
 

Parameters:
row - number
Returns:
true if the row has been modified
Since:
V4.4

setRowSelected

void setRowSelected(boolean selected)
Sets the selected flag for the current row (see getCurrentRow()).

The selected status can be displayed to the user by adding a select column checkbox to a Table Control.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   orders.setRowSelected(false);
 }
 

Parameters:
selected -
Since:
V4.4
See Also:
isRowSelected()

setRowSelected

void setRowSelected(int row,
                    boolean selected)
Sets the selected flag for the specified row. Throws an IllegalArgumentException if row is not a valid row number.

The selected status can be displayed to the user by adding a select column checkbox to a Table Control.

Javascript example:

 tables.ORDERS.setRowSelected(rowNum, false);
 

Parameters:
row - number
selected -
Since:
V4.4
See Also:
isRowSelected(int)

setRowDeletedByUser

void setRowDeletedByUser(boolean deleted)
Sets the deleted by the user status for the current row (see getCurrentRow()). Note that the deleted by the user status is removed when updateTable() is called.

The deleted by the user status can be displayed to the user by adding a delete column checkbox to a Table Control.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   orders.setRowDeletedByUser(false);
 }
 

Parameters:
deleted -
Since:
V4.4
See Also:
isRowDeletedByUser()

setRowDeletedByUser

void setRowDeletedByUser(int row,
                         boolean deleted)
Sets the deleted by the user status for the specified row. Throws an IllegalArgumentException if row is not a valid row number. Note that the deleted by the user status is removed when updateTable() is called.

The deleted by the user status can be displayed to the user by adding a delete column checkbox to a Table Control.

Javascript example:

 tables.ORDERS.setRowDeletedByUser(rowNum, false);
 

Parameters:
row - number
deleted -
Since:
V4.4
See Also:
isRowDeletedByUser(int)

setRowEmpty

void setRowEmpty(boolean empty)
Sets the empty status for the current row (see getCurrentRow()). Rows marked as empty are ignored by the updateTable() method.

Javascript example:

 var orders = tables.ORDERS;
 var rows = orders.getRows();
 while (rows.next())
 {
   orders.setRowEmpty(false);
 }
 

Parameters:
empty -
Since:
V4.4
See Also:
isRowEmpty()

setRowEmpty

void setRowEmpty(int row,
                 boolean empty)
Sets the empty status for the current row (see getCurrentRow()). Rows marked as empty are ignored by the updateTable() method. Throws an IllegalArgumentException if row is not a valid row number.

Javascript example:

 tables.ORDERS.setRowEmpty(rowNum, false);
 

Parameters:
row - number
empty -
Since:
V4.4
See Also:
isRowEmpty(int)

insertRow

int insertRow()
Inserts a new row into the table and sets this row as the current row of the table (see getCurrentRow()). The columns in the row are initialized with their default values or null as appropriate. Inserted rows are displayed at the bottom of a Table Control.

Javascript example:

 var newRowNum = tables.ORDERS.insertRow();
 

Returns:
the row number of the new row
Since:
V4.4

findRow

int findRow(TableColumn column,
            java.lang.Object value)
Returns the first row number with the specified column value, or -1 if no match is found.

Javascript example:

 var row = tables.ORDERS.findRow(tables.ORDERS.ORDER_ID, fields.SEARCH_ORDER_ID.value);
 if (row != -1)
 {
   tables.ORDERS.setCurrentRow(row);
 }
 

Parameters:
column - table column
value - the value of the table column, should be the same type as the underlying column object (see Field.getValue())
Returns:
the row number of the found row or -1
Since:
V4.4
See Also:
findRows(Map)

findRows

TableRowIterator findRows(java.util.Map<java.lang.String,java.lang.Object> parms)
Returns a row iterator object containing all rows that match the search criteria specified by parms.

Javascript example:

 var searchParms = {};
 searchParms.CUSTOMER_TYPE = "Internal";
 searchParms.RATING = 4;
 var rows = tables.CUSTOMERS.findRows(searchParms);
 while (rows.next())
 {
   ..
 }
 

Parameters:
parms - a Map of key/value pairs where key is a column name and value is the corresponding value. In Javascript, an Object can be used where key is a column name and value is the corresponding value which should be the same type as the underlying column object (see Field.getValue()).
Returns:
a table row iterator
Since:
V4.4
See Also:
findRow(TableColumn, Object)

getCurrentRow

int getCurrentRow()
Returns the row number for the table's current row.

The current row represents an important concept - a current row exists for all tables that are not empty. All references to table columns and their values which do not explicitly specify a row number are interpreted as referring to the corresponding table cell for the column on the current row. For example, in the following line of code, values for the ORDER_VAT and ORDER_VALUE columns are obtained from the current row.

 orders.ORDER_VAT.value = orders.ORDER_VALUE.value * vatRate;
 
The current row is set by the system as follows:

Returns:
the row number of the table's current row
Since:
V4.4

setCurrentRow

void setCurrentRow(int row)
Sets the table's current row.

Since:
V4.4
See Also:
getCurrentRow()

sort

void sort(TableColumn[] columns,
          java.lang.String[] directions)
Sorts the table rows using multiple columns. Columns are processed from left to right.

Javascript example:

 tables.ORDERS.sort( [tables.ORDERS.DELIVERY_DATE, tables.ORDERS.DELIVERY_DATE], 
 [Table.SORT_DIRECTION_DESCENDING, Table.SORT_DIRECTION_ASCENDING] );
 

Parameters:
columns - an array of table columns
directions - an array of directions where each direction is either "asc" or "desc" (static constants Table.SORT_DIRECTION_ASCENDING or Table.SORT_DIRECTION_DESCENDING can be used). The sort direction at position n is applied to the column at position n. The number of directions must match the number of columns.
Since:
V4.4

sort

void sort(TableColumn[] columns)
Sorts the table rows using multiple columns in ascending order. Columns are processed from left to right.

Javascript example:

 tables.ORDERS.sort( [tables.ORDERS.DELIVERY_DATE, tables.ORDERS.DELIVERY_DATE] );
 

Parameters:
columns - an array of table columns
Since:
V4.4

sort

void sort(TableColumn column,
          java.lang.String direction)
Sorts the table rows using the single column specified by column in the order specified by direction.

Javascript example:

 tables.ORDERS.sort(tables.ORDERS.DELIVERY_DATE, Table.SORT_DIRECTION_DESCENDING);
 

Parameters:
column - the table column
direction - either "asc" or "desc" (static constants Table.SORT_DIRECTION_ASCENDING and Table.SORT_DIRECTION_DESCENDING can be used)
Since:
V4.4

sort

void sort(TableColumn column)
Sorts the table rows using the single column specified by column in ascending order.

Javascript example:

 tables.ORDERS.sort(tables.ORDERS.DELIVERY_DATE);
 

Parameters:
column - the table column
Since:
V4.4

getColumnValueOnRow

java.lang.Object getColumnValueOnRow(TableColumn column,
                                     int row)
Returns an Object representing the value of the table cell at the specified column and row. See Field.getValue() for documentation on which object types are returned for each column type.

Javascript examples:

 tables.ORDERS.getColumnValueOnRow(tables.ORDERS.ORDER_VALUE, rowNum);
 

Parameters:
column - the table column
row - row number
Since:
V4.4
See Also:
Field.getValue()

setColumnValueOnRow

void setColumnValueOnRow(TableColumn column,
                         int row,
                         java.lang.Object value)
Sets a value for the table cell at the specified column and row. See Field.setValue(Object) for documentation on which object types can be used with each column type.

Javascript examples:

 tables.ORDERS.setColumnValueOnRow(tables.ORDERS.ORDER_VALUE, rowNum, 25.13);
 

Parameters:
column - the table column
row - row number
value - the value object, see Field.setValue(Object)
Since:
V4.4