These steps outline the main structural components of most application programs that access a ActiveSpaces data grid.
Procedure
Task A Initialize ActiveSpaces Objects 1. Initialize the ActiveSpaces library.
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. The put operation overwrites any unchanged columns in the row. The columns that are not part of the primary key can either contain data or be NULL.
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.
Statement
Statement objects are used to run SQL commands on the data grid. Queries (SELECT statements) and data manipulation language (DML) SQL commands can be run by using Statement objects. Statement objects are created by invoking the createStatement() method on the Session object.
A Statement object is created for each individual SQL command. A Statement can be run multiple times and must be closed when it is no longer needed.
You can either create a query using the SELECT statement or update rows using an INSERT or an
INSERT OR REPLACE statement. The INSERT statement is supported for both, transacted and non-transacted sessions. For details on INSERT statement, see The SQL INSERT Statement. For information about INSERT OR REPLACE statement, see The INSERT OR REPLACE Statement.
Parameters
Parameters are used to separate the data of an SQL command from the command itself. This can be useful when the same command can be run multiple times by just varying the data of the command thereby increasing performance of the data grid. Parameters can be used to prevent SQL injection attacks in queries.
Parameters in an SQL command are specified using '?' (question mark). For SELECT statements, parameters are supported for the values of comparisons in WHERE clauses. For INSERT statements, parameters are supported for column values.
The Statement interface provides methods for setting the values of any parameters used in an SQL command. Separate methods for setting parameter values are provided for each data type supported by ActiveSpaces. The setNull() method is provided to specify that a parameter's value must be empty (SQL
NULL). All parameter values must be specified prior to running the statement or an error is returned.
Running Statements
The Statement interface provides two methods for executing the statement. The executeQuery() method is used to run statements, which have been created using a SELECT command. The executeQuery() method returns a ResultSet object that contains the resulting rows of a query.
The executeUpdate() method is used to run statements which have been created using a DML
command. The executeUpdate() method returns the number of rows that were successfully processed.
If the wrong method is used to run a statement, an error is returned. For information about the current list of DML commands supported, see the TIBCO ActiveSpaces Release Notes.
ResultSet
A ResultSet contains the set of rows that make up the result of a query. A ResultSet object is returned when executeQuery() is invoked on a Statement created for a SELECT statement. The ResultSet object must be closed when it is no longer needed. A ResultSet object is returned even if no rows were found for the query.
The ResultSet object contains methods that allow you to iterate over the rows of the query result. A ResultSet object can be iterated over only once. The hasNext() method is used to check if there is a row that can be retrieved. The next() method is used to retrieve the next row object of the result.
Row Objects
A row object retrieved from a ResultSet contains the columns specified in the result list of a query. Each row object retrieved from a ResultSet must be closed when it is no longer needed. A row object contains the methods to find out the data type of each of its columns, whether a column has a value, and the methods to retrieve a column's value by its data type.
The label of a column in the result list is used to access the data for each column. The columns of a row are accessed by using the label specified for the column in the result list using ActiveSpaces. For example,
SELECT col1 AS myname FROM table1
where myname is used as the column label.
If a label was not specified for a column in the result list, the column's name from the table is used as
If a label was not specified and the column of the result list is an expression, the expression string is used as the label. For example,
SELECT col1, date('now') FROM table1 WHERE col1 <= 10
where the expression string, date('now'), is used as the column label.
When a label is specified for a column, or the column is an expression, the label or expression must be used exactly as it was specified in the original query string and is case-sensitive. If a label was not specified for a column and the column is from the table, the label is not case-sensitive.
ResultSet MetaData
The result of running a SELECT statement using the executeQuery() method is a ResultSet object, which contains the resulting rows of the SELECT statement. Information about the rows in the ResultSet is obtained when the statement is first created by invoking the getResultSetMetadata() method of the Statement object.
This information includes the number of columns in a result row, each column's data type, the label given to the column, the name of the column from the table, and the name of the table for each column.
If a label was not specified for a column, the name of the column from the table is used as the label. If a column is not from a table, but is an expression that is calculated as part of the result, the entire
expression string is used as the label. It is always safest to access a column of a ResultSet by its label as a ResultSet column always has a label, but might not necessarily have a name from a table.
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.
Your program needs to get a reference to a valid connection object if you do not already have one.
For convenience, a program can use a table accessor method 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 must destroy the grid metadata object after it has finished using it. 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).