Using the TIBCO ActiveSpaces Operators

Note

This topic describes the StreamBase operators that work with ActiveSpaces 3.0 and later, including 4.x.

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 3.0 and later, including 4.x.

Introduction

The TIBCO ActiveSpaces connectivity solution is implemented as a suite of six 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 InsertOperatorJava.

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 rows to a table.

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

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

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

  • 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.

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 3.0 or later installed.

  • Your application must be configured to locate and load the required ActiveSpaces libraries. The procedure for doing this is different when running from StreamBase Studio and when running from the command line.

    • To run from StreamBase Studio, locate your project's top-level node in the Package Explorer view. Right-click the project node and select Build PathConfigure Build Path. On the Libraries tab of the Properties dialog, click the Add External JARs button. This brings up a file browser; navigate to the lib directory of your ActiveSpaces installation, select tibdg.jar, and click OK. Back in the Libraries tab, an entry is now added for tibdg.jar. Expand this node, select Native Library Location, and click the Edit button. Enter the location of the ActiveSpaces lib subdirectory and click OK, and again for the ActiveSpaces bin subdirectory, then click OK to dismiss the Properties dialog.

    • To run from the command line, add the appropriate entries to your project's sbconf file. At minimum, your configuration file must contain lines like those in bold below, edited to point to your ActiveSpaces installation:

      <?xml version="1.0" encoding="UTF-8"?>
      <streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">
        <java-vm>
          <param name="jvm-args" value="            
          -XX:+UseG1GC
          -XX:MaxGCPauseMillis=500
          "/>
          <!-- Edit the following lines to reflect your TIBCO ActiveSpaces 
               installation directory. -->
          <jar file="${TIBDG_ROOT}/lib/tibdg.jar"/>
          <library path="${TIBDG_ROOT}/lib"/>
          <library path="${TIBDG_ROOT}/bin"/>
        </java-vm>
      </streambase-configuration>                 
  • 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.

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 sbd.sbconf file. Here is an example of such a section, containing all possible settings (either active or commented out):

<?xml version="1.0" encoding="UTF-8"?>

<streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">

  <java-vm>
    <param name="jvm-args" value="            
      -XX:+UseParNewGC
      -XX:+UseConcMarkSweepGC
      -XX:+CMSParallelRemarkEnabled
    "/>

    <!-- Edit the following lines to reflect your TIBCO ActiveSpaces 
         installation directory. -->
    <jar file="${TIBDG_ROOT}/lib/tibdg.jar"/>
    <library path="${TIBDG_ROOT}/bin"/>
    <library path="${TIBDG_ROOT}/lib"/>
  </java-vm>

  <adapter-configurations>
        
    <!-- This section contains the configuration settings for the ActiveSpaces 
         operators -->
    <adapter-configuration name="activespaces">
        
      <section name="datagrid-definition">
        <!-- ALWAYS REQUIRED. This is the ID that will appear in the 
             adapter's 'DataGrid Definition' drop-down -->
        <setting name="id" val="TestGrid"/>

        <!-- This is the DataGrid ID as specified by the AS server. 
             Leave empty to connect to the default grid -->                
        <setting name="datagrid-id" val="_default"/>
                
        <setting name="datagrid-url" val="http://localhost:8080"/>
        <setting name="datagrid-secondary-url" val="http://localhost:8081"/>
                
        <setting name="transacted-session" val="false"/>
                
        <!-- -1 means use default value -->
          <!-- 
             When set, these get passed along to the ActiveSpaces Connection 
             object as the following properties:
             connection-timeout-seconds: 
                 Connection.TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT             
                 ("com.tibco.tibdg.timeout", introduced in ActiveSpaces 3.0.0)
             connect-wait-time-seconds:  
                 Connection.TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME   
                 ("com.tibco.tibdg.connectwaittime", introduced in ActiveSpaces 3.2.0)
             connect-retries:            
                 Connection.TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES 
                 ("com.tibco.tibdg.realmconnectretries", introduced in ActiveSpaces 4.1.0)
          -->
        <setting name="connection-timeout-seconds" val="-1"/>
        <setting name="connect-wait-time-seconds" val="-1"/>
        <setting name="connect-retries" val="-1"/>
                
        <!-- Binding strategy-related settings. -1 means use default value -->
        <setting name="binding-strategy" val="-1"/> <!-- 0: RANDOM, 1: NAMED -->
        <setting name="connect-numresponses" val="-1"/> 
            <!-- RANDOM strategy only, otherwise ignored -->
        <setting name="connect-proxynames" val=""/> 
            <!-- Pipe-delimited list of names. NAMED strategy only, otherwise ignored -->

        <!--
        <setting name="authentication-username" val="YourUserName"/>
        <setting name="authentication-password" val="YourPassword"/>
        <setting name="trust-all" val="true"/>
        <setting name="trust-filename" val="C:/filename"/>
        -->
      </section>
        
      <!-- Define other DataGrids here -->
                
    </adapter-configuration>
  </adapter-configurations>
</streambase-configuration>

In each <section name="datagrid-definition">, the <setting id="SomeName"> tag will be listed in the Operator Properties tab of each operator's Properties view.

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.

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.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this operator starts as part of the JVM engine that runs this EventFlow module. If this field is set to No or to a module parameter that evaluates to false, the operator instance is loaded with the engine, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager.

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 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:

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 sbd.sbconf (see Configuration). This setting is required.

Note

This identifier is only used to specify which data grid definition to use among those listed in sbd.sbconf 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, and ALL.

Operator-Specific Properties

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

Get Operator 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 Operator 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 Operator 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 Operator 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 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 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.

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 types of these fields should match the type of their corresponding key column of the ActiveSpaces table.

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 types of these fields should match the type of their corresponding key column of the ActiveSpaces table.

Put 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   Every other field in the tuple is assumed to represent one column in the row to add or update 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. Either Connect or Disconnect.
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.

DeleteOperator

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

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.
info list<string> This is an all-purpose field used to convey additional information describing this event. For example, in the case of an Error event this will contain the text describing the error.
context tuple If this event was generated as a result of a command being sent to the operator, this field will contain the original command 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 FileLoad StreamBase Sample and look under the Extending StreamBase section for an entry called ActiveSpaces Operator.