com.tibco.datagrid

Interface Table

All Superinterfaces:

java.lang.AutoCloseable

public interface Table
extends java.lang.AutoCloseable

The Table object has methods to put, get and delete rows as well as to create a RowSet for iterating over some or all of the data in the table.

The call that creates a table is Session.openTable.

A program that creates a table should explicitly call Table.close to reclaim its resources.

Since Version 4.10: Whenever a Table that did not have its Table.close method called is garbage collected, the native resources will be reclaimed automatically. This behavior is controlled by the com.tibco.tibdg.autoclose System Property. If the property is not set or set to "cleanup" (the default), the native resources will be reclaimed as if the Table.close method had been called. If the System Property is set to "warn", a warning will be printed to stderr instead of doing the cleanup. If the property is set to "inactive", this feature will not be activated.

This interface is implemented internally. Applications do not implement this interface.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TIBDG_TABLE_CHECKPOINT_NAME_LATEST A special checkpoint name that refers to the latest successful checkpoint Specifying this as the value for Table.TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME property instructs the proxy to replace with the last successful checkpoint name.
static java.lang.String	TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME Property name for specifying checkpoint used with a table; string.

Method Summary

Modifier and Type	Method and Description
void	close() Close a table.
Row	createRow() Create an empty row object.
RowSet	createRowSet(java.lang.String filter, java.util.Properties props) Create a RowSet to selectively get rows in the table.
TableListener	createTableListener(java.lang.String filter, TableEventHandler eventHandler) Create a TableListener Table listeners receive Event objects to indicate that the table they are listening on has changed.
TableListener	createTableListener(java.lang.String filter, TableEventHandler eventHandler, java.util.Properties props) Create a TableListener
void	delete(Row key) Delete a row from a table.
Row	get(Row key) Get a row from a table.
java.lang.String	getName() Get the name of the table.
Session	getSession() Get the session object that was used to create the table.
void	put(Row keyValue) Put a row into a table.
long	update(Row key) Update a row in the table.

Field Detail

TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME

static final java.lang.String TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME

Property name for specifying checkpoint used with a table; string.

Supply this property to Session.openTable.

Specifying this property instructs the datagrid to use the named checkpoint as the data source for this table's read operations (gets, iterators). If this property is not set, the table will use the checkpoint named specified on the session, if any. If this property is set it will override any checkpoint name set on the session. The property value may be a checkpoint name or ID. Tables opened with this property are read-only, write operations (puts, deletes, updates) on the table are not supported. Not supported for transacted sessions.

See Also:

Constant Field Values

TIBDG_TABLE_CHECKPOINT_NAME_LATEST

static final java.lang.String TIBDG_TABLE_CHECKPOINT_NAME_LATEST

A special checkpoint name that refers to the latest successful checkpoint Specifying this as the value for Table.TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME property instructs the proxy to replace with the last successful checkpoint name.

See Also:

Constant Field Values

Method Detail

createRow

Row createRow()
       throws DataGridException

Create an empty row object.

This function returns an empty row object. The application can set columns in the empty row object and use the object as a keyValue for Table.createRow or as a key for Table.get or Table.delete.

Returns:

Row object

Throws:

DataGridException - in case of failures

put

void put(Row keyValue)
  throws DataGridException

Put a row into a table.

The contents of the row contain the information to be placed into the designated table. This must include the values for the columns that make up primary key. Values for the other columns are optional.

Parameters:

keyValue - The row to be placed in the table.

Throws:

DataGridException - in case of failures

get

Row get(Row key)
 throws DataGridException

Get a row from a table.

Using the columns set in the key, this call fetches the row from the table and returns it.

Note: Do not use a row object obtained from one table for operations in a different table. The schemas of the tables may not be compatible and the operations may fail.

Any row object obtained from this function must be released by calling Row.destroy

Parameters:

key - The key information used to fetch the row.

Returns:

Row object

Throws:

DataGridException - in case of failures

update

long update(Row key)
     throws DataGridException

Update a row in the table.

Sets the columns in the row specified by the key to the values set in the input row returning the number of rows modified. Will update only the columns specified leaving others intact in the existing row

If the row does not exist, this will do nothing and return zero

Parameters:

key - The key information used to fetch the row.

Returns:

int number of rows modified by the update (zero if row was not in table)

Throws:

DataGridException - in case of failures

createRowSet

RowSet createRowSet(java.lang.String filter,
                    java.util.Properties props)
             throws DataGridException

Create a RowSet to selectively get rows in the table.

This call creates an RowSet object that contains an iterator which returns rows matching the filter.

This call will block while it fetches the first batch of rows. If fetching each batch of rows is expected to take a long time then the RowSet.TIBDG_ITERATOR_PROPERTY_DOUBLE_FETCH_TIMEOUT property should be set to prevent the fetch requests from timing out.

Parameters:

filter - A string containing a valid query or null to include all the rows in the table

props - Optional, null to omit

• RowSet.TIBDG_ITERATOR_PROPERTY_LONG_PREFETCH
• RowSet.TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY
• RowSet.TIBDG_ITERATOR_PROPERTY_DOUBLE_FETCH_TIMEOUT

Returns:

RowSet

Throws:

DataGridException - in case of failures

delete

void delete(Row key)
     throws DataGridException

Delete a row from a table.

Using the columns in the key, this call deletes the row from the table.

Parameters:

key - The key used to identify row in the table.

Throws:

DataGridException - in case of failures

getName

java.lang.String getName()
                  throws DataGridException

Get the name of the table.

Returns:

a table name string

Throws:

DataGridException - in case of failures

getSession

Session getSession()
            throws DataGridException

Get the session object that was used to create the table.

Returns:

Session

Throws:

DataGridException - in case of failures

createTableListener

TableListener createTableListener(java.lang.String filter,
                                  TableEventHandler eventHandler)
                           throws DataGridException

Create a TableListener Table listeners receive Event objects to indicate that the table they are listening on has changed. A filter can be provided so that only events that match the filter will be received. The syntax for the filter is the same as the syntax for the RowIterator. An event matches the filter if either its previous or current value match.

Parameters:

filter - The filter string to for the listener to use

eventHandler - the object to deliver events to (see TableEventHandler)

Returns:

TableListener

Throws:

DataGridException - in case of failures

createTableListener

TableListener createTableListener(java.lang.String filter,
                                  TableEventHandler eventHandler,
                                  java.util.Properties props)
                           throws DataGridException

Create a TableListener

Parameters:

filter - The filter string to for the listener to use

eventHandler - the object to deliver events to (see TableEventHandler)

props - Optional, null to omit

• TableListener.TIBDG_LISTENER_PROPERTY_STRING_EVENT_TYPE_LIST

Returns:

TableListener

Throws:

DataGridException - in case of failures

close

void close()
    throws DataGridException

Close a table.

Release all resources associated with this table object.

Note that pending operations on this table, e.g., transactional puts, gets or deletes, are marked as "rollback only" if this table is closed before the operations are committed.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

DataGridException - in case of failures