Referencing an Application Module

This topic explains how to reference an application module from another application. The procedure is either graphical or text-based, depending on whether the reference is in an EventFlow or in a StreamSQL application.

Before You Begin

Both procedures in this topic assume that you have performed the prerequisite tasks outlined in Using Application Modules:

  • You have created an application module (or will use an existing module) that is compatible with the main application you will reference it from.

  • The schema field names and types must be the same; the order of fields can be different.

  • The main application must be able to locate the referenced application module. To be referenced, a module must be in either the current project; another, referenced project; or an external directory that is configured in your project's sbd.sbconf file.

Referencing an Application Module in an EventFlow Application

In an EventFlow, a module reference is represented as a single component that you insert onto the canvas. Just like any other component, it can be connected to other components and has properties that can be edited and typechecked.

  1. In the StreamBase Studio SB Authoring perspective, open the EventFlow that will contain the module reference.

  2. In the Editor tab, insert an application module in the EventFlow Editor canvas by using one of these methods:

    • Open the Modules drawer of the Palette and identify the application module you want to reference. The Modules drawer lists the sbapp and ssql applications available to be referenced by your application.

      Drag the module into your EventFlow Editor, creating a new module reference on your canvas. Because the referenced application is defined, the module reference's properties are already defined, and its icon includes ports for any input and output streams that the application module had.

      For example, suppose we have the following application module named lock.sbapp:

      Now suppose we want to reuse lock.sbapp in another application. The next figure shows another another EventFlow, referencing.sbapp, after we have dragged lock.sbapp into it.

      Notice how the module reference name, generated by StreamBase Studio, is based on the application module name.

    • Drag a Module Reference icon from the Palette view. This creates a new, empty module reference in your application, as the next figure shows. Notice that it has no ports, and the yellow background indicates that it needs connecting and configuring. You will need to edit its properties and address those problems in the next steps.

  3. If the new module reference is empty (or if you need to change its properties), open its Properties view and edit its properties. See Defining Module Reference Properties for details. Note that changing module reference properties does not change the application module being referenced: it is a local change that affects only the referencing application. When you are done, module reference should not contain or cause any typecheck errors.

  4. If the referenced application contains parameters, you may need to set or modify the parameter values, as described in Using Module Parameters.

  5. Optionally, you can enable the concurrency option ("Run this component in a separate thread") on the General tab of the module reference's Properties view. Selecting this option is only appropriate if you know that the components in the module reference can run without dependencies on other streaming data in your application. On an SMP machine, the distribution of the threads across available processors happens automatically.

  6. Draw arcs connecting the input and output module reference ports to the appropriate components of your application, as shown in the preceding figure.

  7. Save your application.

Referencing an Application Module in a StreamSQL Application

In a StreamSQL application, module references are made using text StreamSQL statements, not the graphical "drag and drop" method.

  1. Identify the application module in the Package Explorer that you want to reuse. The module must be in either the current project; another, referenced project; or an external directory that is configured in your project's sbd.sbconf file.

  2. Open the application module, and identify the names of its input and output streams.

    • For an EventFlow, you can see the input and output streams on the canvas. In the topic's first figure, the lock.sbapp EventFlow clearly shows the input streams named input_stream and unlock_stream, and the output streams named unlock_key and work_done.

    • If the module is a StreamSQL application, the names are specified in the CREATE INPUT STREAM and CREATE INPUT STREAM statements. The following StreamSQL application example, lock.ssql, is functionally equivalent to the lock.sbapp application we just showed, and has the same input and output stream names: 

      CREATE LOCKSET l (i int, s string(4));
CREATE INPUT STREAM input_stream (number int, symbol string(4), price double);
CREATE INPUT STREAM unlock_stream (num int, sym string(4));
CREATE STREAM do_work;
CREATE OUTPUT STREAM unlock_key;

LOCK l ON number, symbol FROM input_stream INTO do_work;
CREATE OUTPUT STREAM work_done AS
    SELECT * FROM do_work;
UNLOCK l ON num, sym FROM unlock_stream INTO unlock_key;

  3. In the StreamBase Studio SB Authoring perspective, open the StreamSQL application that will reference the application module. At the appropriate place, insert an APPLY MODULE statement that references the module identified in the previous step. In the APPLY MODULE statement, include:

    • A FROM statement that maps each of the referenced module's input streams to the appropriate stream in the application.

    • An INTO statement that maps each of the referenced module's output streams to the appropriate stream in the application.

    For example, the following application (let's call it referencing.ssql) references the lock.ssql application: 

    CREATE INPUT STREAM submitter (number int, symbol string(4), price double);
CREATE INPUT STREAM unlocker (num int, sym string(4));
CREATE OUTPUT STREAM completed;
CREATE OUTPUT STREAM unlock_key;

APPLY MODULE "lock.ssql"
    FROM input_stream=submitter, unlock_stream=unlocker
    INTO work_done=completed, unlock_key=unlock_key;

    Notice how the FROM and TO statements map the streams of the two applications. Because this StreamSQL application is functionally equivalent to referencing.sbapp, the preceding EventFlows graphically show the same mapping of streams.

  4. If the referenced application contains parameters, you may need to set or modify the parameter values, as described in Using Module Parameters.

Viewing or Editing a Referenced Application Module

It's sometimes useful to look at a referenced application module to see what it contains. You can view or modify the properties of an application module in two ways:

  • Find the application in the Properties view and open it (for example, double-click the application).

  • In the referencing EventFlow, right-click the module reference component. Instead of choosing Open in Properties View, choose Open Application Module in Editor.

Note

Edit an application module with caution. Changes can affect every application that references it.

Related Topics

Back to Top ^