Using the Extension Point Operator

Overview

The Extension Point operator is like a Module Reference for interfaces. In the same way that a Module Reference provides input and output ports for sending the flow of tuples into a referenced module, the Extension Point operator references a StreamBase interface, and provides input and output ports for sending the flow of tuples into one or more modules that implement that interface.

An Extension Point operator hosts one or more module instances that implement the interface referenced by that operator. Each module instance is assigned an identifier to be used when uniquely addressing an individual module instance, such as with the Name dispatch style discussed in Properties: Concurrency Tab.

This topic describes how to configure the properties of an Extension Point in the calling module.

Extension Point Samples

Extension Point operators are illustrated in the following samples included with StreamBase:

Sample	Description
Interfaces Sample	Demonstrates how to use StreamBase interfaces to enforce a set of stream and schema definitions, and to use different implementations of the same interface for different purposes.
Extension Point Operator Sample	This sample uses an Extension Point operator to dispatch tuples based on a user-specified action to one of two modules, which double or triple an integer field within the tuple. If no action is specified, the tuple is sent to both modules. This sample illustrates StreamBase interfaces used with the Extension Point operator, and illustrates module dispatch based on a predicate condition.
Extension Point Deployment Sample	This sample is a variation of the Extension Point operator sample to illustrate the use of StreamBase deployment files. The StreamBase interface in this sample specifies externally defined modules. Two example `.sbdeploy` files are provided, which you use to run this sample.

Properties: General Tab

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.

Icon: Use this field to specify a custom icon for this operator to appear on the EventFlow canvas. Icon image files must be in PNG, GIF, or JPG format, and must exist in the current project's resource search path. Size your image file as appropriate to fit on the canvas without displacing adjacent operators, aiming for a recommended size of no more than about 64x64 pixels.

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: Modules Tab

Use the Modules tab to add module instances to this Extension Point. This tab has the following controls:

Interface link

Click this link to open the Interface Editor for the interface shown in the Interface field.

Interface field

If you created this Extension Point by dragging an .sbint interface file to the canvas, this field is filled in for you with the name of the interface that this Extension Point references. If you are defining an Extension Point yourself from scratch, use the drop-down list to select a StreamBase interface file. The list includes all interfaces in the module search path of the current project.

Choose button

Click the Choose button to open a dialog that helps you navigate a large module search path to find and select the interface file of interest.

View search path link

Click this link to open the StreamBase → Module Search Path panel of the current project's Properties dialog, which lets you view or change the current module search path.

Defined: Locally or Externally

Select Defined: Locally, the default setting, to use the Module instances grid to enumerate the modules that implement this operator's interface.

Select Defined: Externally to defer specification of implementing modules until runtime. In this case, you must provide an Extension Point ID, and must configure a StreamBase deployment file with the same ID, as described in Deployment Files and Extension Points. Extension point IDs are container-scoped and must be unique among all Extension Point components used in all modules in the same container. Choose a complex ID that is not likely to be mistaken for an ID in another module.

Module instances

The module instances grid displays when you select Defined: Locally. The grid shows each EventFlow or StreamSQL module added to this Extension Point. Each such module must implement the referenced interface. Each module instance is assigned a module identifier, and can have optional parameters that are passed to that module when invoked.

When you add two or more modules to the module instance grid, the Extension Point operator's canvas icon gains a circled number decoration to show the number of modules configured. For example, you can see without opening the Properties view that the following Extension Point has three module instances:

The module instances grid has Add, Edit, Remove, Up, and Down buttons:

Add

Use the Add button to open the Add Module Instance dialog. Select a module name from the Module drop-down list or click Choose to open the Choose Application Module dialog. The list of modules in both the drop-down and the Choose dialog is restricted to modules on the current project's module search path. Specify an identifier for the module you are adding.

If your application design includes passing parameters to module instances, enter one or more parameter names and the expression that determines the value of each.

Edit

Select a module instance in the grid and click Edit. This opens the Edit Module Instance dialog, which is used just like the Add dialog described above.

Remove

Select a module instance in the grid and click Remove.

Up, Down

Use the Up and Down buttons to reorder the list of modules in the Module Instances grid.

Properties: Input Ports Tab

Use this tab to view the association between the operator's input ports and the input ports defined by the referenced interface.

When you create an Extension Point by dragging an .sbint interface file to the canvas, the mapping between input ports and interface streams is done for you. Use the grid controls on the upper right of the grid only if you are defining every aspect of an Extension Point yourself from scratch. This should be rare.

Properties: Output Ports Tab

Use this tab to view the association between the operator's output ports and the output ports defined by the referenced interface.

When you create an Extension Point by dragging an .sbint interface file to the canvas, the mapping between output ports and interface streams is done for you. Use the grid controls on the upper right of the grid only if you are defining every aspect of an Extension Point yourself from scratch. This should be rare.

Properties: Tables Tab

Use the Tables tab to associate a placeholder Query Table defined in the referenced interface with an actual Query Table data construct in the containing module.

If the referenced interface does not define any placeholder Query Tables, this tab reports: Current interface contains no placeholder tables to configure.

If the referenced interface contains one or more placeholder tables, then the Extension Point operator appears with a gray diamond-shaped connector at the bottom of the token on the canvas. Connect this to the top connector of a Query Table data construct, which must be defined with the same table schema as the placeholder table in the interface. Then select the same table from the drop-down list in the Application Table column of this tab.

Properties: Concurrency Tab

Use the Concurrency tab to specify separate threading and to specify the dispatch style for input streams in this Extension Point operator.

The Concurrency options for the Extension Point operator differ from those of other operators and adapters in that there is no Multiplicity option. This is because managing multiple module instances is inherent in the design of this operator, and does not need to be added on.

The Run this component in a parallel region check box is a candidate for selection if the hosted module instances are long-running or compute-intensive, can run without data dependencies on other StreamBase components, and would not cause the containing module to block while waiting for one or more module instances to return. In this case, you may be able to improve performance by selecting this option. This option causes StreamBase Server to process the module instances concurrently with other processing in the application. The operating systems supported by StreamBase automatically distribute the processing of threads across multiple processors.

Caution

The separate thread setting is not suitable for every application, and using this setting requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

When one or more modules are listed as module instances for an Extension Point operator, incoming tuples are routed to those modules according to the dispatch style for each of the operator's incoming streams, as specified on the Concurrency tab. Two dispatch styles are available for the input streams of an Extension Point:

Broadcast. Sends incoming tuples in parallel to all module instances of the Extension Point operator.
Name. Routes incoming tuples to one of the Extension Point's module instances by module identifier, using logic in upstream components before entering the operator to determine and specify the module identifier to call. When you specify the Name dispatch style, you must also specify a Dispatch Expression that resolves to one of the module identifiers specified on the Modules tab or in an external StreamBase deployment file.

If the referenced interface defines more than one input stream, you can specify dispatch styles independently for each input stream of the Extension Point operator.

For example, let's say an Extension Point operator references the Colors interface, and hosts two module instances that implement the Colors interface, Red.sbapp and Blue.sbapp, with module identifiers red and blue assigned in either the Modules tab or in an external deployment file. The default settings specify the Broadcast dispatch style, which means a copy of the incoming tuple is sent in parallel to both red and blue module instances.

If you specify the Name dispatch style, you must also specify a Dispatch Expression that resolves to one of the two module instance identifiers red or blue. Thereafter, when a tuple arrives with a field whose contents resolve to red or blue, that tuple is sent only to the matching module instance.