Bundler

Overview

To use the Bundler panel, open the Project Properties dialog for the Studio project of interest as described in StreamBase Project Properties. Select Bundler from the contents column on the left.

Use the Bundler panel to specify any third-party resource files (or folders containing such files) that you want included in StreamBase bundle files generated for an application in this project folder. Files and folders specified on this page are included in bundles generated both with the Studio export-as-bundle feature and with the sbbundle -p|-P command.

StreamBase bundle files automatically include all Java classes compiled from Java source folders, JARs referenced in the Java Build Path, and any files referenced by Java operators or adapters using GetResourceFile() or similar StreamBase Client API methods. By contrast, certain other resource files are not automatically included in the bundle, as discussed on Application Bundling.

The Bundler properties page provides a way to include resource files needed by third party libraries, or files needed by a StreamBase module that are not loaded as part of the module's typechecking environment. Examples of files to specify on this page include, but are not limited to:

  • Configuration files for either the LogBack or Log4j logging subsystems.

  • CSV files to serve as input to the CSV File Reader adapter, in cases where the file name is specified dynamically to the adapter's control port by an upstream operator.

  • Security certificate files used by a third-party library.

  • Files read by or written by third-party libraries.

  • In some special cases, native library files.

The logging-log4j and logging-logback samples included with StreamBase provide illustrations of specifying a third-party resource file for inclusion in a bundle made from those sample projects.

Selecting Files to Include in Bundles

To open the Bundler project Properties page:

  1. Use the steps shown in StreamBase Project Properties to open the project Properties dialog for the Studio project of interest.

  2. Open the StreamBase node in the left column, and select Bundler.

Use the Add button to add files or folders to the list. This opens a dialog that lets you browse for files in the current project.

Select the Show .* resources check box to show for selection any files and folders whose name begins with a period.

Specifying Paths for Bundled Resource Files

When you select a file or folder with the Add button, by default Studio specifies (default) in the Path in Bundle column. When an application in this project folder is bundled, files or folders with (default) entries are placed in the bundle's /resources folder. This folder is automatically on the resource search path for the project, which means files placed in the default bundle location will be found at runtime when the bundle is run.

However, your application, or a third-party library used by your application, may expect to find a particular resource file in a particular location. In this case, you can click to edit the Path in Bundle column for each entry in the Required Resources grid. Specify a path relative to the bundle's root directory where a resource file is expected, using the following guidelines:

  • In the Path in Bundle column, specify any path relative to the bundle's root. The file or folder on that line will be placed in the specified Path in Bundle folder.

  • The bundle's root directory will be the runtime working directory of the sbd process when the bundle is run.

  • Remember that you can specify the file system location from which to run a bundle by using the -w option, as shown in this example:

    sbd -w /home/sbuser/runfromhere myapp.sbbundle

Choose your relative paths carefully to make sure your application runs equally well:

  • from Studio

  • interactively at the command prompt with the sbd command

  • when run as a bundle

In particular, if a resource file is referenced by relative path in your project's sbd.sbconf configuration file, then be sure to specify the same relative path in the Bundler Properties page so that the file is bundled into the path expected by the configuration file.

Using the Bundler Properties page, you cannot select any file or folder that is outside of the current Studio project. TIBCO recommends always using paths relative to the project's root for maximum portability of the bundle to run on different servers. However there may be third-party libraries that expect to find resource files at fixed file system locations outside the Studio project's boundaries. In this case, you can:

  • Use symbolic links to place a link inside the project workspace folder to the path outside the project folder.

  • Generate your bundle files with the sbbundle command instead of Studio export-as-bundle. The sbbundle command allows you to specify any path with its -I or --include options, which are the equivalent of this Bundler project Properties page.

Examples

Example 1. In the logging-logback sample included with StreamBase, the sbd.sbconf specifies a system property that defines the location of the Logback configuration file, logback.xml, at the root of the Studio project:

...
<sysproperty name="logback.configurationFile" value="logback.xml"/>
...

To match this specification when the project is bundled, the Bundler page of the sample_logging-logback project specifies a single slash ( / ) as the bundle location of logback.xml:

Example 2. In a fictional project, let's say a third-party market data feed, AZData, requires a security certificate file to be present in a folder named config, placed relative to the folder from which StreamBase Server is run. In this case, create a Studio project folder named config, and place the security file, AZData.cert, in that folder. The application should now run both in Studio and at the command prompt.

To make sure the same application can run when bundled, use the Bundler project Properties page to add the following file and path:

Project Resource Path in Bundle
AZData.cert /config