Contents
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 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. |
Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. 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 to learn about Error Ports.
Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
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
.sbintinterface 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 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 > 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. 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 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 , , , , and buttons:
- Add
-
Use the 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 . 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 .
- Up, Down
-
Use the and buttons to reorder the list of modules in the Module Instances grid.
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.
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.
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.
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.
Further information about StreamBase Interfaces: