Application Bundling

< Previous		Next >

Introduction

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.

Running Bundles

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.

Important

The version of StreamBase and of any called resources must be the same on the machine that runs the bundle as on the machine that generates the bundle. The StreamBase Server version is normally specific down to the minor release, which is specified in the second position in the release number. However, occasionally a maintenance release introduces changes that require the same or later maintenance release to run.

You can direct StreamBase Server to override version checking of bundles by using the --override-version-checking switch with your sbd command. Incompatibilities between the bundled application and the server may still prevent the bundle from running.

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

How Bundles Are Run

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.

Bundling Prerequisites

In general:

If you can successfully run an application from the command line with the sbd command and a server configuration file, then you can create an application bundle for that application using the sbbundle command.
If you can successfully run an application in Studio, then you can bundle it in Studio.
If you can successfully bundle an application in Studio, you can do the same at the command line using sbbundle -p or -P.

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.

Bundling Studio Project Property Settings

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.

Referencing Java Classpath Variables

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.

Emulate Studio Bundling at the Command Line

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.

Creating a Bundle with the sbbundle Command

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

Starting Points When Using sbbundle

When generating an application bundle file with the sbbundle command, you must specify one of the following starting points for the bundler to parse, so that it can locate the module and resource files that must be included in the bundle:

A top-level EventFlow or StreamSQL module file with the –a option.
A StreamBase deployment file that specifies a top-level module to run in its <application> element.
Only a server configuration file with the –f option. In this case, the configuration file must specify the name of the top-level application module in an <application> child element of the <runtime> element. (This is a deprecated configuration.)

You can optionally specify:

A server configuration file with the –f option to accompany the top-level module or deployment file starting points. Directives in the configuration file are converted into a bundle-specific configuration file that uses bundle-specific paths and locations.
A Studio project directory for consideration of its project metadata, as described in Bundling Studio Project Property Settings.

Example sbbundle Commands

See sbbundle for details on the command syntax. The following are examples of the sbbundle command:

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

In the following example, the .sbconf file must name the top-level module to run in an <application> child element of the <runtime> element (but this is a deprecated configuration).

sbbundle -f coreapp.sbconf app4.sbbundle

The example below excludes the entire .svn directory from the bundle.

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

The Windows example below specifies the relative paths to two project directories, one of which contains the deployment file to be bundled. The combined metadata of both projects is to be considered when generating the bundle's configuration file:

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

The UNIX version of the same example uses UNIX path separators:

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

Here is the same command for Windows, if your current directory is thisproject:

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

Making Corrections in the Bundle's Configuration File

The sbbundle command has options that allow you to extract the bundle-specific configuration file from the bundle. You can then edit the extracted file and place the edited file back in the bundle. This feature allows you to specify, for example, a development-only URI for a JDBC data source and bundle the application with that development-only reference. You then:

Extract the bundled configuration file.
Edit it to specify a deployment-specific JDBC URI.
Replace the configuration file back in the bundle.

The edited bundle is then ready to run from the command line with sbd in the deployment environment.

For example:

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

The .sbconf file generated by the bundler and placed in the bundle is always named bundle.sbconf. You can specify any file name with the –x option; this is the name to give the extracted .sbconf, not the name of the .sbconf in the bundle. Likewise, with the –r option, specify the extracted name of the bundle's .sbconf file. The sbbundle –r command does the work of renaming the edited .sbconf back to bundle.sbconf for placement back into the bundle.

Exporting a Bundle in StreamBase Studio

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

Starting Points When Exporting a Bundle in Studio

When exporting a project to an application bundle file in Studio, you must specify either:

A Studio launch configuration.
A top-level EventFlow or StreamSQL module file.
A StreamBase deployment file that specifies a top-level module to run in an <application> element.

Before running the Studio bundle export wizard, decide in advance whether to base the bundle on a Studio launch configuration, a deployment file, or a top-level module file.

Basing a Bundle on a Launch Configuration

In a Studio launch configuration, you can specify containers for sub-modules, container connections, and other container parameters. These constructs are honored in the bundle when you base a bundle on a launch configuration. See Editing Launch Configurations for more on creating and editing launch configurations.

When you specify a launch configuration as the starting point of a bundle, the bundler preserves in the generated bundle file the following information extracted from the launch configuration:

The path to the top-level module file to run.
Any module parameters specified for the top-level module on the Containers tab.
Any non-default containers, container start order, container connections, and container parameters specified on the Containers tab.

The bundler does not attempt to preserve information on other tabs of the launch configuration. In particular, any specification in the launch configuration of a remote server and username are ignored and are not placed in the bundle.

Steps to Export a Bundle in Studio

To export an application bundle in Studio, follow these steps:

Run File → Export from the top-level Studio menu.

As an alternative, select a top-level EventFlow or StreamSQL module file, or a deployment file, in the Package Explorer. Then right-click and select Export from the context menu. In this case, the selected module or deployment file is pre-selected in the StreamBase Export dialog.
In the Export dialog, open the StreamBase folder, then StreamBase Application Bundle.
Click Next. This opens the StreamBase Export dialog.
Fill in the dialog as described in the next section.
When done, click Finish.

Bundle files cannot be run from Studio. To test your new bundle file, open a StreamBase Command Prompt on Windows or a terminal window on UNIX, and run the bundle file as an argument of the sbd command.

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.

What Files Get Bundled

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

The top-level EventFlow or StreamSQL module.
Any EventFlow or StreamSQL modules referenced by the top-level module, and modules referenced by modules.
Any Java class files referenced by modules in the application.
Any resource files referenced by an adapter or operator in the application. Resource files might include CSV files, initialization files, security certificate files, and so on.

Exception: resource files used by third-party libraries are not bundled.
A generated bundle-specific server configuration file that describes the bundled location of module and resource files. The bundle's configuration file also preserves references to JDBC data sources and to non-native libraries exactly as found in the original pre-bundled configuration file.
Optional. If specified, you can include a precompiled archive version of the top-level application, as discussed below in Bundling and Precompiled Archive Files.

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

A StreamBase deployment file.
A Studio launch configuration.
<application> elements in a server configuration file (deprecated).

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.

How the Bundler Locates Files for Bundling

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.

Enforcing Typechecking

Both Studio and command line bundlers enforce that all referenced modules pass typechecking. Bundling cannot proceed until all modules pass.

Locating Module Files

Both Studio and command line bundlers parse the top-level module file to determine all sub-modules referenced. The Studio bundler locates referenced module files on the Studio project's module search path.

The command line bundler has two methods: with -p or -P and the path to a Studio project folder, sbbundle can also locate module files on the Studio project's module search path. Without -p or -P, the module search path must be defined with <module-search> elements in a server configuration file.

Locating Java Class Files

Your application might reference Java classes that define custom functions, operators, or adapters. An operator or adapter might also reference third-party Java classes. The Studio bundler locates referenced Java classes on the Studio project's Java Build Path. The command line bundler can also take advantage of the Studio project's Java Build Path when using the -p or -P options. Without those options, the command line bundler relies on <jar> and <dir> elements in the server configuration file to locate referenced class files.

Note

Studio and sbbundle -p|P both ignore <jar> and <dir> elements in the server configuration file. See Configuration Elements Ignored in Studio Launches for details.

Locating Resource Files

With the Studio bundler, resource files referenced by operators and adapters (including CSV, initialization, and security certificate files) are included in a bundle if the files are locatable on the Studio project's resource search path and the file is referenced by the getResource() Java method. Files opened by other means in custom code, and any resource file referenced by a third-party library, are not automatically bundled.

The command line bundler has the same two criteria when using the -p or -P options. Without those options, the command line bundler locates resource files called by getResource() in directories specified in <operator-resource-search> elements in the server configuration file.

Configuration File Directives

Both bundlers honor the settings in a server configuration file specified to the bundler, and both bundlers pass those settings into the generated bundle-specific configuration file. However, the Studio bundler follows the same configuration file rules as for running applications in Studio:

The server configuration file must be named sbd.sbconf and must exist at the root of the Studio project directory.
Certain settings are ignored, as described in Configuration Elements Ignored in Studio Launches.

What Files Do Not Get Bundled

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

Global operators and adapters. Make sure you install any global adapters required by the bundled application on the StreamBase Server instance that will run the bundle, and make sure that Server installation is licensed to use those adapters.
Native code. Some applications make use of C++ plug-ins, or use Java operators or adapters that reference native DLL or .so libraries. If the bundler detects a native code reference in the configuration file, it issues a warning message and continues to generate the bundle. The configuration file's paths to native code libraries on the bundling machine are preserved in the bundle.

Despite the warning message, a bundled application that references native libraries can still run on StreamBase Server on another machine, under the following conditions: the server machine must have the exact same versions of the same native code library files, and those files must be locatable in the same paths on the StreamBase Server host as are specified in the original, pre-bundled configuration file for the bundling machine.
Resource files referenced by third-party libraries and resource files referenced in custom operator or adapter code using a method other than getResource(). You can explicitly include such files using the -I or --include options of the sbbundle command, or by using the Bundler project property page in Studio.

Bundling and Precompiled Archive Files

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 ^