Defining Module Reference Properties

A StreamBase application can be referenced by another application, as described in Using Application Modules. In an EventFlow, a module reference is the component within one application that links to the other application, which can call an application module.

This topic describes how to configure the properties of a module reference in the main application. Important module reference properties include the module name, the application that it references, and its input and output port associations.

Notes

Module reference properties apply only in the current, referencing application; any changes you make do not affect the referenced application module itself. or references to it in other applications.
This topic applies only to module references in an EventFlow. For details about defining module references in a StreamSQL Application, refer to Referencing an Application Module and the StreamSQL Guide.

Topics:

General Tab

Name: Every application component must have a unique name. Use this field to specify or change the component's name. 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.

Application:

If this is a module reference that you have created by dragging an sbapp or ssql file from your Package Explorer, the application's name appears here.
If you extracted a subset of components from an EventFlow, the name of the sbapp file created by StreamBase appears here.
If you inserted an empty module reference from the Palette view, this field is blank. Choose the application you want from the drop-down list.
If you have an empty module reference and the module you want to use is not listed, it might because the module is not in your project's search path - for example, it might be in a different project or outside of your workspace. To understand how to modify the search path to make modules available, please follow the guidelines in Managing Studio Resource Files.

To see what directories are currently in the search path, you can click the View search path active link, which opens the StreamBase page of your project's Properties dialog.

Enable Error Output Port: Check this 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 a description 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.

Schemas Tab

The Schemas tab enables you to display the schemas for each of the input ports of the module reference. Use the Show schema for control to choose which schema you want to view.

Input Ports Tab

Use this tab to add and remove input ports and assign schemas.

The ports on the module reference are assigned to the outer input and output streams of the referenced application. Therefore, when you connect a component to a module reference, the schema of the arc going into the module reference is passed into the referenced application. For more information about input and output port associations in module references, refer to Extracting an Application Module.

The names and schemas of these streams are initially inherited from the referenced application module. However, module references can be changed independently from their original applications. Therefore, as you work with a module reference you may need to know how module streams correspond to the input and output streams in the referenced application. In some cases, the port associations might need to be changed. For example, if the name of a stream changes in an application module, a module reference that is linked to it might fail because a port cannot find its associated stream.

For these reasons, the Properties View allows you to see and manage the mapping of ports to module streams.

The Port associations table shows the current ports and their assignments, and provides the following ways of managing them:

If the module reference was extracted or inserted from the Package Explorer, the ports and assignments are automatically filled in for you.
If you are creating a new module reference, the port association is initially blank. Use the control buttons to create input ports and assign schemas to them. To do this manually, use the Add and Remove buttons. Alternatively, use the Assign All button to automatically create an input port for each input stream in the referenced application. The streams are assigned to ports in sorted order.
Use the drop-down control in the Module Stream field to define or change the stream assignment of a port.

Output Ports Tab

Use this tab to add and remove output ports and assign schemas.

The Port associations table shows the current ports and their assignments, and provides the following ways of managing them:

If the module reference was extracted or inserted from the Package Explorer, the ports and assignments are automatically filled in for you.
If you are creating a new module reference, the port association is initially blank. Use the control buttons to create input ports and assign schemas to them. To do this manually, use the Add and Remove buttons. Alternatively, use the Assign All button to automatically create an output port for each output stream in the referenced application. The streams are assigned to ports in sorted order.
Use the drop-down control in the Module Stream field to define or change the stream assignment of a port.

Table Associations Tab

If your Module Reference contains one or more placeholder tables, and you connect it to one or more Query Tables in the application outside the Module Reference, use this tab to map the connections to the Query Tables. The Application Table field is loaded automatically when you make each connection; use the Module Table control to specify the table you want to connect to within the module.

If properties are incomplete or incorrect, instead of an informational message, a red error icon and a problem description are displayed at the top of the tab. For example, if you create a new Input Stream, the component does not typecheck until you begin defining fields in its schema.

Parameters Tab

Use this tab to bind values to parameters that have been defined in the referenced application module (described in Using Module Parameters).

Click the "Show parameter definitions" link to display all the parameters. The list includes the name of each parameter, and any default value assigned in the application module.

Add a row for each parameter you want to bind. Include a row for any parameter that does not have a default value, or whose default value you want to override.

You can use either the Add button to edit rows manually, or the Fill All Rows button to load parameters for you. Clicking the small arrow to the right of the button presents these choices:

Fill with all module parameters: Loads a row for every parameter. Useful if you want to override default values.
Fill with required parameters only: Loads a row only for parameters for which there is no default value defined. Useful if you want to accept all default values.

Each row includes the parameter name and any default value assigned in the application module. For a screen shot see the example in Using Module Parameters.

Concurrency Tab

Run this component in a separate thread

This option causes the server to process the component's requests concurrently with other processing in the application. You can distribute the processing of the threads automatically across multiple processors on an SMP machine.

If this is a compute-intensive component and you know that it can run without data dependencies on other components in the StreamBase application, you may be able to improve performance by enabling this option.

Caution

These features are not suitable for every application. For details, see Execution Order, Concurrency, and Parallelism. It includes important guidelines for the use of these features.

Run in parallel threads

If you checked the first option, you can also choose this option, which causes the server to run multiple instances of this component. That is, each instance runs in its own thread. At run time, tuples are dispatched to particular instances based on the Key Expression value (which must evaluate to an int).