Module Search Path

Overview

The module search path is the path along which StreamBase searches for EventFlow and StreamSQL application modules that are referenced by an application in the current project.

StreamBase Studio prevents you from dragging an EventFlow or StreamSQL module file onto the currently open EventFlow canvas unless the project folder from which you are dragging is on the current application's module search path.

Add folders to the module search path as described in Adding to the Module Search Path.

You can see the module search path for the currently open application in several ways:

  • See a tree grid list of all modules and interfaces on the current project's module search path using the Module Explorer View. A button in the view's toolbar allows you to sort the view in module search path order.

  • See the calling order of the subfolders and referenced project folders on the current project's module search path in the Project Properties dialog.

  • Examine the module calling order of the currently selected EventFlow application using the Module Call Hierarchy View.

The module search path is maintained independently of the resource search path. This lets you set a wide search path for modules but a narrow one for resources, or the converse.

In the Package Explorer view, folders on the module search path are decorated with an overlay icon.

The operator sample group provides an example of putting module files in a separate subfolder. See Operator Sample Group.

Module Search Path Order of Precedence

StreamBase uses a predefined search sequence to resolve the location of a referenced module. The search for a module ends when the specified module's name is located. StreamBase searches the following locations in the following order:

  1. The containing folder of the calling application.

    Modules are created by default at the root of the project's folder, but you are free to organize your project into subfolders. If the calling application is in a subfolder, that subfolder is searched first.

  2. The root of the calling application's project folder. (Of course, if the calling application is in the root folder and not a subfolder, the root folder is searched first.)

  3. Any subfolder of the current project that has been designated as a member of the module search path in the project's properties dialog. Subfolders are searched in the order they are listed in the Project Folders grid of project properties dialog.

  4. The root folder of the first referenced project. The order of referenced projects is in simple alphabetic order by project name. (See Project References.)

  5. Any subfolders of the first referenced project, as specified in the Project Folders section of the referenced project's Module Search Path project property panel.

  6. The root folder of the next referenced project.

  7. Any subfolders of the next referenced project as specified in that project.

  8. A path specified in the <module-search> child element of the <global> element of the current project's server configuration file. (But configuration file paths of referenced projects are not exported to the current project.)

Modules in other locations are not automatically located.

The module search order of precedence is also used for locating resource files on the resource search path.

Adding to the Module Search Path

Add folders to the current project's module search path in the following ways:

  • Designate a subfolder of the current project folder as a member of the module search path using the Module Search Path panel of the project properties dialog as described in the next section.

  • Add a project reference to another project in the Studio workspace using the Project References panel of the project properties dialog. Limitation: referenced projects must exist in the current Studio workspace.

  • Add a file system path to the current project's server configuration file, as described in Using resources outside your workspace in Managing Resource Files in Studio. Limitation: Studio does not use modules specified in the configuration file when typechecking, running, or debugging the current module.

Module Search Path Property Panel

Contents of this section:

Project Folders Section
Hidden Module Folders
Private Module Folders
Resolved Module Search Path Section

Adjust the module search path of a Studio project using the Module Search Path panel of the project's Properties dialog. To use the panel, first open the Project Properties dialog for the project, as described in StreamBase Project Properties. Then select Module Search Path from the contents column on the left.

Use the Module Search Path property panel to:

  • View the overall module search order, including contributions from project references and the server configuration file.

  • Add a subfolder of the current project's folder to the module search path.

  • Manage the search order of subfolders for the current project and for any referencing projects.

  • Designate folders as hidden so that they do not appear in the Module Explorer view for the containing project or for referencing projects.

  • Designate folders as private so that they do not become part of the module search path for referencing projects.

Project Folders Section

Use the Project Folders on Module Search Path section of the Module Search Path panel to specify module-containing subfolders of the current project.

Use the Add button to add an existing subfolder in the current project to the module search path. Use the Up and Down buttons to manage the calling order of subfolders, and use the Remove button to take a subfolder out of the module search path.

Hidden Module Folders

Use the Hide/Unhide button to designate the currently selected subfolder or folders as hidden. This prevents those folders and their contents from appearing in the Module Explorer view for the current project or for referencing projects. This, in turn, prevents users from dragging a module from the Module Explorer view to an EventFlow module in the current or referencing project.

A hidden folder and any modules or interfaces therein is still visible in (and still draggable from) the Package Explorer view. In addition, you can toggle on or off the display of hidden folders in the Module Explorer view by means of the Show hidden folders option in the view's menu bar.

Private Module Folders

Folders specified in the Project Folders section of the Module Search Path panel are automatically exported to any other project that has a Project Reference to the current project. To prevent referencing projects from seeing and using the modules in a subfolder, use the Private/Exported button to designate that folder as private.

Private folders and their contents are visible in and referenceable from the containing project, but are removed from the module search path for any referencing project. Private folders are automatically hidden in the Module Explorer view for referencing projects, so there is no need to mark folders as both private and hidden.

Modules in private folders are not on the search path for the referencing project and cannot be used in the referencing project even if called internally in the containing project. For example, let's say ProjectA contains a module topA.sbapp which has module references to modules-public/public-module.sbapp and modules-private/private-module.sbapp. ProjectA's modules-private folder is designated private.

Another Studio project, ProjectB, has a project reference to ProjectA. The Module Explorer view for ProjectB shows that it can create module references both to topA.sbapp and to modules-public/public-module.sbapp.

However, any module reference in ProjectB to ProjectA's topA.sbapp does not succeed and always fails typechecking. This is because topA.sbapp has an internal reference to a private module that ProjectB cannot see.

Resolved Module Search Path Section

The Resolved Module Search Path grid at the bottom of the panel shows the actual module search order for this project, as determined by StreamBase. The grid has three columns:

Column Meaning
(first column) Empty in most cases. For file system locations specified in sbd.sbconf, the first column shows a yellow caution icon normally, or shows a red warning icon If you specify a path that StreamBase cannot locate. The yellow caution icon is a reminder that resources in file system locations are used by StreamBase Server, but are ignored while authoring in StreamBase Studio. Hover the mouse cursor over an icon to see the details of the caution or warning.
Resolved Workspace or File System Path Contains a path where StreamBase looks for modules.
  • Paths shows as(application directory) mark the folder that contains the current project's StreamBase top-level module. (This is usually the root of the project's folder in the Package Explorer, but might be a subfolder.)

  • Paths shown as built-in, selected folder, or project reference are shown relative to the root of the Studio workspace. These paths are all visible in the Package Explorer.

Source Contains one of the following values:
(built-in)

The subfolder, if any, that contains the module that calls other modules, and the root of the project folder for this module.

(selected folder)

A subfolder of the current project that you added in the Project Folders section of this dialog panel.

(project reference)

A folder or subfolder of another project listed in the Project References dialog panel.

sbd.sbconf

A folder listed by absolute path in the server configuration file for the current project.

Module Search Path Configuration File Snippets

Just below the Resolved Module Search Path grid, look for the Generate configuration file snippet controls.

Both links take the search path settings shown in the grid and write them out in the form of a valid fragment of a server configuration file. The purpose of these links is to create fragment configuration files that can be included in your project's top-level server configuration file using the <sb-include> or <xi:include> directives. This accelerates the creation of a server configuration file that can be used to run your project at the command prompt with the same settings used when running in Studio. The inclusion features of server configuration files are described in Using Modular Configuration Files.

The difference between the two links is as follows:

to workspace

This link opens a dialog showing your Studio workspace projects, and prompts you to select a project. Specify a name for your fragment file; the dialog provides the default name: modulesearchpath.include.sbconf. This link then writes the fragment configuration file using paths relative to the selected project. This is the most portable option.

to file system

This link opens a dialog that prompts you to select any local or network file system location, and prompts for a name for the fragment file, suggesting modulesearchpath.include.sbconf. This link then writes the fragment configuration file using full, absolute paths.

The following shows an example of a fragment configuration file, generated using the to workspace link above:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<streambase-configuration>
  <global>
    <module-search directory="." />
    <module-search directory="..\TC_common" />
    <module-search directory="..\TC_common\common" />
    <module-search directory="..\TC_common\common\util" />
    <module-search directory="..\TC_fx_handlers" />
    <module-search directory="..\TC_fx_handlers\common" />
    <module-search directory="..\TC_fx_handlers\venues\barclays-barx" />
    <module-search directory="..\TC_fx_handlers\venues\barclays-barx\private" />
    <module-search directory="..\TC_fx_handlers\venues\bbg-tradebook" />
    <module-search directory="..\TC_fx_handlers\venues\bbg-tradebook\private" />
    <module-search directory="..\TC_fx_handlers\venues\citifxesp" />
    <module-search directory="..\TC_fx_handlers\venues\citifxesp\private" />
  </global>
</streambase-configuration>