Contents
Note
This document describes the legacy operators for use with ActiveSpaces 2. This set of operators is deprecated.
For information on StreamBase operators that support ActiveSpaces 3.0 and later, including 4.x, see Using the TIBCO ActiveSpaces Operators.
This topic describes how to use the TIBCO ActiveSpaces® 2 operators to interact with an ActiveSpaces Metaspace, and explains how to configure the operators' Properties views. This suite of operators work only with ActiveSpaces version 2.x starting with 2.1.
The TIBCO ActiveSpaces 2 connectivity solution is implemented as a suite of seven global Java operators that allow a StreamBase application to connect to an ActiveSpaces Metaspace and Space, and that allow the application to exchange tuples seamlessly with the Space. Depending on your operators' configuration settings, your application acts 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 supported using the appropriate operator. The complete list of supported operations and operators is described below.
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
→ → .
From the Insert an Operator or Adapter dialog, select one of the following ActiveSpaces-related operators and double-click or press :
-
TIBCO ActiveSpaces Legacy Put, which adds to the Space.
-
TIBCO ActiveSpaces Legacy Get/Take, which retrieves from the Space.
-
TIBCO ActiveSpaces Legacy Lock/Unlock, which performs locking operations on tuples in the Space.
-
TIBCO ActiveSpaces Legacy Browse, which lists some or all tuples in the Space.
-
TIBCO ActiveSpaces Legacy Listen, which asynchronously informs of Take, Put, Expire, or Evict events on the Space.
-
TIBCO ActiveSpaces Legacy Transaction Operations, which perform Begin, Commit, and Rollback operations on the Space.
-
TIBCO ActiveSpaces Legacy Control, which allows your StreamBase application to connect to and disconnect from a Space, as well as to obtain metric information from it such as the number of tuples contained therein.
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 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 → . On the Libraries tab of the Properties dialog, click the button. This brings up a file browser; navigate to the
lib
directory of your ActiveSpaces installation, selectas-common.jar
, and click . Back in the Libraries tab, an entry is now added foras-common.jar
. Expand this node, select Native Library Location, and click the button. Enter the location of the ActiveSpaceslib
subdirectory and click , then click 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>
Optionally, you can make use of the
AS_HOME
environment variable (if available) to specify the location of your ActiveSpaces libraries:<?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="${AS_HOME}/lib/as-common.jar"/> <library path="${AS_HOME}/lib"/> </java-vm> </streambase-configuration>
-
-
At runtime, the operators expect the configured Metaspace and Space to be running and ready to accept connections at the configured URLs. Configuration of your ActiveSpaces operators is discussed in the next section.
The different ActiveSpaces operators share a connection to the same Metaspace (and optionally the same Space), provided they
are configured to do so. Each operator lists the Metaspaces and Spaces 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/"> <adapter-configurations> <!-- This section contains the configuration settings for the ActiveSpaces operators --> <adapter-configuration name="activespaces"/> <!-- This section defines a Metaspace --> <section name="metaspace-definition"> <setting name="id" val="sbms"/> <setting name="member-name" val="me"/> <!-- Edit these URLs to reflect your Metaspace's required values --> <setting name="discovery-url" val="tcp://10.97.233.31:50000"/> <setting name="listen-url" val="tcp://10.97.233.31:50001"/> <setting name="reconnect-interval-ms" val="10000"/> <setting name="connection-timeout-ms" val="30000"/> <!-- Authentication. Note that the <authentication-pwd> value can either be enciphered using sbcipher or can be plain text. <setting name="authentication-domain" val="myDomain"/> <setting name="authentication-username" val="myName"/> <setting name="authentication-pwd" val="dgrqnVai/TG6QgpPrb2ASOMCA4oVaijxqsUauHYbEff6fjoCQT9UunhREY8vtIu6oxiztD3k9TIjuk4v2m3t7g=="/> <setting name="security-policy-file" val="myPolicyFile"/> <setting name="security-token-file" val="myTokenFile"/> <setting name="identity-pwd" val="dgrqnVai/TG6QgpPrb2ASOMCA4oVaijxqsUauHYbEff6fjoCQT9UunhREY8vtIu6oxiztD3k9TIjuk4v2m3t7g=="/> --> <!-- This section defines a Space managed by this Metaspace --> <section name="space-definition"> <setting name="id" val="sbspace"/> <setting name="is-seeder" val="true"/> </section> <!-- This section defines another Space managed by this Metaspace --> <section name="space-definition"> <setting name="id" val="sbspace2"/> <setting name="is-seeder" val="true"/> </section> </section> <!-- Other Metaspace definitions go here --> </adapter-configuration> </adapter-configurations> </streambase-configuration>
In each <section name="metaspace-definition">
and <section name="space-definition">
section, the <setting id="SomeName">
tag should match its id
value to the actual Metaspace or Space name it represents in the ActiveSpaces system. This is also the value listed in the
Operator Properties tab of each operator's Properties view.
A best practice is to define your Metaspaces and Spaces 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.
This section describes the properties you can set for a TIBCO ActiveSpaces operator, using the various tabs of the Properties view in StreamBase Studio.
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: 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 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.
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.
All the ActiveSpaces operators have a common set of properties:
- Metaspace Name
-
Specifies the name of the ActiveSpaces Metaspace to which to connect. The combo box will contain a list of available Metaspaces from which to choose, as defined in
sbd.sbconf
(see Configuration). This setting is required. - Space Name
-
Specifies the name of the ActiveSpaces Space to join. The combo box will contain a list of available Spaces from which to choose, as defined in
sbd.sbconf
(see Configuration). This setting is required. - Enable Status Port
-
Specifies whether to add a second output port to the operator to convey status tuples (connection notices, errors, and so on). This setting is optional.
Note
This property is not available for the Control operator.
- Connect on Startup
-
When selected, controls whether the operator attempts to connect to the Metaspace automatically when the containing application is started. All ActiveSpaces operators except ActiveSpaces Control default to false.
- 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.
In addition to the common properties listed above, some operators also have some properties of their own:
- Get or Take Tuple
-
Specifies whether this operator should get or take (remove) the requested tuples. This setting is optional and defaults to
Get
.
- Lock or Unlock Tuple
-
Specifies whether this operator should lock or unlock the specified tuples. This setting is optional and defaults to
Get
.
- Browsing Type
-
Specifies the type of browsing operation to perform on the Space (
Get
,Take
orLock
). This setting is optional and defaults toGet
. - # Of Tuples To Fetch
-
Specifies the number of tuples to pre-fetch from the Space when browsing. This setting is optional and may be left blank to use the ActiveSpaces default value of 1000.
- Query Limit
-
Specifies the maximum number of tuples to return from the Space when browsing. This setting is optional and may be left blank (or set to 0) to use the ActiveSpaces default value for this Space.
Note
This property is ignored if the operator detects that the running version of ActiveSpaces is older than 2.1.5, as this functionality was not available in older versions.
- Start or Stop Listening
-
Specifies whether to start or stop reporting on events occurring in the Space. This setting is optional and defaults to Start.
When set to
Start
, input tuples'listenerID
must be set to a unique identifier which will be associated with the created listener. In this way, multiple listeners may be created by the same operator by using different values forlistenerID
. If the samelistenerID
value is used to start another listener, the previous listener associated with this ID will be stopped first.When set to
Stop
, input tuples'listenerID
value will be used by the operator to find the listener to be stopped. - Report Take Events
-
Specifies whether to report on Take events in the Space. This setting is optional and defaults to
true
(check box checked). - Report Put Events
-
Specifies whether to report on Put events in the Space. This setting is optional and defaults to
true
(check box checked). - Report Expire Events
-
Specifies whether to report on Tuple Expiration events in the Space. This setting is optional and defaults to
true
(check box checked). - Report Evict Events
-
Specifies whether to report on Tuple Eviction events in the Space. This setting is optional and defaults to
true
(check box checked). - Query Limit
-
Specifies the maximum number of tuples to return from the Space when listening. This setting is optional and may be left blank (or set to 0) to use the ActiveSpaces default value for this Space.
Note
This property is ignored if the operator detects that the running version of ActiveSpaces is older than 2.1.5, as this functionality was not available in older versions.
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 exactly one input and one output port (plus an optional Status port). Several of these operators have a
tuple field called asTuple
on those streams, used to represent an ActiveSpaces tuple. The schema for this tuple field is the same for both input and
output streams 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 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.
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.
Each operator has only one input port, used to receive commands describing an operation to be performed on the ActiveSpaces Space (such as Get, Put, Connect, and so on). The schema for each operator is different because different operations require different parameters.
One optional field is common to all operators: a tuple field named passthrough
. If present, it is passed on, unchanged, to the output stream of the operator. You can use this mechanism to attach context
data to you commands to an operator, allowing you to identify this command again later on downstream.
For all operators, fields are optional unless noted otherwise below.
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | REQUIRED. Describes the tuple to retrieve. This should contain a tuple with its key value(s) properly set so the corresponding tuple can be located from the Space and retrieved. |
forget | boolean | For Take operations, this tells the operator to not return the ActiveSpaces tuple in the asTuple field of the result tuple on the output stream after removing is from the Space (the asTuple field will be left null). For Get operations, this field is ignored.
|
route | boolean | For Take operations, specifies whether the operation should be routed across subnets. For Get operations, this field is ignored. |
lock | boolean | For Take operations, specifies whether to lock a tuple before executing the command. For Get operations, this field is ignored. |
unlock | boolean | For Take operations, specifies whether to unlock a tuple after executing the command. For Get operations, this field is ignored. |
lockWait | long | For Take operations, specifies the timeout value for lock and unlock operations. Leave empty to wait forever. For Get operations, this field is ignored. |
passthrough | tuple | If present, this field's contents is passed along unchanged to the Result output stream. This allows context to be attached to the command, for example to identify output tuples that directly result from this command. |
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | REQUIRED. Describes the tuple to be added (or, if this tuple already exists, updated) in the Space. |
forget | boolean | Tells the operator to not return the ActiveSpaces tuple in the asTuple field of the result tuple on the output stream after updating it in the Space (the asTuple field is left null).
|
route | boolean | Specifies whether the operation should be routed across subnets. |
lock | boolean | Specifies whether to lock a tuple before executing the command. |
unlock | boolean | Specifies whether to unlock a tuple after executing the command. |
lockWait | long | Specifies the timeout value for lock and unlock operations. Leave empty to wait forever. Ignored if neither lock or unlock fields are present.
|
ttl | long | Specifies the time-to-live (in milliseconds) for the tuple about to be put to the Space before it is considered for expiration. |
passthrough | tuple | If present, this field's contents are passed along unchanged to the Result output stream. This allows context to be attached to the command, such as to identify output tuples that directly result from this command. |
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | REQUIRED. Describes the tuple to be locked or unlocked in the Space. |
forget | boolean | Tells the operator to not return the ActiveSpaces tuple in the asTuple field of the result tuple on the output stream after locking or unlocking it in the Space (the asTuple field wil be left null).
|
lockWait | long | Specifies the timeout value for lock and unlock operations. Leave empty to wait forever. Ignored if neither lock or unlock fields are present.
|
passthrough | tuple | If present, this field's contents are passed along unchanged to the Result output stream. This allows context to be attached to the command, such as to identify output tuples that directly result from this command. |
Field Name | Field Type | Description |
---|---|---|
filter | string | Specifies the predicate used to filter the result set returned by the Browse operation. |
timeScope | string | Specifies whether the Browse command should be applied to existing tuples, new tuples being added or both. Valid values are:
|
distributionScope | string | Specifies whether the Browse command should be applied to all tuples or only to those seeded by the calling process (that is, your StreamBase application).
Valid values are:
|
passthrough | tuple | If present, this field's contents are passed along unchanged to the Result output stream. This allows context to be attached to the command, such as to identify output tuples that directly result from this command. |
Field Name | Field Type | Description |
---|---|---|
listenerID | string | REQUIRED. Should uniquely identify the listener to be created (if the operator's Start or Stop Listener property is set to Start ), or deleted (if the operator's Start or Stop Listener property is set to Stop ). If the same ID is used again to create another listener, the existing listener will be stopped first.
|
filter | string | Specifies the predicate used to filter the result set returned by the Listen operation. |
timeScope | string | Specifies whether a Listen command should be applied to existing tuples, new tuples being added or both. Valid values are:
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 (that is, your StreamBase application).
Valid values are:
All values are case-sensitive. |
passthrough | tuple | If present, this field's contents are passed along unchanged to the Result output stream. This allows context to be attached to the command, such as to identify output tuples that directly result from this command. |
Field Name | Field Type | Description |
---|---|---|
passthrough | tuple | If present, this field's contents are passed along unchanged to the Result output stream. This allows context to be attached to the command, such as to identify output tuples that directly result from this command. |
Field Name | Field Type | Description |
---|---|---|
command | string | REQUIRED. Describes the command to be executed. Valid values include:
|
filter | string | Specifies the predicate used to filter the result set returned by the GetSpaceSize command. For all other commands, this field is ignored. |
passthrough | tuple | If present, this field's contents are passed along unchanged to the Result output stream. This allows context to be attached to the command, such as to identify output tuples that directly result from this command. |
Every operator has only one fixed output port, used to deliver the results of executing operator commands, plus one optional Status output port if the operator's Enable Status Port option is checked.
The Results Port differs for each operator.
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | Contains the tuple that was retrieved from the Space as a result of executing the command that triggered this output. |
passthrough | tuple | If a tuple field of the same name is present on the Input stream, this field will contain the unchanged contents of its input counterpart. This allows context to be attached to the command, for example to identify output tuples that directly result from a command. |
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | If a tuple with this key was already present in the Space before the Put operation, this field contains the old version of the tuple (that is, the tuple as it existed before the update). If no such tuple existed before the Put operation, this field is left null. |
passthrough | tuple | If a tuple field of the same name is present on the Input stream, this field will contain the unchanged contents of its input counterpart. This allows context to be attached to the command, for example to identify output tuples that directly result from a command. |
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | Contains the tuple that was locked or unlocked in the Space as a result of executing the command that triggered this output.
If the command tuple specified forget=true , then this field is left null. When the operator's Lock Or Unlock Tuple property is set to Unlock , or if forget=true in the command tuple, this field is null.
|
passthrough | tuple | If a tuple field of the same name is present on the Input stream, this field will contain the unchanged contents of its input counterpart. This allows context to be attached to the command, for example to identify output tuples that directly result from a command. |
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | When a Browse command is executed, one or more tuples are issued on the output port -- one for each ActiveSpaces tuple returned by the
command. For each of these tuples, this field will contain the corresponding ActiveSpaces tuple. Once all tuples have been
returned, one more is issued with this field set to null to indicate that the command has finished execution.
|
passthrough | tuple | If a tuple field of the same name is present on the Input stream, this field will contain the unchanged contents of its input counterpart. This allows context to be attached to the command, for example to identify output tuples that directly result from a command. |
Field Name | Field Type | Description |
---|---|---|
asTuple | tuple | Contains the tuple that was retrieved from the Space as a result of executing the command that triggered this output. When
the operator's Start or Stop Listening property is set to Stop , this field is always null.
|
event | string | The type of result represented by this output tuple. Possible values are: PutEvent , TakeEvent , ExpireEvent , EvictEvent .
|
passthrough | tuple | If a tuple field of the same name is present on the Input stream, this field will contain the unchanged contents of its input counterpart. This allows context to be attached to the command, for example to identify output tuples that directly result from a command. |
Field Name | Field Type | Description |
---|---|---|
passthrough | tuple | If a tuple field of the same name is present on the Input stream, this field will contain the unchanged contents of its input counterpart. This allows context to be attached to the command, for example to identify output tuples that directly result from a command. |
Field Name | Field Type | Description |
---|---|---|
status | string | Contains the result of the command. Possible values are: Connected , Disconnected , Error , SpaceSize , SpaceStatus .
|
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, and in the case of a GetSpaceSize command this will contain the size of the Space (in tuples).
|
passthrough | tuple | If a tuple field of the same name is present on the Input stream, this field will contain the unchanged contents of its input counterpart. This allows context to be attached to the command, for example to identify output tuples that directly result from a command. |
The Status Port, when enabled, is the same for each operator (except the Control operator, which doesn't have one).
Field Name | Field Type | Description |
---|---|---|
status | string | Describes this event. Possible values include: Connected , Disconnected , 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. |
When exchanging tuples between StreamBase and ActiveSpaces, the fields and field types of these tuples are expected to match in the following ways:
-
Tuples 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 |
---|---|
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 |
tuple, list, function | string, blob
When mapping a StreamBase tuple, list, or function field to an ActiveSpaces string, the field's value is converted to a JSON object, and its string representation is placed in the tuple. Conversely, if an ActiveSpaces string is mapped to a StreamBase tuple, list, or function field, an attempt is made to deserialize the string into a JSON object assumed to represent a value appropriate for assignment to the field. It is the responsibility of the StreamBase application's author to ensure the recipient field is of the correct type for the JSON conversion. When mapping a StreamBase tuple, list, or function 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 function 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. |
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. |
As mentioned in previous sections, every operator in the ActiveSpaces suite has the capability to initiate connection to its
assigned Space. However, for complex applications it is more desirable to leave all operators' Connect On Startup property unchecked, save for one Control operator at the beginning of your EventFlow logic to initiate the connection. Add
a Filter operator connected to its Status port to wait for a status tuple with status
='SpaceEvent'
and info
=['Space state changed', 'READY']
before letting the rest of the ActiveSpaces operations (such as Browse queries) take place. This allows for greater control
over the required sequence of events, such as ensuring Listen queries are sent before the first Put operations are performed.