TIBCO ActiveSpaces®

(1)

Concepts

Software Release 3.5 April 2018

(2)

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE

SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDER SEPARATE SOFTWARE LICENSE TERMS AND IS NOT PART OF A TIBCO PRODUCT. AS SUCH, THESE SOFTWARE ITEMS ARE NOT COVERED BY THE TERMS OF YOUR AGREEMENT WITH TIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES, AND INDEMNITIES. DOWNLOAD AND USE THESE ITEMS IS SOLELY AT YOUR OWN

DISCRETION AND SUBJECT TO THE LICENSE TERMS APPLICABLE TO THEM. BY PROCEEDING TO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THE

FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written

authorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, ActiveSpaces, and FTL are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

TIBCO FTL^® is an embedded and bundled component of TIBCO ActiveSpaces^® - Enterprise Edition.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,

INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

(3)

(4)

About This Product

TIBCO ActiveSpaces^® software is a distributed in-memory data grid product. ActiveSpaces^® features familiar database concepts, high I/O capacity, and network scalability.

ActiveSpaces software features a complete redesign and re-implementation of the product and is straightforward to understand, use, and administer.

Product Editions

ActiveSpaces is now available in a community edition and an enterprise edition.

ActiveSpaces Community Edition

ActiveSpaces - Community Edition is ideal for getting started with ActiveSpaces, for implementing application projects, including proof of concept projects, for testing, and for deploying applications in a production environment. Although the community license limits the number of production instances, you can easily upgrade to the enterprise edition as your use of ActiveSpaces expands.

The community edition is available free of charge. It is a full installation of the ActiveSpaces product.

The limitation of using the community edition is that the users can run up to 25 nodes (a total of the copyset nodes or proxies in your data grid).

ActiveSpaces - Community Edition is compatible with both the enterprise and community editions of TIBCO FTL^®.

ActiveSpaces Enterprise Edition

ActiveSpaces is now available in a community edition and an enterprise edition.

ActiveSpaces - Enterprise Edition is ideal for all application development projects, and for deploying and managing applications in an enterprise production environment. It includes all features presented in this documentation set, and access to TIBCO Support. Choose the enterprise edition for production deployments with more than 25 nodes (a total of the copyset nodes or proxies in your data grid) and for enterprise monitoring using dashboards.

ActiveSpaces - Enterprise Edition depends on the enterprise edition of TIBCO FTL.

(6)

TIBCO Documentation and Support Services

How to Access TIBCO Documentation

Documentation for TIBCO products is available on the TIBCO Product Documentation website, mainly in HTML and PDF formats.

The TIBCO Product Documentation website is updated frequently and is more current than any other documentation included with the product. To access the latest documentation, visit https://

docs.tibco.com.

Product-Specific Documentation

Documentation for TIBCO ActiveSpaces^® is available on the TIBCO ActiveSpaces^® Product Documentation page. The following documents for this product can be found on the TIBCO Documentation site:

● TIBCO ActiveSpaces^® Concepts

● TIBCO ActiveSpaces^® Administration

● TIBCO ActiveSpaces^® Release Notes

● TIBCO ActiveSpaces^® Installation

● TIBCO ActiveSpaces^® API Reference

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

● For an overview of TIBCO Support, visit http://www.tibco.com/services/support.

● For accessing the Support Knowledge Base and getting personalized content about products you are interested in, visit the TIBCO Support portal at https://support.tibco.com.

● For creating a Support case, you must have a valid maintenance or support contract with TIBCO.

You also need a user name and password to log in to https://support.tibco.com. If you do not have a user name, you can request one by clicking Register on the website.

How to Join TIBCO Community

TIBCO Community is the official channel for TIBCO customers, partners, and employee subject matter experts to share and access their collective experience. TIBCO Community offers access to Q&A forums, product wikis, and best practices. It also offers access to extensions, adapters, solution accelerators, and tools that extend and enable customers to gain full value from TIBCO products. In addition, users can submit and vote on feature requests from within the TIBCO Ideas Portal. For a free registration, go to https://community.tibco.com.

(7)

Product Overview

TIBCO ActiveSpaces^® software is a distributed in-memory data grid product. ActiveSpaces^® features familiar database concepts, high I/O capacity, and network scalability.

Motivation

The rise of big data and the internet of things places new and larger demands on databases. Traditional relational database implementations can exhibit bandwidth bottleneck as more frequent queries with larger result sets overwhelm their I/O capacity.

With ActiveSpaces data grids, you can scale I/O capacity by adding host computers to the grid.

Redesigned from the Ground Up

ActiveSpaces software features a complete redesign and reimplementation of the product and is straightforward to understand, use, and administer.

Database

Use ActiveSpaces data grid software as a system of record. An ActiveSpaces data grid provides a consistent, fault-tolerant system that supports mixed read and write workloads in a scalable manner.

ActiveSpaces software presents application programmers with familiar database concepts, such as tables, rows, and columns. Programs can insert, delete, and retrieve individual rows. Programs can query for rows that match a specified pattern of data.

Administrators define and configure a data grid. Administrators deploy and manage the component processes that implement the data grid. Administrators define tables, indexes, and their parameters.

Process Memory Storage

ActiveSpaces software caches data in process memory for fast read access, and writes data to persistent storage for safety.

Communications

ActiveSpaces software uses fast TIBCO FTL^® messaging software in these key roles:

● Communication between application programs and the data grid

● Data type foundation in application programs and the data grid

● Internal communication among data grid component processes

● Configuration, monitoring, and management of data grid components For the minimum supported release of TIBCO FTL^® software, see the ^readme file.

(8)

Components

ActiveSpaces software consists of these primary components.

● State Keeper executable binary file

● Node executable binary file

● Proxy executable binary file

● API libraries

● Administration tool executable binary file

In addition, the executable components of this product require a TIBCO FTL realm server to supply configuration data.

Communication among Components

The diagram shows the components of a data grid and their communication paths.

Programmers include API calls within application programs.

(9)

The API communicates with proxy processes to request database queries and operations.

Proxies communicate with node processes to execute database operations on behalf of application programs.

A state keeper process supplies critical information to node and proxy processes.

A TIBCO FTL realm server supplies data grid configuration definitions to all the preceding components.

Administrators use ^tibdg to define the data grid configuration, check the status of component processes, and manage those processes.

(10)

Programming Concepts

These concepts and definitions pave the way to a more detailed understanding of applications programming with ActiveSpaces software.

Data Grid

A distributed database, including all the component processes that implement it.

Connection

An application program connects to a data grid. A connection object is analogous to a traditional database connection.

Session

An application program interacts with a data grid through one or more session objects. Each session insulates the data grid interactions within one program thread from the interactions in other threads.

A session can be transacted or non-transacted. Get, put, and delete operations in a transacted session occur within a transaction, and do not take effect until the program explicitly commits the transaction.

Table

An ActiveSpaces data grid organizes and presents data as rows in tables, like a traditional relational database.

Administrators define tables within the data grid.

Programs can get a row from a table, put a row into a table, and delete a row from a table.

Programs can query a table for the rows that match a filter.

Primary Key

Each table distinguishes a primary key, or more briefly, the key.

Values of the key are unique: no two rows in a table have the same key value.

Secondary Index

A table can have zero or more secondary indexes, which facilitate queries.

Iterator

An iterator presents an application program with the results of a data grid query, one row at a time.

Structuring Programs

These steps outline the main structural components of most application programs that access a ActiveSpaces data grid.

Procedure

Task A Initializing ActiveSpaces Objects 1. Initialize the ActiveSpaces library.

2. Connect to a data grid.

3. Create session objects.

See Session.

4. Open table objects.

See Table.

(11)

Task B Data Grid Operations

5. Access the data grid using methods of a table object.

See Table Operations.

Task C Clean-Up 6. Close table objects.

7. Destroy session objects.

8. Close the data grid connection object.

Session

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.

(12)

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.

(13)

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

(14)

It is the responsibility of the program to destroy that grid metadata when finished with it. If

updated grid metadata is needed, the existing metadata object should be destroyed another request should 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).

Querying a Data Grid Table

Application programs have the following options to query tables in a data grid.

The following options are available:

● Table iterator

A table iterator is used when you have created a table object and need to iterate over all of the rows or a specific subset of the rows in the table.

You can create an iterator to query the contents of the table and then iterate over the query results.

The contents of the query results for the iterator are controlled by the use of a filter string when the iterator is first created. Using a NULL filter string when creating the iterator returns all of the rows of the table.

To restrict the query results to a subset of the rows of a table, provide a non-NULL filter string which contains a filter expression as described in Query Language.

For more information, see Table Iterator.

● Session statement

A statement is created from a session object and is not tied to any one particular table. A session statement is created using a SQL SELECT string and the table for the query is determined by parsing the SELECT string. The SQL SELECT string supported has the form:

SELECT * FROM table_name WHERE filter

The syntax for a filter string is the same as for table iterators with the exception that parameter markers using '?' are supported. Parameter markers allow you to optimize the scenario where you want to run the same query several times with different values in a filter expression. For example,

SELECT * FROM mytable WHERE key > ?

Before a query is executed for the session statement, you must provide values for all of the

parameter markers in the SQL SELECT string by calling the appropriate tibdgStatement_SetXXX

method for each parameter value depending upon the data type of the value.

The parameter number is required when calling the ^SetXXX method with the first parameter in the statement being numbered 1.

For more information, see Session Statement.

(15)

The advantages of using a session statement over a table iterator:

● The same query can be run multiple times using a single statement object.

● You can use parameter markers to vary the results of your query each time it is run.

● You do not have to create a table object before you can query a table.

Statements and result sets should be created on a non-transacted session because they do not interact with the commit and rollback APIs on a transacted session.

Table Iterator

Application programs can query a data grid table to retrieve a subset of its rows.

Procedure

1. Formulate a filter string that specifies the query, that is, the constraints that determine the rows that the query retrieves.

See Query Language.

2. Call the create iterator method of the table object.

Supply the filter string as an argument.

The API library sends the filter string to a proxy process, which retrieves matching rows from the data grid, and funnels them to the application through the iterator object.

3. Iterate over the resulting rows.

The iterator presents the rows in an order that is deterministic and repeatable, however, the application program cannot influence that order.

4. Close the iterator object.

Closing the iterator releases the resources that hold the query results within the component processes of the data grid.

Session Statement

A session statement is created using a SQL SELECT string and the table for the query is determined by parsing the SELECT string.

Procedure

1. Formulate a SQL SELECT string for the query you want to use to retrieve rows from a table.

2. Call the create statement method of the session object.

Supply the SQL SELECT string as an argument.

3. Call the statement methods to set the parameter values for the query.

4. Run the query by calling the statement method to execute the query.

(16)

Query Language

ActiveSpaces software supports a restricted subset of the SQL query language.

To specify a query, supply a filter expression. For example:

column_name > 100

Queries return all columns of a table rather than a subset of specific columns. That is, all queries implicitly begin with SELECT * FROM table_name WHERE. Nonetheless, programs do not specify this string, they specify only the filter that would follow the WHERE keyword.

Filter expressions are not case sensitive. Query evaluation converts keywords and column names to lower case before evaluation.

Filter Expression Syntax Reference

Query filter expressions have the following form.

[ NOT ] column operator value { [ AND | OR ] [ NOT ] column operator value }*

The following sections describe further details of filter expression syntax and semantics.

Column

column can be the name of any column defined in the table.

Operator

operator can be any operator in the following table:

Operator

=

==

IS

!=

<>

IS NOT

>

<

>=

<=

ISNULL IS NULL

Tests that the row does not contain a value in this column.

(17)

Operator NOTNULL NOT NULL IS NOT NULL

Tests that the row contains a value in this column.

BETWEEN value_1 and value_2 Requires two values,

separated by the

keyword and. The range includes the end values.

IN ( value [, value ]* ) Requires a set of values,

separated by commas, surrounded by parentheses.

Value

value can be any value of the same data type as the column's data type.

Surround string values in single quote characters: for example, ^{'My Value'}. Conjunctions

● AND joins multiple conditions. The overall condition is true if and only if every individual condition is true.

● OR joins multiple conditions. The overall condition is true if at least one of the individual conditions is true.

Negation

NOT reverses the boolean value of a logical expression that follows it. For example, you can use the operators NOT BETWEEN and NOT IN.

You can also precede an operator clause with NOT, for example:

NOT column operator value

Order of Operations

Order of operations is similar to SQL. NOT takes precedence over conjunctions. The conjunction AND takes precedence over OR.

You can use parentheses to group expressions, overriding that order.

(18)

Unsupported

LIKE GLOB UNIQUE EXISTS ORDER BY GROUP BY LIMIT

Special Characters in Column Names

Column names with special characters require special treatment.

It is good practice for administrators to define column names that follow the SQL identifier rules. (See

"Column Names" in TIBCO ActiveSpaces Administration.)

Nonetheless, in some situations, a table might contain non-standard column names. For example, a table copied from a legacy data base might have columns with names that contain a space character.

If you must refer to non-standard column names in a filter expression, surround the column name with any of the following escape characters:

Technique Example

Single quotes 'column name'

Double quotes "column name"

Escaped double quotes \"column name\"

Square brackets [column name]

Back ticks (accent grave) `column name`

Efficiency of Filters

The efficient use of queries depends in part upon the way you construct filter expressions, and in part upon the way the administrator constructs table indexes. Programmers and administrators can use these rules of thumb to help promote efficiency and high performance.

Programmers: consult your data base administrator for information about the definition of indexes.

Keys and Indexes

Rule of Thumb: Construct filter expressions in which every conjunct refers to a key or index.

A filter expression that does not refer to a key or index results in a full table scan, which is inefficient.

A compound filter expression, which combines conjuncts using AND or OR, results in a full table scan for each conjunct that does not refer to a key or index.

(19)

Left-Most Columns

Rule of Thumb: Construct filter expressions that reference the left-most columns of an index using the predicates =, ==, <=, >=, <, >, IN, or BETWEEN.

When an index includes more than one column, the administrator has defined them in a specific order:

from left to right. Queries with filter expressions that refer to the left-most column of an index can be more efficient than filter expressions that skip the left-most column and instead refer only to columns to its right. Similarly, queries with filter expressions that refer to the left-most two columns can be even more efficient. Queries can achieve maximum efficiency when they use filter expressions that refer to all the columns of an index.

In contrast, omitting the left-most column from the filter expression results in a full table scan, which is the least efficient.

The order in which the columns appear within the filter expression does not affect efficiency. Only the order of columns when defining the index matters.

Avoid Left-Most NOT

Rule of Thumb: Do not construct filter expressions that reference the left-most columns of an index using the predicates NOT, IS NOT, !=, <>, IS, ISNULL, IS NULL, NOTNULL, NOT NULL, and IS NOT NULL.

In contrast to the rule of left-most columns, filter expressions that reference the left-most columns with these operators have the opposite effect: to guarantee a full table scan, which is the least efficient.

The presence of the predicate IS in this list could be counterintuitive. See the next rule.

However, this rule does not imply that predicates in the NOT family are always inefficient. For example, a query can still be efficient if it obeys the left-most columns rule and also tests columns further to the right using NOT. For example, if the administrator defined an index on the columns

lastname and ^firstname, then this filter expression can be efficient:

lastname='Smith' and firstname IS NOT 'Dan'

Avoid IS

Rule of Thumb: Use the predicates = or ==, rather than IS.

Even though the predicates =, ==, and IS are semantic synonyms, the behavior of IS differs dramatically. Namely, IS guarantees a full table scan, which is the least efficient.

Bound Ranges from Both Ends

Rule of Thumb: When using the predicates > or >=, which specify a lower limit on a column's value, also include the opposite predicates, < or <=, to specify an upper limit on the same column.

A query searches an index from its lower limit to its upper limit. If you omit the upper limit, the query

(20)

Snapshots are inexpensive if the table data changes slowly, but can become expensive if the data changes rapidly. To limit memory growth within data grid components, administrators can limit the number of concurrent snapshots.

Transaction Isolation

ActiveSpaces enforces the highest level of transaction isolation: serializable. As a result, serialization can delay database operations as transactions wait for other transactions to commit or roll back.

ActiveSpaces uses a pessimistic transaction model: blocking any operations that could violate database consistency or isolation. For example, when an operation in transaction A refers to table row R, and an operation in a second transaction B also refers to row R, then the second operation blocks until

transaction A either commits or rolls back. Similarly, an operation within a transaction can block operations in non-transacted sessions.

Listeners

Listeners are used to monitor events corresponding to changes in a table.

Using listeners you can either monitor the contents of a specific table or a subset of rows in a specific table.

For example, your application could track the table containing customer data. Specifically, track the activity in a particular geographic region; to know when new customers are added or deleted, or when customers move to another region.

An event indicates that the data in a table has changed.

An event is of type:

● PUT: Indicates new data has been added to the table.

PUT events have a current value which is a copy of the row that was PUT into the table. If the PUT operation replaces an existing row, the event additionally has a previous value, which is a copy of the row prior to the PUT operation.

● DELETE: Indicates that a row has been deleted from the table. DELETE events have a previous value, which is a copy of the row prior to the DELETE operation.

● ERROR: Indicates that something has happened in the system that means the flow of events are disrupted. ERROR events have an error code and an error description. The application should destroy the table listener. Depending on the error code, it might or might not make sense for the application to recreate the table listener. The ActiveSpaces API documentation provides more details on the specific error codes that are possible.

● EXPIRED: Indicates that a row has expired. When rows are removed from a table due to expiration, table listeners on the table receive EXPIRED events, if the expired rows match the listeners’ filters.

When creating a table listener you must specify the table that is the source of the events of interest and a callback function that is invoked when events are delivered to the application. The callback function executes in a thread that is internal to the ActiveSpaces client library and is expected to complete in a timely fashion. The client library retains ownership of the events and the rows they contain so any data that is required outside of the callback must be copied and managed by the application itself.

Filtering Events

When the table listener is being created you can optionally specify a filter string to further narrow the scope of events received.

The filter string specifies the criteria that events must match in order for them to be delivered to the table listener. The filter is equivalent to the WHERE clause of an SQL query and is applied to both the current and previous values for the row that has changed. If either the current or previous value matches the filter, then the event is delivered to the listener.

(21)

For example, in a table containing customer data with a column called state, the filter state = “CA”

limits the events delivered to only those involving customers in California.

(22)

Development Environment

In many enterprises programmers act as administrators during the development and test phases of a project. To develop and test application programs that use ActiveSpaces software, deploy the following processes.

● Realm server One process

● State keeper One process

● Node One process

● Proxy One process

● Your application programs One or more processes, as appropriate

In a development environment you can run all of these processes on the same host computer.

Sample Scripts

Refer to the TIBCO_HOME/as/<version>/samples/readme.md before using the sample scripts.

The following scripts are available:

● TIBCO_HOME/as/<version>/samples/scripts/as-start defines a simple data grid and starts its component processes.

● TIBCO_HOME/as/<version>/samples/scripts/as-stop stops those component processes.

Copyset Partitioning Test

To test the partitioning of data rows into copysets, you can define a data grid with more than one copyset, each with its own node process running on a separate host computer.

For more information see "Defining a Data Grid" in the TIBCO ActiveSpaces^® Administration guide.

Sample Docker Environment

A sample docker-compose environment is provided to demonstrate how to deploy an ActiveSpaces data grid in Docker. For more information, see TIBCO_HOME/as/<version>/samples/docker/

README.md.

TIBCO ActiveSpaces®

Concepts

Contents

About This Product

TIBCO Documentation and Support Services

Product Overview

Components

Programming Concepts

Structuring Programs

Session

Table

Metadata

Querying a Data Grid Table

Table Iterator

Session Statement

Query Language

Transaction Isolation

Listeners

Filtering Events

Development Environment