Using the TIBCO ActiveSpaces Legacy Operator

Contents

Introduction
Properties View Settings
Input Ports
Output Ports
Commands And Results
Type Mappings
Legacy ActiveSpaces Operator Sample
Related Topics

Note

This document describes usage of the deprecated legacy version of the ActiveSpaces operator, which was superseded in Release 7.5.0 by a new set of ActiveSpaces operators. To use the most current version, see Using the TIBCO ActiveSpaces Operators.

This topic describes how to use the TIBCO ActiveSpaces® legacy operator. It explains how to configure the operator's Properties view and how to use it to interact with an ActiveSpaces Metaspace.

Introduction

The TIBCO ActiveSpaces legacy operator connects to an ActiveSpaces Metaspace and Space and allows your StreamBase application to exchange tuples seamlessly with the Space. Depending on your operator's configuration settings, it will act either as a leech or a seeder within the Space, and may connect to the Space as a remote client.

In addition to the ability to get, take, and put tuples to and from a Space, a number of other operations are also supported. The complete list of supported operations is given in this document.

Placing an ActiveSpaces Legacy Operator on the Canvas

The ActiveSpaces operator is a member of the Java Operator group in the Palette view in StreamBase Studio. You select the operator 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 that opens, select ActiveSpaces and double-click or press OK.

Prerequisites

In order to run correctly, the operator assumes the following to be properly set up:

  • The machine running your StreamBase application must have a copy of ActiveSpaces 2.1 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 Path → Configure 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 as-common.jar, and click OK. Back in the Libraries tab, an entry is now added for as-common.jar. Expand this node, select Native Library Location, and click the Edit button. Enter the location of the ActiveSpaces lib subdirectory and click OK, 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="C:/TIBCO/as/2.1/lib/as-common.jar"/>
    <library path="C:/TIBCO/as/2.1/lib"/>
  </java-vm>
</streambase-configuration>

  • At runtime, the operator will expect the configured Metaspace and Space to be running and ready to accept connections at the configured URLs.

Properties View Settings

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

General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. 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: A field that shows the fully qualified class name that implements the functionality of this operator. Use this class name when loading the operator in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this operator starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the operator does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.

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 and Error Streams 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.

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.

Metaspace Name

Specifies the name of the ActiveSpaces Metaspace to which to connect. This setting is required.

Discovery URL

Specifies the URL to use for Metaspace member discovery. This setting is optional; if left blank the default value will be provided by ActiveSpaces.

Listen URL

Specifies the URL to use for member-to-member connection. This setting is optional; if left blank the default value will be provided by ActiveSpaces.

Space Name

Specifies the name of the Space to join. This setting is required.

Member Name

Specifies the member name to use when joining the Space. This setting is required.

Join As Seeder

Specifies whether to join the Space as a seeder or a leech. This setting is optional; the default value is leech.

Connect When Application Starts

Specifies whether to try to connect to the ActiveSpaces Metaspace when the StreamBase application is started. This setting is optional.

Log Level

Use this to set the operator to produce more or less verbose console output, independent of the STREAMBASE_LOG_LEVEL global setting.

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.

The operator has exactly one input and one output port. Both of these contain a tuple field called activeSpacesTuple. The schema for these two fields is the same and must be defined on this tab. Furthermore, because these fields are meant to represent the content of an ActiveSpaces tuple, this schema must match that used by the ActiveSpaces Space to which the operator is connected. In this context, "must match" means that both 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.

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

The operator has only one input port, used to receive commands describing an operation to be performed on the ActiveSpaces Space (e.g. Get, Put, Connect, etc). Only two fields (command and activeSpacesTuple) are expected to be present; however, a number of other fields are also recognized and may be useful to execute certain commands. If those optional fields are not present in the schema or are present but not set in a command tuple the default value specified by ActiveSpaces will be used.

The full list of fields is given in the following table. Fields are optional unless noted otherwise.

Field Name Field Type Description
command string REQUIRED. Describes the command to be executed. The list of supported commands (along with their expected output) is given in Commands And Results.
activeSpacesTuple tuple REQUIRED. Describes the tuple to which this command applies. For example, for a Get command this should contain a tuple with its key value(s) properly set so the corresponding tuple can be located from the Space and retrieved, for a Put command this should contain the tuple to put in the Space, etc.
commandID string If specified, this field will be set on the output tuple(s) resulting from executing the present command. Using this, an application can draw a correlation between a command and its results.
filter string Specifies the predicate used to refine the set of tuples on which to work when executing a Listen command. If no filter is specified, the command will apply to all tuples in the Space.
listenerID string When a Listen command is executed, the resulting listener is named by the operator for further reference. This ID is given in the info field of the resulting tuple for this command. This is ID should be set on the present field when executing a StopListening command so the operator will know which listener to remove.
lock boolean Specifies whether to lock a tuple before executing the command. Applies to the Take and Put commands.
unlock boolean Specifies whether to unlock a tuple after executing the command. Applies to the Take and Put commands.
lockWait lock Timeout value for lock and unlock operations. Applies to the Lock, Unlock, Take and Put commands.
forget boolean By default, certain commands will return the tuple on which the operation was performed. If this field is true the tuple will not be returned. Applies to the Lock, Take and Put commands.
timeScope string Specifies whether a Listen command should be applied to existing tuples, new tuples being added or both. Valid values are:

  • SNAPSHOT — returns only PUT corresponding to the entries stored in the Space at creation time.

  • NEW — updated only with events related to new or updated entries in the Space.

  • NEW_EVENTS — updated with all events that occur in the Space after creation time.

  • ALL — starts with all the entries currently in the Space at creation time (which will be presented as an initial set of PUT events) and then is continuously updated according to changes in the Space.

All values are case-sensitive.

distributionScope string Specifies whether a Listen command should be applied to all tuples or only those seeded by the calling process (i.e. your StreamBase application). Valid values are:

  • ALL — the Listen command applies to all tuples in the Space.

  • SEEDED — the command only applies to those tuples in the Space that are being seeded by the current process. This setting is only meaningful if the operator was configured to connect as a seeder.

All values are case-sensitive.

route boolean Specifies whether the operation should be routed across subnets. Applies to the Take and Put commands.
ttl long Specifies the time-to-live value (in milliseconds) for the tuple about to be added to the Space. Applies to the Put command.

Output Ports

The operator has only one output port, used to deliver the results of executing operator commands. The complete list of commands and expected results is given in Commands And Results.

Field Name Field Type Description
commandID string Mirrors the value of the commandID field of the input tuple containing the command that triggered this output.
event string The type of result represented by this output tuple. The list of event types is given in Commands And Results.
activeSpacesTuple tuple Contains the tuple that was retrieved from the Space as a result of executing the command that triggered this output. For example, for a Get command this contains the retrieved tuple, for a Put command it contains the old tuple (if any), etc.
info list<string> This is an all-purpose field used to convey additional information describing this result. For example, in the case of an Error event this will contain the text describing the error.

Commands And Results

This section describes the commands supported by the operator as well as their expected results.

Commands

For every command described in this section, you may wish to set the optional commandID field to a unique value in addition to setting command-specific values. Doing so will ensure that any tuple produced as direct result of executing the command will have its corresponding field of the same name set to the same value, so that your application can keep track of the command-to-result correlation.

All input fields are optional unless marked otherwise.

Connect

Description: Instructs the operator to establish a connection to the configured Metaspace and Space. Calling this command when already connected will cause the operator to disconnect and attempt to connect again.

Fields:

  • command: Connect

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Connected

  • info: null

  • activeSpacesTuple: null

Disconnect

Description: Instructs the operator to sever the connection to the configured Metaspace and Space. Calling this command when already disconnected will have no effect, but a Disconnected result tuple will still be emitted.

Fields:

  • command: Disconnect

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Disconnected

  • info: null

  • activeSpacesTuple: null

Connection Status

Description: Queries the operator to determine if the configured Metaspace and Space is currently connected or not.

Fields:

  • command: ConnectionStatus

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Connected or Disconnected

  • info: null

  • activeSpacesTuple: null

Get

Description: Instructs the operator to get a tuple from the Space matching the key(s) given in the included tuple.

Fields:

  • command: Get

    Required field.

  • activeSpacesTuple: A tuple with at least all of the Space's defined key fields set. Those values are used to find a matching tuple in a connection to the configured Metaspace and Space. Calling this command when already connected causes the operator to disconnect and attempt to connect again to the Space. The non-key fields of the tuple may be left null.

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Get

  • info: null

  • activeSpacesTuple: the retrieved tuple, or null if the requested tuple was not found in the Space.

Take

Description: Instructs the operator to take (atomic get-and-remove operation) a tuple from the Space matching the key(s) given in the included tuple.

Fields:

  • command: Take

    Required field.

  • activeSpacesTuple: A tuple with at least all of the Space's defined key fields set. Those values will be used to find a matching tuple in the Space. The non-key fields of the tuple may be left null.

    Required field.

  • forget: If set to false the result tuple will include a copy of the Space's tuple in the activeSpacesTuple field. If set to true the result tuple will be null.

    Default value: false.

  • route: Set this to true if the operation is to be routed.

    Default value: false.

  • lock: Set this to true if the Space's tuple should be locked after taking it.

    Default value: false.

  • unlock: Set this to true if the Space's tuple should be unlocked after taking it.

    Default value: false.

  • lockWait: Set this to the number of milliseconds the operation should wait for a locked tuple before giving up. Using a value of -1 will cause the operation to wait forever. If the operation times out, an error tuple will be emitted.

    Default value: -2 (that is, do not wait for the tuple to unlock).

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Take

  • info: null

  • activeSpacesTuple: the retrieved tuple, or null if the requested tuple was not found in the Space or if the command's forget field was set to true.

Put

Description: Instructs the operator to put (i.e. add or update) the given tuple in the Space.

Fields:

  • command: Put

    Required field.

  • activeSpacesTuple: The tuple to put in the Space.

    Required field.

  • forget: If set to false the result tuple will include a copy of the Space's tuple in the activeSpacesTuple field. If set to true the result tuple will be null.

    Default value: false.

  • route: Set this to true if the operation is to be routed.

    Default value: false.

  • lock: Set this to true if the Space's tuple should be locked after putting it in the Space.

    Default value: false.

  • unlock: Set this to true if the Space's tuple should be unlocked after putting it in the Space.

    Default value: false.

  • lockWait: Set this to the number of milliseconds the operation should wait for a locked tuple before giving up. Using a value of -1 will cause the operation to wait forever. If the operation times out, an error tuple will be emitted.

    Default value: -2 (that is, do not wait for the tuple to unlock).

  • ttl: Specify the time to live for this tuple, in milliseconds.

    Default value: -2 (that is, do not expire).

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Put

  • info: null

  • activeSpacesTuple: If the tuple already existed in the Space, a copy of its state before the update is placed in this field. Contains null if the tuple was not found in the Space or if the command's forget field was set to true.

Lock

Description: Instructs the operator to lock the given tuple in the Space.

Fields:

  • command: Lock

    Required field.

  • activeSpacesTuple: A tuple with at least all of the Space's defined key fields set. Those values will be used to find a matching tuple in the Space. The non-key fields of the tuple may be left null.

    Required field.

  • forget: If set to false the result tuple will include a copy of the Space's tuple in the activeSpacesTuple field. If set to true the result tuple will be null.

    Default value: false.

  • lockWait: Set this to the number of milliseconds the operation should wait for a locked tuple before giving up. Using a value of -1 will cause the operation to wait forever. If the operation times out, an error tuple will be emitted.

    Default value: -2 (that is, do not wait for the tuple to unlock).

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Lock

  • info: null

  • activeSpacesTuple: If the tuple already existed in the Space, a copy of its state before the update is placed in this field. Contains null if the tuple was not found in the Space or if the command's forget field was set to true.

Unlock

Description: Instructs the operator to unlock the given tuple in the Space.

Fields:

  • command: Unlock

    Required field.

  • activeSpacesTuple: A tuple with at least all of the Space's defined key fields set. Those values will be used to find a matching tuple in the Space. The non-key fields of the tuple may be left null.

    Required field.

  • lockWait: Set this to the number of milliseconds the operation should wait for a locked tuple before giving up. Using a value of -1 will cause the operation to wait forever. If the operation times out, an error tuple will be emitted.

    Default value: -2 (that is, do not wait for the tuple to unlock).

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Unlock

  • info: null

  • activeSpacesTuple: null

Listen

Description: Instructs the operator to start listening to tuple changes in the Space.

Fields:

  • command: Listen

    Required field.

  • filter: Can be used to specify an expression used to select a subset of tuples in the Space for which change notification is desired.

    Default value: null, which means all tuples will be watched for changes.

  • timeScope: Determines the time span for which notifications are desired. Should be set to one of the following:

    SNAPSHOT: The results only consist of one PutEvent event for each tuple already existing in the Space, essentially reporting the current state of the Space. No other events will be issued as a result of this Listen command.

    NEW: The results consist of all events related only to tuples that are new or have been updated since the execution of the Listen command. The initial state of the Space is not reported.

    NEW_EVENTS: The results consist of all new events for tuples in the Space — that is, events that have occurred since the execution of the Listen command. The initial state of the Space is not reported.

    ALL: The results consist of one PutEvent event for each tuple already existing in the Space, plus all new events as well. In effect this is equivalent to a SNAPSHOT Listen immediately followed by a NEW_EVENTS Listen.

    Default value: NEW.

    All of the above values are case-sensitive.

  • distributionScope: Determines the subset of tuples for which notifications are desired. Should be set to one of the following:

    ALL: All tuples in the Space should be reported upon.

    SEEDED: Only those tuples which are being seeded by the application should be reported upon. This setting is only meaningful if the operator's Join As Seeder property is checked.

    Default value: ALL.

    All of the above values are case-sensitive.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: Listen

  • info: This contains a list of only one item: The unique identifier associated with this listener. This ID is assigned by the operator and should not be expected to observe any particular format. It should be used as the input value to the StopListener command's listenerID field so the operator will know which listener to stop.

  • activeSpacesTuple: null

Furthermore, one or more tuples with the following values may be emitted asynchronously as changes are made to the Space while the listener is active:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: One of: TakeEvent, PutEvent, or ExpireEvent.

  • info: This contains a list of only one item: The unique identifier associated with the listener that generated this event.

  • activeSpacesTuple: The current value of the tuple that generated this event.

StopListener

Description: Instructs the operator to stop listening to tuple changes in the Space.

Fields:

  • command: StopListener

    Required field.

  • listenerID: Identifies the listener to stop. The value for this field must be set to the one given in the result tuple of the corresponding Listen command's info field.

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: StopListen

  • info: This contains a list of only one item: The unique identifier associated with the listener that was stopped.

  • activeSpacesTuple: null

Get Space Size

Description: Returns the number of tuples matching the given filter expression. If no filter is specified, the total number of tuples contained in the Space will be returned.

Fields:

  • command: GetSpaceSize

    Required field.

  • filter: Can be used to specify an expression used to select a subset of tuples in the Space on which to apply this command.

    Default value: null, which means all tuples will be reported on.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: SpaceSize

  • info: This contains a list of only one item: The number of tuples matching the given filter (or the total number of tuples in the Space if no filter was specified).

  • activeSpacesTuple: null

Get Space State

Description: Reports on the current state of this Space.

Fields:

  • command: GetSpaceState

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: SpaceState

  • info: Contains a list of only one item set to one of: READY, INITIAL, LOADING, SUSPENDED, RECOVER, or INVALID.

  • activeSpacesTuple: null

Begin Transaction

Description: Begins an atomic transaction. Commands executed between this call and a corresponding CommitTransaction command will be executed as a single transaction. You may cancel the entire transaction by calling the RollbackTransaction command.

Fields:

  • command: BeginTransaction

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: TransactionBegun

  • info: null

  • activeSpacesTuple: null

Commit Transaction

Description: Commits the transaction previously started with the BeginTransaction command.

Fields:

  • command: CommitTransaction

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: TransactionCommitted

  • info: null

  • activeSpacesTuple: null

Rollback Transaction

Description: Rolls back (aborts) the transaction previously started with the BeginTransaction command.

Fields:

  • command: RollbackTransaction

    Required field.

Expected result: A tuple with the following values:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple.

  • event: TransactionRolledBack

  • info: null

  • activeSpacesTuple: null

Asynchronous Events

Some events are not emitted as a direct result of executing a command but are rather a result of an asynchronous occurrence, such as connection state transitions, error conditions, etc. This section describes these events.

Error Event

Description: This is emitted whenever an unexpected condition occurs.

Fields:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple that generated this error, if applicable.

  • event: Error

  • info: A list of values containing more information on the error condition.

  • activeSpacesTuple: null

Connection Or Disconnection Event

Description: This is emitted whenever the operator's connection state changes.

Fields:

  • commandID: Contains whatever value was specified in the corresponding field of the command tuple that generated this error, if applicable.

  • event: The new connection state; either Connected or Disconnected.

  • info: null

  • activeSpacesTuple: null

Listener Update Event

Description: When a listener is created on the Space using the Listen command, one or more asynchronous events may be generated to represent changes to the Space as they occur.

Fields:

  • commandID: Contains whatever value was specified in the corresponding field of the Listen command tuple that create this listener.

  • event: One of: TakeEvent, PutEvent, or ExpireEvent.

  • info: A list of only one item: the unique identifier associated with the listener that generated this event.

  • activeSpacesTuple: The current value of the tuple that generated this event.

Type Mappings

When exchanging tuples between StreamBase and ActiveSpaces, the fields and field types of these tuples are expected to match; the tuples have the same number of fields, each field's name is the same, and their types are such that a reasonable conversion can be made. The table below lists all the type translations supported by the operator.

StreamBase Type ActiveSpaces Type
boolean boolean
string string, char

When mapping a StreamBase string to an ActiveSpaces char, the first character of the StreamBase string is used.

int int, short

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

long long
double double, float

When mapping a StreamBase double to an ActiveSpaces float, some precision may be lost.

timestamp DateTime
blob, tuple, list, capture blob

When mapping a StreamBase tuple, list, or capture field to an ActiveSpaces blob, the value is serialized and placed in the blob. Conversely, if an ActiveSpaces blob is mapped to a StreamBase tuple, list, or capture field an attempt is made to deserialize the blob bytes into the appropriate object. It is the responsibility of the StreamBase application's author to ensure the recipient field is of the correct type for deserialization.

Legacy 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 → Load StreamBase Sample and look under the Extending StreamBase section for an entry called ActiveSpaces Operator.

Related Topics

Back to Top ^