Application Bundling

A StreamBase application bundle is an archive file that contains a deployable application environment, which is the collection of files needed to deploy and run a StreamBase application on a supported StreamBase Server. A typical use for bundle files is to package a StreamBase application so that it is ready for deployment.

You can create application bundles in StreamBase Studio by exporting a Studio project, or at the command prompt with the sbbundle command.

StreamBase bundle files are generated in JAR archive format, which is also the industry-standard Zip format.

Once created, you can run a bundle as an argument to the sbd command just as you would run an EventFlow, StreamSQL, precompiled archive file, or deployment file. Just as with unbundled StreamBase applications, you can create and run an application bundle on any supported machine configuration. The following example shows sbd running an application bundle:

sbd myApp.sbbundle

The .sbbundle extension is required in the names of bundle files.

The bundle contains a bundle-specific server configuration file. For this reason, it is an error to specify the sbd command's -f option along with a bundle file argument.

There is no provision for running bundle files in StreamBase Studio.

When you run a bundle with a simple command such as sbd myApp.sbbundle, the sbd startup code creates a temporary directory, unzips the bundle there, and runs the sbd command as specified in the bundle's configuration file.

When using the -w or --working-directory options in conjunction with running a bundle file, the working directory you specify is where the bundle file is unzipped before running its contents.

If you specify an empty directory with -w, it is treated as a temporary directory, and is automatically and silently deleted when sbd exits.

If you use -w, but specify a path to a directory with any existing contents, that directory is preserved on sbd exit. You can use the streambase.sbd.delete-working-bundle-dir system property to modify this delete on exit behavior. Set -Dstreambase.sbd.delete-working-bundle-dir=true to delete the working directory's contents even if you specify a non-empty path with -w. You can use the sbd command's -J option to specify the system property on the sbd command line.

In general:

Exceptions to these general rules are noted in the sections below.

There are cases where an application can be successfully launched and run in Studio, but fails to run at the command prompt with sbd. These cases usually involve external resources such as custom Java operators or adapters that Studio knows how to locate from the project's Java Build Path, but sbd does not. The solution is to create a server configuration file that identifies the same Java resources in <jar> or <dir> elements. When you can successfully run your application with sbd -f sbd.sbconf appname, you are ready to create an application bundle of the same application that will run from the command line.

A Studio project stores a complex set of metadata that can include project references to other projects, a customized Java build path, an extended module search path, or an extended search path for resource files. This information is specified in the Properties dialog for the project that you invoke from project's context menu in the Package Explorer.

When creating a bundle in Studio, Studio project metadata is automatically included in the bundle.

For example, one project, A, might have a project reference to project B, and A/toplevel.sbapp references the B/definitions.sbapp module. The resulting bundle of toplevel.sbapp in project A would automatically include a copy of B/definitions.sbapp.

Unless you prefer or require a single file to execute in sbd, in most cases you can run your application with sbd -f sbd.sbconf appname. Starting in release 7.4, StreamBase Studio automatically maintains each project's sbd.sbconf server configuration file in a ready-to-run state. That is, it points to all resources necessary to run the application. For more information, see How StreamBase Studio Uses Server Configuration Files.

When you bundle applications in projects created in StreamBase Studio from the command line and you are using any Eclipse Classpath Variables, you must define them when invoking sbbundle using the --classpath-variable (or -V) option. Within Eclipse, your workspace defines these variables. When bundling outside of Eclipse/Studio, workspace preferences are not available.

The option's syntax is sbbundle -V name=path or sbbundle --classpath-variable name=path, where path is an absolute file system path and name is the name of the Classpath Variable used by your projects. You can define more than one variable name using this option. To do so, repeat -V (or --classpath-variable) with arguments for each name you declare. For more information on Classpath Variables, see the help at eclipse.org.

The sbbundle command, when used with its –p or –P options, can automatically incorporate project metadata into the bundle, in the same way as the Studio bundler. This allows you to add an sbbundle -p command to your application's build script or Makefile to generate a runnable bundle that works the same way as a Studio-generated bundle.

As arguments for the -p or -P option, specify a colon-separated list (UNIX) or semicolon-separated list (Windows) of relative paths to Studio project directories in your Studio workspace. List all projects whose Studio metadata is to be considered when generating the bundle. With these options, the bundler generates a server configuration file for inclusion in the bundle that is based on the metadata of the specified projects.

When used as lowercase –p, the search for project metadata is restricted to the directory paths named as arguments. When used as uppercase –P, each specified project directory is recursively scanned for further Studio project directories.

Use the sbbundle command interactively, or as part of a build script to automatically generate your application's bundle file for deployment.

sbbundle -a topLevelApp.sbapp app1.sbbundle
sbbundle -a deployment.sbdeploy app2.sbbundle
sbbundle -a orderrouter.ssql -f sbd.sbconf app3.sbbundle

sbbundle -f coreapp.sbconf app4.sbbundle

sbbundle -i .svn -a topLevelApp.sbapp app5.sbbundle

cd myprojects
sbbundle -p thisproject;otherproject thisproject\deployment.sbdeploy app6.sbbundle

sbbundle -p thisproject:otherproject thisproject/deployment.sbdeploy app6.sbbundle

sbbundle -p .;..\otherproject deployment.sbdeploy app6.sbbundle

sbbundle -x extracted.sbconf app7.sbbundle
edit extracted.sbconf
sbbundle -r extracted.sbconf app7.sbbundle

This section describes how to interactively export an application's project to a bundle file in Studio.

The StreamBase Export Dialog

The StreamBase Export dialog is shown in the following example:

Use the following points to understand the options in the StreamBase Export dialog.

StreamBase Application Launch Configuration

This option is dimmed unless your Studio workspace includes at least one launch configuration. You must select either this option or the StreamBase Applications or Deployment Files option.

Use this option to base your application bundle on a Studio launch configuration, selecting the desired launch configuration name from the drop-down list (which shows all launch configurations in the Studio workspace). You might base your bundle on a launch configuration in order to preserve the configuration's specifications of containers, container start order, container connections, and container parameters.

StreamBase Applications

You must select either this option or the StreamBase Application Launch Configuration option. This option shows a tree view of the EventFlow, StreamSQL, and deployment files in the Studio workspace, organized by project folders.

Locate and select the top-level module or deployment you want to bundle. (If you entered the dialog from the context menu of a module or deployment file in the Package Explorer, that file is pre-selected.)

To file

Type a path or browse to a directory location and specify a file name for the bundle file to be created. The path can be in any location for which you have write rights, and does not need to be in the Studio workspace. Use the .sbbundle file name extension; this extension is added for you if you omit it, and is appended if you use a different extension.

Overwrite existing files without warning

Select this check box if you are re-creating an existing bundle file.

Include precompiled application in the bundle

Select this option to have the bundler generate a precompiled application from the specified application and include it in the bundle.

Ignore directories and files with these names

Provide a comma-separated list of files and directories in the selected application's project to exclude from the bundle. You can use this feature to exclude the state files for your version control system; for example, for Subversion, enter .svn.

Use the StreamBase Bundler property page ...

The text at the bottom of the dialog provides a link to open the Bundler page of the Project Properties for the selected project. This is a reminder that the bundling mechanism only includes files determined by the typechecking process. If your project has third-party resource files that must be included in the bundle to create a runnable application, click the link to specify those files on the Bundler Project Properties page. Then return to the StreamBase Export dialog to complete the creation of your bundle file. See the Bundler Properties Page for more on the types of files and folders you might need to specify separately.

A successful bundling of an application contains the following types of files, as appropriate for the bundled application:

The bundling process supports multiple containers and container connections if they are specified in:

The top-level module specified with the –a option is always bundled to run in the default container — that is, in a container named default.

The bundling mechanisms in Studio and in the sbbundle command have analogous but slightly different methods for locating the module and resource files that must be included in a bundle to make a runnable application.

The following resource types are NOT included in an application bundle:

When creating bundle files in StreamBase Studio, the Export Bundle dialog offers the option Include precompiled application in bundle. With this option enabled, the Export Bundle dialog generates a precompiled application from the top-level application and packages both application file and its precompiled version into the bundle.

Your Studio project may have the Speed up launches option selected in the project's properties (StreamBase → Project Builder), so that precompiled application files are generated automatically. In this case, the Studio bundler includes the most recently generated application instead of regenerating one.

When creating bundle files with the sbbundle command, you can specify the –c option to generate a precompiled application for the specified top-level application, which is then automatically included in the bundle.

You cannot specify an .sbar file created with sbargen for inclusion in a bundle, either with sbbundle or with the Studio bundler. See Precompiled Application Archives for more on precompiled application archives.

Back to top ^