Using the 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 Java Operator dialog, which you invoke with one of the following methods:

Drag the Java Operator 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 dialog, 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 Name: 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 check box is selected, an instance of this operator starts as part of the containing StreamBase Server. If cleared, the operator is loaded with the server, but does not start until you send an sbadmin resume command, or start the component with StreamBase Manager. With this option cleared, the operator does not start even if the application as a whole is suspended and later resumed. The default and recommended setting is selected.

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
Describe
Free Form
Get Leadership
Get Operator Status for Container
List Connections
Modify Container
Remove Container
Restart Operator
Resume
Set Leadership
Shutdown Server
Shutdown Operator
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 an entire 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.

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.

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 example for container connections:

list("main.ClientInputB=default.ClientOutputB")

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 both fields in the form of a StreamBase expression, which usually means simply placing quotes around a string argument.

Name: If your selected subcommand requires it, enter the StreamBase URI for a server instance.
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 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.

Command: Enter the full sbadmin subcommand without "sbadmin," as you would enter it at the shell command prompt.
Command line parameters: Enter any further arguments to append to your free form sbadmin command line.

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 separate threading 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.