These steps outline the main structural components of most application programs that access a ActiveSpaces data grid.
Task B Data Grid Operations
5. Access the data grid using methods of a table object.
See Table Operations.
Programs use sessions to insulate data grid operations within program threads and to unite operations within transactions.
An application program usually creates only one connection to a data grid. From that connection object, a program can create one or many session objects.
Session objects are lightweight.
Sessions and Threads
It is good practice to create a separate session for each program thread that accesses the data grid.
Programs must use sessions in a thread-safe way. That is, two threads must not simultaneously access the same session. Violating this constraint can yield unpredictable results.
Sessions and Transactions
Each session can be either transacted or non-transacted. Programs determine this semantic property when creating each session.
In a transacted session, all get, put, and delete operations occur within a transaction, which is bound to the session. The session implicitly starts the transaction. Programs explicitly call the session's commit and rollback methods. (As these methods complete, they automatically start a new transaction in the session.)
If a program operates within several open transactions simultaneously, use a separate session and thread for each transaction.
In a non-transacted session, put, get, and delete operations are immediate: that is, when the method completes, the effect of the operation is also complete.
However, operations in a transacted session can block operations in a non-transacted session. For further explanation, see Transaction Isolation.
Only get, put, and delete operations are affected by a transacted session, the corresponding commit, and rollback APIs. Other commands such as iterators, queries, DDL updates, and so on do not have different behavior when running on a transacted session versus a non-transacted session.
Sessions and Defining Tables
Once a session has been created, it can be used to define tables programmatically. For more information, see "Defining a Table Using SQL DDL Commands" in the TIBCO ActiveSpaces Administration guide.
Table
Table objects represent data grid tables within an application program.
Tables and Sessions
A program opens a table object by calling a session's open table method. The program can use the table object's methods to operate on the corresponding table in the data grid.
Opening a table object does not lock the table in the data grid.
If the session is transacted, then table operations occur within the session's transaction. Within a transaction you can interact with multiple tables.
If the session is non-transacted, then table operations are not transacted.
Table Operations
Tables support the following data grid operations:
● Put a row into the table
● Get a row of the table
● Delete a row from the table
● Create an iterator to present the results of a table query Primary Key
Every table requires a primary key, which can consist of one or more columns. The data type of key columns must be either long or string.
Examples of primary keys include employee number, invoice number, or MAC address.
The value of the primary key always remains unique across all the rows of the table. That is, database operations can never create two rows with the same key value; instead, they overwrite data in the existing row with that key value.
Creating Tables
Before a program can use a table or its rows for operations, an administrator must first create the table within the data grid. See "Defining a Table" in TIBCO ActiveSpaces Administration.
Put
The put operation adds a row to a data grid table.
Before calling the put method, your program must first create a row object and set its columns with values.
The row object must contain a value in all columns of the primary key. The value of the key is unique. If the table already contains a row with that key value, then the put operation replaces the existing row within the table.
All other columns contain or omit values.
Get
The get operation retrieves a row of a data grid table.
Before calling the get method, your program must first create a row object and set a value in all columns of the primary key. The value of the key is unique.
If the table contains a row with that key value, then the get operation returns the contents of that row in a new row object. If the table does not contain a row with that key value, then the method returns null.
Delete
The delete operation deletes a row from a data grid table.
Before calling the delete method, your program must first create a row object and set a value in all columns of the primary key. The value of the key is unique.
If the table contains a row with that key value, then the delete operation deletes that row from the table.
If the table does not contain a row with that key value, then the method returns without changing the table.
Create Iterator
The create iterator operation submits a query on a data grid table and creates an iterator object to present the query results.
Supply a filter string as an argument. This filter specifies the content of the query: that is, criteria for selecting a subset of rows from the table.
An iterator object receives batches of matching rows from the data grid. The prefetch property of the iterator determines the batch size.
The iterator consistency property allows the client to choose between the following snapshot consistency level:
● global snapshot (default level)
This level ensures that none of the results in the snapshot are from a partially committed transaction, although more coordination is required when taking the snapshot.
● snapshot
This level makes no guarantee about the results in the snapshot containing partially committed transactions but requires less coordination when taking the snapshot.
The iterator object presents the program with the individual rows that match the query, one at a time.
The program must close the iterator object to release resources within the data grid component processes. For more information, see Query Behavior.
An implicit timeout limits the lifespan of iterator objects. Program calls that access an iterator after that timeout elapses return an error.
Avoid queries that result in full table scans, which can be resource-intensive and time-consuming. For more information, see Efficiency of Filters.
Metadata
Application programs can use the metadata APIs to retrieve metadata information about the data grid or a specific table.
The outline of the process involved in retrieving metadata information:
1. Your program needs to get a reference to valid connection object if you don't already have one.
If the program only has a reference to a single table, it must use accessor methods to get the reference to the parent session and then the parent connection.
2. Call the get grid metadata API for the connection.
This makes a network request to the data grid for the metadata information (including all tables) at that point in time.
The program destroys the grid matadata after the request is completed. If updated grid metadata is needed, the existing metadata object must be destroyed. Another request must be made using the same API to retrieve the latest metadata information.
3. The table metadata object and any strings retrieved from it do not need to be destroyed since they are all owned by the grid metadata object and are destroyed as part of its destroy method.
Grid Metadata Object
The grid metadata object contains the array of table metadata objects that exist in the data grid at the time the request was made.
A single metadata object for a table is retrieved using its table name. If the names of the tables are not known to the program, the grid metadata object provides a method to get the array of all table names, which in turn can be used to get a single table metadata object as described previously.
Similarly, a column name or index name is used to get information about that column or index from a table metadata object. If the column names or index names are not known to the program, the table metadata object provides a method to get the array of those names.
Additionally, a method to get the primary index name exists in the table metadata object and is used to determine the table's primary index and then the column (or columns) that make up that index (often known as the primary key(s) of the table).