Using the TIBCO StreamBase Admin Operator

Introduction

The StreamBase Admin operator is a global Java operator that provides a way to run sbadmin subcommands as a Java process without opening a shell command prompt. This feature is especially useful in StreamBase high availability design patterns, where an application in one container might need to send an sbadmin subcommand to an application in another container or on another StreamBase Server.

Configure the operator to send a single sbadmin subcommand to a single target server or container. Once configured, the operator's subcommand is sent on receipt of a tuple with any schema on the operator's input port. To send more than one sbadmin subcommand, use more than one instance of the operator in your application.

Specify the subcommand to run using the Command field of the Operator Properties tab. The subcommand you select may require arguments or parameters. If so, enter those on other tabs of the Properties view. Fields in other tabs are dimmed and unavailable unless they are relevant to the subcommand selected in the Command field.

Placing a StreamBase Admin Operator on the Canvas

Select the StreamBase Admin operator from the Insert an Operator or Adapter dialog, which you invoke 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 StreamBase Admin and double-click or press OK.

Input Port

By default, the StreamBase Admin operator has one input port that accepts a tuple with any schema. The operator runs its configured command on the receipt of a tuple, not based on the contents of the tuple.

You can also add an optional Error Output port, which outputs a StreamBase error tuple for any error thrown by the operator, as described in General Tab.

Properties: General Tab

This section describes the properties on the General tab in the Properties view for the External Process operator.

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.

Properties: Operator Properties Tab

This section describes the properties on the Operator Properties tab in the Properties view for the StreamBase Admin operator.

Command

This field is central to the operation of the operator. Use the drop-down list in the Command field to select the exact sbadmin subcommand to send with this instance of the operator. The available subcommands are:

Add Container
Add Deploy
Describe
Free Form
Get Dynamic Variable
Get Leadership
Get Operator Status for Container
List Connections
List
Kill Connection
Manage Jdbc Connections
Modify Container
Remove Container
Restart Operator
Restart Container
Resume
Set Dynamic Variable
Set Leadership
Shutdown Server
Shutdown Operator
Status
Suspend

All commands except Free Form correspond to an sbadmin subcommand, as documented on the sbadmin reference page. The Free Form command lets you type a subcommand with custom arguments for custom uses.

Once you select an sbadmin subcommand with the Command field, you may need to provide further information on one of the other tabs of the Properties view. See the sbadmin reference page for details on the required and optional arguments and parameters for your selected subcommand.

Remote server

By default, this operator sends its command to the same StreamBase Server instance that is hosting and running this operator. Select this check box to send the command to any other server instance, including to another server running on a different port on the same machine.

Server URI

If you selected the Remote server check box, enter a StreamBase URI in this field in the form of an expression. See sburi for the format of a StreamBase URI.

Username

If you did not select the Remote server check box and the StreamBase server is running with authentication enabled, enter a user name in this field in the form of an expression. A username and password is never required when running locally.

Note

This property is deprecated and will be removed in a future release. For remote servers running under authentication, specify the username as part of the Server URI.

Password

If you did not select the Remote server check box and StreamBase Server is running with authentication enabled, enter a password in this field in the form of an expression. A username and password is never required when running locally.

Note

This property is deprecated and will be removed in a future release. For remote servers running under authentication, specify the password as part of the Server URI.

Number of async worker threads

The default value of 1 means that the operator's commands are performed serially. This is ideal behavior when using the operator to perform commands that must be run in sequence, such as Add Container, then Modify Container. Positive values specify a limit on the number of threads to spawn to perform the operator's requested operations. Negative or 0 means the operator spawns an unlimited number of threads.

Enable Status Port

The status port can be enabled to allow the operator to output status tuples to give the user more information during processing. Status tuples for this operator will be emitted for errors and rejections of input tuples. A rejection status tuple will be emitted if there is a validation problem on the input tuple. A error status tuple will be emitted if there is an error during processing.

Log Level

Controls the level of verbosity the adapter uses to issue informational traces to the console. This setting is independent of the containing application's overall log level. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

Properties: Container Tab

This section describes the properties on the Container tab in the Properties view for the StreamBase Admin operator. First select the sbadmin subcommand to send using the Command field on the Operator Properties tab. If the subcommand affects containers or container operations, enter further subcommand arguments on this tab. Enter arguments in all fields in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

Container Name

If your selected subcommand requires it, enter a container name to which the command is to be addressed.

Container application file name

If your selected subcommand requires it, enter the path to an EventFlow or StreamSQL file to load into a container.

Container options

If your selected subcommand requires it, enter further arguments or parameters for your container-related command. Enter the arguments as a list of strings like the following examples for adding a container:

Container name: "A"
Container application file name: "mainprocess.sbapp"
Container options: list("--enqueue","DISABLED")

The equivalent sbadmin command for the second example would be:

sbadmin addContainer A mainprocess.sbapp --enqueue=DISABLED

For descriptions of relevant options, see the commands section in the sbadmin documentation and find the subcommand you are invoking with the operator.

Properties: Get and Set Info Tab

This section describes the properties on the Get and Set Info tab in the Properties view for the StreamBase Admin operator. First select the sbadmin subcommand to send using the Command field on the Operator Properties tab. If the subcommand affects a get or set info or leadership operation, then enter further subcommand arguments on this tab. Enter arguments in the fields in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

Deploy File: If your selected subcommand requires it, enter the deploy file to use.
Feature Name: If your selected subcommand requires it, enter feature name.
Name: If your selected subcommand requires it, enter the StreamBase URI for a server instance.
Connection Id: If your selected subcommand is Kill Connections, enter the Id of the connection to kill.
Leadership: If your selected subcommand is Set Leadership, enter either LEADER or NON-LEADER.

Properties: Free Form Tab

This section describes the properties on the Free Form tab in the Properties view for the StreamBase Admin operator. First select Free Form in the Command field on the Operator Properties tab. Then enter the sbadmin subcommand in the Command field and its arguments in the Command line parameters field. Provide arguments in the form of a list of quoted strings containing subcommand options and StreamBase expressions.

Command

Commands are case-sensitive and must be surrounded with quotes. Enter them exactly as they appear in the Operator Properties Command drop-down menu. This string can differ from the actual sbadmin command name. For example, you would enter Modify Container, not modifyContainer.

Command line parameters

Enter parameters to provide to the indicated sbadmin command. For example, to execute an Add Container Command, enter the following:

Command: "Add Container"
Command line parameters: "A mainprocess.sbapp --enqueue=DISABLED"

Parameters should also be entered as a single quoted string, not the list of strings that the Container tab's Container Options requires.

The equivalent sbadmin command for the second example would be:

sbadmin addContainer A mainprocess.sbapp --enqueue=DISABLED

Verbose mode is always enabled when the sbadmin command is called from this operator.

The sbadmin subcommand readTable is not supported.

Properties: Dynamic Variable Tab

This section describes the properties on the Dynamic Variable tab in the Properties view for the StreamBase Admin operator. First select Get/Set Dynamic Variable in the Command field on the Operator Properties tab. Then type the full sbadmin subcommand and its arguments in the fields of this tab. Enter arguments in both fields in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

Variable Path: Enter the full path of the dynamic variable.
Variable Value: Enter the value used when performing a set operation.

Properties: Operator Property Tab

This section describes the properties on the Operator Property tab in the Properties view for the StreamBase Admin operator. First select Get/Set Operator Property in the Command field on the Operator Properties tab. Then type the full sbadmin subcommand and its arguments in the fields of this tab. Enter arguments in both fields in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

Operator Name: Enter the operator name.
Operator Property Name: Enter the name of the property for the operator.
Operator Property Value: Enter the value used when performing a set operation.

Properties: List Tab

This section describes the properties on the List tab in the Properties view for the StreamBase Admin operator. First select the List command using the Command field on the Operator Properties tab. Enter arguments in the fields in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

Connection Type: If your selected subcommand is List Connections, enter either current, old, all, or clearOld.
Entity Type: The entity type to list. May be schema, stream, output-stream, input-stream, box, operator, table, tableconcrete, window, windows, window-spec, window-specs, container-connection.
Fully Qualified Names: Include the container name in the entity name.
Include Modules: Include all sub-modules.
Container: The container to list entities for. If not specified, the default container is used.

Properties: JDBC Tab

This section describes the properties on the List tab in the Properties view for the StreamBase Admin operator. First select the Manage JDBC Connections command using the Command field on the Operator Properties tab. Enter arguments in the fields in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

JDBC Action: The type of action to perform on the connection: close, count.
JDBC Data Source: The data source to perform the action on.

Properties: Starting and Stopping Tab

This section describes the properties on the Starting and Stopping tab in the Properties view for the StreamBase Admin operator. First select the sbadmin subcommand to send using the Command field on the Operator Properties tab. If the subcommand affects starting or stopping a server or container, enter further subcommand arguments on this tab. Enter any arguments in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

Name: Enter a StreamBase URI of a server or container instance to start, pause, resume, or shutdown.

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.

Using the TIBCO StreamBase Admin Operator

Introduction

Placing a StreamBase Admin Operator on the Canvas

Input Port

Properties: General Tab

Properties: Operator Properties Tab

Note

Note

Properties: Container Tab

Properties: Get and Set Info Tab

Properties: Free Form Tab

Properties: Dynamic Variable Tab

Properties: Operator Property Tab

Properties: List Tab

Properties: JDBC Tab

Properties: Starting and Stopping Tab

Properties: Concurrency Tab

Caution

Related Topics