Editing Launch Configurations

Introduction

This topic describes how to use the Run Configuration, Debug Configuration, and Trace Configuration dialogs. All three dialogs have the same usage and allow you to set the same settings.

StreamBase Studio provides three entrance paths for setting up launch configurations: one for running applications, and another for debugging, and a third for running a trace debug. By default, Studio configures and saves a single named launch configuration for each application run, whether for running, debugging, or tracing. You can copy

The Run Configuration, Debug Configuration, and Trace Configuration dialogs are nearly identical, and are treated on this page as if they are the same dialog. When referring generically, to any of the three dialogs, this page uses the term Launch Configuration dialog.

Use Cases for Launch Configurations

You can save sets of launch configurations with different names, to be used in several ways:

You can save one run-debug-trace configuration for each StreamBase application.
You can save separate run, debug, and trace configurations for each application, with different parameters for the three conditions.
You can save several run configurations for any one application, to run and test it with different runtime parameters. For example, you can quickly switch between testing the same application against both local and remote servers with separate configurations for each server.
You can specify a run configuration instead of a top-level application file when exporting a StreamBase bundle. See Application Bundling.

Open the Launch Configuration Dialog

Open the Run Configuration, Debug Configuration, and Trace Configuration dialogs using any of the following methods:

Select Run → Run Configurations from the top-level menu (or Run → Debug Configurations or Run → Trace Configurations).
Right-click in the EventFlow Editor canvas for your application. From the context menu, select Run As → Run Configurations.
In the Package Explorer, right-click the name of your application's EventFlow or StreamSQL file. From the context menu, select Run As → Run Configurations.

Launch configurations are stored as metadata in your Studio workspace. Thus, by default, your set of named launch configurations is common to all your StreamBase projects. However, a launch configuration includes the pathname to the individual application to be launched, so you cannot share launch configurations among StreamBase applications.

Create a New Launch Configuration

Studio automatically creates a new launch configuration for you the first time you run, debug, or trace a module, with the configuration taking the name of the top-level application being run. These launch configurations are created with default settings, and you can edit or copy them to specify custom settings.

You can also create a new launch configuration from scratch. To do this, open the Run Configurations, Debug Configurations, or Trace Configurations dialog and do one of the following:

In the left pane, right-click StreamBase Application, and choose New in the context menu.
In the left pane, select StreamBase Application and click the New toolbar button.
Select the name of an existing StreamBase launch configuration and click the Duplicate toolbar button.

Edit an Existing Launch Configuration

To edit an existing launch configuration:

Open the the Run Configurations, Debug Configurations, or Trace Configurations dialog.
Select the name of the configuration to edit.
Make changes in the tabs of the wizard and click the Apply button before you leave each tab.
Click Revert to undo changes since the last saved version.

After applying your edits, you can:

Click Close to preserve your edits and exit the dialog.
In the Run Configurations dialog, click Run to run the edited launch configuration.
In the Debug Configurations dialog, click Run to run and debug the edited launch configuration.
In the Trace Configurations dialog, click Trace to run the edited launch configuration, generate a tuple trace file, then automatically open the SB Trace Debugger perspective.

The Main Tab

Name

A configuration name is generated for you. Change the name according to your site's standards. The name you enter is not reflected in the navigator pane on the left until you click Apply.

Application

Specify the path to the StreamBase EventFlow or StreamSQL application file to be run or debugged. Paths are absolute, measured from the root of the current Studio workspace. The easiest way to enter the correct path format is to browse for an application file using the Browse button. The resulting dialog shows a list of all .sbapp and .ssql files in your workspace. Select the one you want and click OK.

Target Server

Choose one of the following options:

Local

Launches StreamBase Server on this machine.

Use 32-bit StreamBase Server instead of 64-bit version

This option only appears when StreamBase is installed with the 64-bit version of the StreamBase installer on 64-bit Windows, and Studio detects the bin64 folder in %STREAMBASE_HOME%. Under those circumstances, Studio automatically launches the 64-bit version of the server. Tick this checkbox to override that default and use the 32-bit server.

Remote using workspace defaults

Launches StreamBase Server on a separate UNIX machine using default server settings. If you previously defined a default server machine and username in the Studio preferences dialog, those defaults are automatically used. See StreamBase Studio Preferences for details.

Remote using the following target server

Launches StreamBase Server on a separate UNIX machine with settings that you specify for this launcher only (any workspace defaults are ignored). Fill in the next two fields:

Server machine

Enter the name of the remote host on which to invoke StreamBase Server. The remote host name must be a valid DNS name, IP address, or the string localhost, and can be optionally followed by a colon and the port number of the SSH server on that host. Studio uses the standard SSH port 22, if you do not specify a port. The remote server must be accessible from this machine using SSH. For example, enter:

wayfast.example.com:22

Username

Enter a valid SSH username on the specified remote host. The username must be already set up and tested for SSH connectivity to the specified host. StreamBase supports both password and keyboard-interactive authentication methods with the remote SSH server.

Any remote server designation here is ignored when making an executable bundle with the sbbundle command, or with the StreamBase Export dialog described on Application Bundling.

The Advanced Tab

Debugging Options

The Enable Intermediate Stream Dequeue checkbox allows you to dequeue from intermediate streams while your application is running, for temporary debugging purposes only. You can optionally specify a regular expression to match against the names of intermediate streams in the top-level module and all sub-modules. Intermediate streams whose name matches the provided expression as a substring are exposed for dequeuing; all other intermediate streams are not. See Intermediate Stream Dequeuing for more information.

The Allow Remote Java Debugging checkbox is for debugging embedded Java modules you have added to your StreamBase application. Specify the port number to which a remote Java debugger will connect to your Java module. For example, you might be using Eclipse's Remote Java Application Debug Launch Configuration to debug embedded Java code live, running inside a StreamBase Server instance that was launched with this option checked.

Server Logging Level

Select Current Studio logging level to use the logging level that Studio knows about at launch time. If you start Studio with a higher log level, launch configurations that use this setting will use the higher logging level.

Select Specified to override the global logging level. The higher the log level number you specify, the more messages and message types are sent to the Console View and/or to an output log file, if this launch configuration specifies one.

Persistent Data Options

This option specifies a directory to be used for persistent data in disk-based Query Tables (available only in StreamBase Enterprise Edition). This is the same option specified as --datadir when running sbd from the command line. Use the default or specify an existing directory, accessible to and writable by StreamBase Server.

Working Directory

Use this option to change the working directory for a local launch. Any files output by your running application (for example, generated CSV files) are created relative to your working directory. By default, the working directory is the folder that contains the application file you are launching. Click Specified to enter a different working directory. This option is ignored for remote target servers.

The Containers Tab

Running Applications in Containers

Use the Containers tab to specify one or more containers to hold and run other StreamBase applications that you want to start at the same time as the primary application specified on the Main tab. StreamBase containers are described on Container Overview.

With multiple applications running in containers, the names of streams in applications running in non-default containers are prefixed with the container name. Thus, sideplay.OutgoingBids refers to the output stream named OutgoingBids in the application running in the container named sideplay.

Most of the features of running an application in Studio apply to applications running in containers as well. This includes:

In the Manual Input view, you can send tuples manually to input streams in non-default containers.
The Application Input view shows tuples sent to all input streams, including those in non-default containers.
The Application Output view shows tuples from all output streams in all running containers.

However, running multiple containers in Studio has the following limitations:

The primary StreamBase application, the one specified on the Main tab, is always started in a container named default. You cannot change the name of the container for the primary application.
When debugging, only the path through the primary application is traversed. Debugging does not step across container boundaries.
You cannot run separate feed simulations in Studio for the primary application and for applications running in containers. Only streams in the default container can be addressed.
You cannot use the launch configuration dialogs to specify a container connection for streams in the primary application. However, you can specify the same connection from the point of view of the other container in the connection.

Setting Module Parameters

To specify parameters for modules running in containers, first select the line for the container of interest in the Application-Container Name grid. To specify parameters for the top-level application, select the line with the container named default.

Click the New Parameter button, and specify the Name and Value settings. The parameter name you specify must be already defined with the Parameters tab of the EventFlow Editor for the module specified to run in the selected container. See Using Module Parameters for more on module parameters.

Making Container Connections

Use the Selected Container Parameters and Connections grid to specify one or more connections between containers. Container connections are described in Container Connections.

You will typically use this feature to specify a stream-to-stream connection, where an input stream in one application and container receives tuples from an output stream in another application and container. However, you can specify any container connection type in the Containers tab that you can specify in the server configuration file or interactively with the sbadmin command, as described in Container Connections.

To specify a container connection, first select the line for the container of interest in the Containers section of the tab. (You cannot select the line for the container named default. Instead, make a connection in another container back to to a stream in the default application.) Click the New button, and specify the Source and Destination streams, using stream names qualified with the container name, as shown in this example:

You can use Ctrl+Space in the Source and Destination fields to invoke auto-completion to show the list of available streams. The list of streams shown is context-sensitive and includes only the streams appropriate for the Source and Destination sides of the connection.

Select an existing container connection line to activate the Edit, Duplicate, and Remove buttons. To create a container connection that is very similar to an existing connection, use the Duplicate button to copy the existing connection, then select the new connection and use the Edit button to modify the new connection.

Container Start Order

Use the Move Up and Move Down buttons to specify container start order. Studio starts containers in the order listed in the top grid in the Containers tab.

For some container connections to work, you must specify a non-default container start order. For example, if you specify a container connection that causes the primary application to read from a stream in another container, Studio fails to start the primary application unless the other container is started and already running.

It is possible to specify container connections in the application itself, using the Container connection field in the Advanced tab of the Properties view for input and output streams. In this case, you may need to adjust the container start order to allow the container with the outgoing stream to start before the container with the incoming stream.

The Environment Tab

The settings in the Environment tab are common to all Eclipse launch configurations. Use Eclipse Help to learn how more about these options. Use the Environment tab to specify or override environment variables with which to launch the application specified in the Main tab.

You can define new, application-specific environment variables with the New button, or you can override or append to existing system environment variables. Use the Select button to show a list of the system's currently set environment variables, from which you can select one or more. Once a system variable is in the table, use the Edit button to change or append to its value.

You cannot replace or override the STREAMBASE_HOME, PATH, STREAMBASE_JVM_ARGS, or STREAMBASE_LOG_LEVEL variables.

The New/Edit Environment Variable dialog contains a Variables button, which is a feature inherited from Eclipse. Use this button to specify the value of an environment variable using one or more Eclipse system variables whose contents are resolved by Eclipse when this configuration is run. Use the circled question mark help button on this dialog for further information on this Eclipse feature.

The Common Tab

The settings in the Common tab are common to all Eclipse launch configurations. Use Eclipse Help to learn how more about these options.

Save as

This option determines where this launch configuration is saved. The default setting, Local file, saves configurations in the workspace metadata area. As an alternative, you can select Shared file to save this launch configuration as a file in one of your Project folders. In this case, the launch configuration is saved as Name.launch, where Name is specified in the Name field. Specify the target Project folder using the Browse button.

Display in favorites menu

The favorites menu is a list of launch configuration names that appears in the second section of the drop-down menu of the Run and Debug buttons on the toolbar. The first section contains a changing list of recently-run launch configurations. Add a configuration to the favorites section to keep it in the menu, even when other applications have replaced it in the recently-run section. This option performs the same function as the Organize Favorites option in the Run and Debug drop-down menus.

Console Encoding

Use this section to specify a non-default character encoding for log messages sent to the Console View (and optionally to a standard output file).

Standard Input and Output

Allocate Console is checked by default. This specifies using the Console view to display logging messages written to standard output and standard error, and to accept text input, if your application requires it. You can disable this option for launch configurations that will run on remote StreamBase Servers.

File is unchecked by default. To specify that standard output and standard error of your application's run are written to a log file, check the File checkbox, and enter a path to an existing file. If both Allocate Console and File are checked, log messages are written to both places. You must designate the path to the file using an Eclipse-specific syntax. Rather than typing a path, use the Browse Workspace or Browse File System buttons to navigate to an existing file, and let Eclipse write the syntax for you. To navigate to a file in the workspace, you must first have created it with Studio's File → New → File menu option. If you are familiar with the Eclipse syntax required in this field, you can use the Variables button to build up a path from components.

Append is dimmed unless File is checked. Check the Append checkbox to have log messages appended to the file specified in the File field. By default, the file is overwritten with each run of this launch configuration.

Launch in background

Use this option to specify that the launching process itself runs in the background. (StreamBase Server is always run in the background.) Checking this box returns control of Studio immediately, without displaying the usual Starting Server dialogs, after you click Run or use the toolbar Run button later to launch this configuration.

Launch Configuration Perspective-Change Preferences

By default, running or debugging a StreamBase application with a launch configuration automatically switches StreamBase Studio to the SB Test/Debug perspective, after prompting you to confirm. You can specify on the prompt dialog to not ask again.

The option to switch perspectives is not stored in the launch configuration itself, but is a global setting for all StreamBase applications, as specified in StreamBase Studio Preferences.

Back to Top ^