Using the TIBCO ActiveSpaces Operators

Note

This topic describes the StreamBase operators that work with ActiveSpaces 4.0 and later.

If you are looking for legacy ActiveSpaces 2.x support, see Using the TIBCO ActiveSpaces 2 Operators.

This topic describes how to use the TIBCO ActiveSpaces® operators to interact with an ActiveSpaces data grid, and explains how to configure the operators' Properties views. These operators work only with ActiveSpaces version 4.0 and later.

Introduction

The TIBCO ActiveSpaces connectivity solution is implemented as a suite of global Java operators that allow a StreamBase application to connect to an ActiveSpaces data grid, and that allow the application to perform operations on the tables and rows of that grid.

In addition to the ability to get, put and delete tuples to and from a data grid, a number of other operations are supported using the appropriate operator. The complete list of supported operations and operators is described below.

Placing ActiveSpaces Operators on the Canvas

The ActiveSpaces operators are members of the Java Operator group in the Palette view in StreamBase Studio. Select the operators from the Insert an Operator or Adapter dialog. Invoke the dialog with one of the following methods:

  • Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.

  • Click in the canvas where you want to place the operator, and invoke the keyboard shortcut O V

  • From the top-level menu, invoke Insert>Operator>Java.

From the Insert an Operator or Adapter dialog, select one of the following ActiveSpaces-related operators and double-click or press OK:

  • TIBCO ActiveSpaces Put, which adds or updates a row to a table.

  • TIBCO ActiveSpaces Batched Put, which adds or updates multiple rows in a single call. Note that this operator cannot be used in transacted sessions.

  • TIBCO ActiveSpaces Get, which retrieves a row from a table.

  • TIBCO ActiveSpaces Batched Get, which retrieves multiple rows from a table in a single call. Note that this operator cannot be used in transacted sessions.

  • TIBCO ActiveSpaces Delete, which removes a row from a table.

  • TIBCO ActiveSpaces Batched Delete, which removes multiple rows from a table in a single call. Note that this operator cannot be used in transacted sessions.

  • TIBCO ActiveSpaces Query, which can send arbitrary SQL queries to the data grid.

  • TIBCO ActiveSpaces Listen, which monitors events corresponding to changes in a table (or specific rows of a table).

  • TIBCO ActiveSpaces Transaction Operations, which performs Commit and Rollback operations on the data grid.

  • TIBCO ActiveSpaces Control, which allows your StreamBase application to connect to and disconnect from an ActiveSpaces data grid. Once this operator emits a tuple to indicate a connection has been established, other operators linked to the same DataGrid definition (that is, have the same entry specified in their DataGrid Definition property) can begin performing operations. You can also use this operator to retrieve the metadata for the connected data grid or one of its tables.

Prerequisites

In order to run correctly, the operators assume the following to be properly set up:

  • The machine running your StreamBase application must have a copy of ActiveSpaces 4.0 or later installed.

  • Your application must be configured to locate and load the required ActiveSpaces libraries. Open src/main/configurations/engine.conf and adjust paths based on your own install locations for TIBCO ActiveSpaces and TIBCO FTL. See Engine Configuration for details.

  • At runtime, the operators expect the configured data grid to be running and ready to accept connections at the configured URLs. Configuration of your ActiveSpaces operators is discussed in the next section.

Adapter Configuration

The different ActiveSpaces operators share a connection to the same data grid (and optionally the same table), provided they are configured to do so. Each operator lists the data grids available in corresponding combo box settings (see Properties: Operator Properties Tab). The lists are specified in a dedicated section of the application's adapter configuration file. The following example is the ActiveSpaces.conf file used in the ActiveSpaces Operator sample:

name = "ActiveSpaces.conf"
type = "com.tibco.ep.streambase.configuration.adapter"
version = "1.0.0"
configuration = {
        
  // An adapter group type defines a collection of EventFlow adapter 
  // configurations, indexed by adapter type.
  AdapterGroup = {
        
    // A collection of EventFlow adapter configurations, indexed by adapter type. 
    // This key is required and must contain at least one configuration.
    adapters = {
  
      // The root section for an EventFlow adapter configuration.
      activespaces = {
        
        // Section list. This key is optional and has no default value.
        sections = [
        
          // A configuration for an EventFlow adapter named section.
          {     
            // Section name. The value does not have to be unique; that is, 
            // you can have multiple sections with the same name in the  
            // same array of sections. This key is required.
            name = "datagrid-definition"
            // Section property bag. All values must be strings. This 
            // key is optional and has no default value.
            settings = {
              id = "TestGrid"
              binding-strategy = "-1"
              connect-numresponses = "-1"
              connect-proxynames = ""
              connect-retries = "-1"
              connect-wait-time-seconds = "-1"
              connection-timeout-seconds = "-1"
              datagrid-id = "_default"
              datagrid-secondary-url = "http://localhost:8081"
              datagrid-url = "http://localhost:8080"            
              transacted-session = "false"
              datagrid-id = "_default"
              connect-numresponses = "-1"
              connect-proxynames = ""
              authentication-username = "YourUserName"
              authentication-password = "YourPassword"
              trust-all = "true"
              trust-filename = "C:/filename"
            }
          }
        ]
      }
    }
  }
}

In each section named datagrid-definition, the value of the id setting identifies this particular section (in other words, this particular data grid definition) and will be listed in the Operator Properties tab's DataGrid Definition drop-down setting in each operator's Properties view. Multiple operators can be made to share a single connection to a data grid by using the same value for this DataGrid Definition setting.

Note

Do not confuse the id setting discussed above with the datagrid-id setting, which is used to denote the name of the target data grid as it is named on the ActiveSpaces server.

A best practice is to define your data grid before placing operator instances on the canvas, so that the lists are already available in the Properties view and the operators can be configured right away.

Shared Adapter Configuration Options

This section describes the shared adapter configuration block found in the HOCON file.

If a value is not present, the default is used. Those values listed without a default are required unless otherwise noted.

Property Type Default Description
id string   ALWAYS REQUIRED. This is the ID that will appear in the adapter's DataGrid Definition drop-down.
datagrid-id string _default The name of the ActiveSpaces data grid to which to connect, as defined by the grid's administrator. Leaving this null or undefined will cause the adapter to connect to the default data grid on the server (which is usually named "_default".)
datagrid-url string   datagrid URL.
datagrid-secondary-url string   datagrid secondary URL, used for failover scenarios. If no secondary URL is specified, only the primary datagrid URL above is used.
transacted-session boolean false transacted session
connection-timeout-seconds int -1 -1 means use default value. Passed along to the ActiveSpaces Connection object as the property Connection.TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT (i.e. "com.tibco.tibdg.timeout", introduced in ActiveSpaces 3.0.0)
connect-wait-time-seconds int -1 -1 means use default value. Passed along to the ActiveSpaces Connection object as the property Connection.TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME (i.e. "com.tibco.tibdg.connectwaittime", introduced in ActiveSpaces 3.2.0)
connect-retries int -1 -1 means use default value. Passed along to the ActiveSpaces Connection object as the property Connection.TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES (i.e. "com.tibco.tibdg.realmconnectretries", introduced in ActiveSpaces 4.1.0)
binding-strategy int -1 Binding strategy-related settings. -1: default value, 0: RANDOM, 1: NAMED.
connect-numresponses int -1 Binding strategy-related settings. -1: default value. RANDOM binding-strategy only, otherwise ignored.
connect-proxynames int   Pipe-delimited list of proxy names to use. NAMED binding-strategy only, otherwise ignored. 1: NAMED.
authentication-username string   authentication username
authentication-password string   authentication password
trust-all boolean true If true, no authentication is used. If false, trust-filename (see below) is required to be appropriately set.
trust-filename string   The full path to the FTL realm server's trust file, used for authentication.

Engine Configuration

In addition to the adapter configuration discussed above, use a configuration file of type sbengine.conf to configure lines like those below to point to your ActiveSpaces installation. The following example is the file used in the ActiveSpaces Operator sample:

name = "activespaces-adapter"
version = 1.0.0
type = "com.tibco.ep.streambase.configuration.sbengine"

//
// Configuration for ActiveSpaces adapter.  This configuration 
// assumes that AS 4.x is installed into /opt/tibco/as or c:/TIBCO/as.
// This can be overridden using the TIBDG_ROOT substitution 
// variable.
//
configuration =
{
    StreamBaseEngine =
    {
        //
        //    Configure native AS library path for each platform
        //
        externalNativeLibraryPath =
        {        
            windows_x86_64 =
            [
                "${TIBDG_ROOT:-c:/TIBCO/as/4.0}/bin"
            ]
            //osx_x86_64 =
            //[
            //    "${TIBDG_ROOT:-/opt/tibco/as/4.0}/lib"
            //]    
            //linux_x86_64 = 
            //[
            //    "${TIBDG_ROOT:-/opt/tibco/as/4.0}/lib"
            //]
        }
        externalNativeLibraryPath =
        {       
            windows_x86_64 =
            [
                "${FTL_ROOT:-c:/TIBCO/ftl/5.4}/bin"
            ]
            //osx_x86_64 =
            //[
            //  "${TIBDG_ROOT:-/opt/tibco/ftl/5.4}/lib"
            //] 
            //linux_x86_64 = 
            //[
            //  "${TIBDG_ROOT:-/opt/tibco/ftl/5.4}/lib"
            //]
        }
        //
        // Add ActiveSpaces JAR to class path
        //
        externalClassPath =
        [
            "${TIBDG_ROOT:-c:/TIBCO/as/4.0}/lib/tibdg.jar"
        ]
        
        jvmArgs =
        [
            "-XX:+UseParNewGC",
            "-XX:+UseConcMarkSweepGC",
            "-XX:+CMSParallelRemarkEnabled"
        ]
    }
}

Properties View Settings

This section describes the properties you can set for a TIBCO ActiveSpaces operator, using the various tabs of the Properties view in StreamBase Studio.

Properties: General Tab

Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Operator Properties Tab

This section describes the properties on the Operator Properties tab in the Properties view for the ActiveSpaces operator. Enter all text fields as string literals, not as expressions.

Common Properties

All the ActiveSpaces operators have a common set of properties:

ActiveSpaces Configuration

The Edit button is a shortcut to the StreamBase Configuration File Editor, used for adapter configurationor converting an existing application's adapter-configurations.xml file to HOCON format.

DataGrid Definition

Specifies the ID of the connection definition describing the ActiveSpaces data grid to which to connect. The DataGrid Definition drop-down list of each operator will contain a list of available definitions of data grids from which to choose, as specified in the adapter configuration file (see Adapter Configuration). This setting is required.

Note

This identifier is only used to specify which data grid definition to use among those listed in the adapter configuration file and is not related to the ActiveSpaces Data Grid IDs used by the ActiveSpaces realm itself.

Log Level

Use this to set the operator to produce more or less verbose console output, independent of the STREAMBASE_LOG_LEVEL global setting. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Operator-Specific Properties

In addition to the common properties listed above, some operators also have some properties of their own:

Get and Batched Get Operators Properties
Table Name

The name of the table from which to get rows. This setting is required.

Enable Status Port

When checked, an additional output port is added to receive status tuples.

Put and Batched Put Operators Properties
Table Name

The name of the table to which to put or update rows. This setting is required.

Enable Status Port

When checked, an additional output port is added to receive status tuples.

Delete and Batched Delete Operators Properties
Table Name

The name of the table from which to delete rows. This setting is required.

Enable Status Port

When checked, an additional output port is added to receive status tuples.

Query and Listen Operators Properties
Enable Status Port

When checked, an additional output port is added to receive status tuples.

Control Operator Properties
Connect On Startup

Specifies whether to attempt to connect to the data grid when the application is started.

Properties: Edit Schema Tab

For general instructions on using the Edit Schema tab, see the Properties: Edit Schema Tab section of the Defining Input Streams page.

Each operator has one output port (plus, in the case of the Get, Put, Delete (and their Batched variants), Listen and Query operators, an optional Status port). Several of these operators have a tuple field called row on those output streams, used to represent a row in an ActiveSpaces table (the Batched Get, Put and Delete adapters have a list of such rows). The schema for this tuple field must be defined on this tab. Furthermore, because these fields are meant to represent the content of an ActiveSpaces row, this schema must match that used by the ActiveSpaces table to which the operator is connected. In this context, "must match" means that both ActiveSpaces and StreamBase schemas must contain fields with the same names, and those fields must have compatible types. The list of compatible types between StreamBase and ActiveSpaces is specified in Type Mappings.

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

Properties: Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Input Ports

Each operator has only one input port, used to receive commands describing an operation to be performed on the ActiveSpaces data grid (such as Get, Put, Connect, and so on). The schema for each operator is different because different operations require different parameters.

Get Operator

Field Name Field Type Description
passthrough <any type> OPTIONAL. This field can have any type and is ignored during the execution of this operation and is simply passed through to the output port as part of the input tuple. This can be helpful to attach a unique identifier to the command tuple and have it propagated downstream.
All other fields   Specifies the key(s) of the row to retrieve. The names and types of these fields should match that of their corresponding key column of the ActiveSpaces table.

Batched Get Operator

Field Name Field Type Description
rows list<tuple> Specifies the key(s) of the rows to retrieve. The names and types of the fields in the tuples of this list should match that of their corresponding key column in the ActiveSpaces table.
passthrough <any type> OPTIONAL. This field can have any type and is ignored during the execution of this operation and is simply passed through to the output port as part of the input tuple. This can be helpful to attach a unique identifier to the command tuple and have it propagated downstream.

Delete Operator

Field Name Field Type Description
passthrough <any type> OPTIONAL. This field can have any type and is ignored during the execution of this operation and is simply passed through to the output port as part of the input tuple. This can be helpful to attach a unique identifier to the command tuple and have it propagated downstream.
All other fields   Specifies the key(s) of the row to delete. The names and types of these fields should match that of their corresponding key column of the ActiveSpaces table.

Batched Delete Operator

Field Name Field Type Description
rows list<tuple> Specifies the key(s) of the rows to delete. The types of the fields in the tuples of this list should match the type of their corresponding key column in the ActiveSpaces table.
passthrough <any type> OPTIONAL. This field can have any type and is ignored during the execution of this operation and is simply passed through to the output port as part of the input tuple. This can be helpful to attach a unique identifier to the command tuple and have it propagated downstream.

Put Operator

Field Name Field Type Description
_ttl long OPTIONAL. This field, when present and non-null, can be used to specified the time-to-live value (in seconds) of this row.
passthrough <any type> OPTIONAL. This field can have any type and is ignored during the execution of this operation and is simply passed through to the output port as part of the input tuple. This can be helpful to attach a unique identifier to the command tuple and have it propagated downstream.
All Other Fields   Every other field in the tuple is assumed to represent one column in the row to add or update in the table.

Batched Put Operator

Field Name Field Type Description
rows list<tuple> Specifies the column values of the rows to delete. The names and types of the fields in the tuples of this list should match that of their corresponding columns in the ActiveSpaces table. In addition, the schema may include an extra field of type long named _ttl to specify the time-to-live of each row.
passthrough <any type> OPTIONAL. This field can have any type and is ignored during the execution of this operation and is simply passed through to the output port as part of the input tuple. This can be helpful to attach a unique identifier to the command tuple and have it propagated downstream.

Listen Operator

Field Name Field Type Description
action string REQUIRED. The type of action to perform. One of start, stop or stopall.
listenerID string REQUIRED for start and stop actions. A user-assigned and unique ID designed to identify this subscription. All tuples issued by the operator as a result of row updates on the table will include this ID. Furthermore, this ID is required when using the stop action to specify which subscription to stop.
table string REQUIRED for start actions. The name of the table on which to perform this listen operation.
filter string If set when sending a start action, specifies a filter in SQL WHERE syntax (e.g. Column1 = 'MyName') to select the rows of the table on which to listen for changes. If left null, the listen action will be applied to all rows of the table.

For stop and stopall commands this field is ignored.

All Other Fields   Every other field in the tuple is ignored and simply passed along to the output (including output tuples resulting from asynchronous updates as rows change in the table).

Query Operator

Field Name Field Type Description
query string REQUIRED. Specifies the SQL query to execute (for example, SELECT * FROM MyTable).
passthrough <any type> OPTIONAL. This field can have any type and is ignored during the execution of this operation and is simply passed through to the output port as part of the input tuple. This can be helpful to attach a unique identifier to the command tuple and have it propagated downstream.

Transactions Operator

Field Name Field Type Description
command string REQUIRED. Either Commit or Rollback, which triggers the corresponding operation on the data grid.
All Other Fields   Every other field in the tuple is ignored and simply passed along to the output.

Control Operator

Field Name Field Type Description
command string REQUIRED. The action to perform. One of Connect, Disconnect, GetGridMetadata or GetTableMetadata.
param1 string REQUIRED for the GetTableMetadata action. Specified the table for which to fetch metadata.
All Other Fields   Every other field in the tuple is ignored and simply passed along to the output.

Output Ports

Every operator has only one fixed output port, used to deliver the results of executing operator commands. The Get, Put, Delete and Query operators additionally have one optional Status output port if the operator's Enable Status Port option is checked.

Results Port

Get, Put, and Query Operators

All three of these operators have the same schema for emitting the results of their operations.

Field Name Field Type Description
input tuple Contains the input tuple that triggered the operation.
row tuple Contains one row returned by the executing operation. If the operation returns multiple rows, one tuple will be emitted for each row. Once all rows are processed in this way, a marker tuple is emitted with this field set to null to indicate the operation has completed.

Delete Operator

Field Name Field Type Description
input tuple Contains the input tuple that triggered the operation.

Batched Get Operator

Field Name Field Type Description
input tuple Contains the input tuple that triggered the operation.
numberOfFailures int 0 if all rows were successfully retrieved. Otherwise set to the number of rows that could not be fetched. The rows fields (see below) will only be set if this field is 0.
rows list<tuple> Contains the rows returned by the batched get operation. If numberOfFailures > 0, this field will be left null. Note that attempting to get a row whose key was not found is not considered an error, and as such the corresponding row returned in this list will simply be null.

Batched Put and Delete Operators

Field Name Field Type Description
input tuple Contains the input tuple that triggered the operation.
numberOfFailures int 0 if all rows were successfully updated (Put Operator) or deleted (Delete Operator). Otherwise set to the number of rows on which the operation was unsuccessful.

Listen Operator

Field Name Field Type Description
input tuple Contains the input tuple that triggered the operation.
listenerID string The ID of the listener that caused this update tuple. This corresponds to the listenerID field given to the operator in the start command, as described in Listen Operator.
eventType string Describes the type of event that triggered this listener update. One of PUT, DELETE, EXPIRED, ERROR.
oldrow tuple For PUT and DELETE event types, this contains the row as it was before the event happened. For other event types this field will be null.
newrow tuple For PUT events, this contains the row as it is after this event. For other event types this field will be null.
errorCode int For ERROR events this contains a numeric code identifying the type of error that occurred. For other event types this field will be null.
errorDescription string For ERROR events this contains a textual description of the error that triggered this event. For other event types this field will be null.

Status Port

The Status Port is the only output port for the Control and Transactions operator, and optionally the second port on the other operators (if their Enable Status Port property is set). In all cases the schema is the same:

Field Name Field Type Description
Status string Describes this event. Possible values include: Connected, Disconnected, Success, Error.
Time timestamp The time at which this tuple was emitted.
Info list<tuple> This is an all-purpose field used to convey additional information describing this event in the form of tuples containing name and value string fields. For example, in the case of an Error event this might contain one entry with name set to "Reason" and value set to the text describing the error. Wherever possible, one entry describes the input tuple (name = "InputTuple") that triggered this status tuple.

Type Mappings

When operating on ActiveSpaces rows, the fields of the StreamBase tuple and corresponding columns of ActiveSpaces rows are expected to match in the following ways:

  • Tuples and their corresponding rows have the same number of fields,

  • The fields have the same names, and

  • Data types match or can be readily converted.

The table below lists all the type translations supported by the operator.

StreamBase Type ActiveSpaces Type
string string
int, long long

When mapping an ActiveSpaces long to a StreamBase int, some precision may be lost.

double double
timestamp DateTime
blob Opaque
tuple, list, function, capture, boolean Unsupported data types

ActiveSpaces Operator Sample

The StreamBase installation comes with a sample demonstrating the use of this operator. To load the sample in StreamBase Studio, select File>Import Samples and Community Content and look under the Other TIBCO Product Connectivity category for an entry called ActiveSpaces Operator.