Application Bundling

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 or at the command prompt with the sbbundle command.

Running Bundles

Once created, you can run a bundle as an argument to the sbd command just as you would run an EventFlow, StreamSQL, or precompiled archive 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.

Important

The version of StreamBase must be the same on the machine that runs the bundle as on the machine that generates the bundle. The StreamBase version is specific down to the minor release number, which is the second position in the release number. For example, a bundle file created with StreamBase release 6.2 can only be run with the sbd server from release 6.2. A bundle generated with release 6.2.0 runs as expected with release 6.2.2. However, a bundle created with 6.2.0 does not run with sbd release 6.3.

Bundling Prerequisites

In general, if you can successfully run an unbundled application file from the command line with the sbd command and a server configuration file, then you can create an application bundle for that application.

The bundling process parses the provided top-level EventFlow or StreamSQL application file, or its server configuration file, or both, to determine whether any modules or resources need to be included in the bundle. All definitions in the configuration file are preserved, and any referenced JAR files or other native resource files are included in the bundle:

  • The top-level application file is parsed to determine the modules called. If any EventFlow or StreamSQL modules are required, the bundler locates them and includes them in the bundle.

  • The configuration file is parsed to determine the application's need for external resources, such as custom operators or adapters in JAR or class format. The bundler then locates those files and includes them in the bundle.

There are cases where an application can be successfully launched and run in Studio, but does not run 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.

Creating a Bundle with the sbbundle Command

When using the sbbundle command line utility, specify either:

  • A top-level application file with the –a option, plus an optional configuration file with the –f option.

  • Only a 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 element.

The sbbundle command also has options that allow you to extract the bundle-specific configuration file from the bundle. You can then edit the extracted file, then place the edited file back in the bundle. This feature allows you to specify a development-only URI to 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, then place the configuration file back in the bundle. The edited bundle is then ready to run with sbd in the deployment environment.

The following are examples of the sbbundle command: 

sbbundle -a top-level-app.sbapp
sbbundle -a orderrouter.sbapp -f sbd.sbconf
sbbundle -f coreapp.sbconf
# In the last case, the sbconf file must name the top-level application
# in an <application> element.

See sbbundle for details on the command syntax.

Creating a Bundle in StreamBase Studio

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

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

  • In the Export dialog, open the StreamBase folder.

  • Select StreamBase Application Bundle and click Next.

  • On the next dialog page:

    • Select a project folder and open its plus sign.

    • Select a top-level EventFlow or StreamSQL application file.

    • In the To file field, type a path or Browse where you want to save the bundle file. Bundle files do not need to be saved in the Studio workspace. You can select any path for which the current machine and login name has write access.

    • Type a file name with sbbundle extension. (If you use the Browse button, the extension is added for you.)

    • Click Finish.

Bundle files cannot be run from Studio. To test your new bundle file, open a StreamBase Command Prompt or terminal window on UNIX, and try to run the bundle file with the sbd command.

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 application.

  • Any EventFlow or StreamSQL modules referenced by the top-level application, and modules referenced by modules.

  • Any Java JAR or class files containing code referenced in jar or library elements of the server configuration file.

  • Any resource files such as CSV or text files referenced in the server configuration file.

  • A generated bundle-specific server configuration file that references the included module and Java files in their bundle-specific locations. 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.

The bundling process supports multiple containers and container connections if they are specified in application elements in the configuration file. The top-level application specified with the –a option is always bundled to run in the default container.

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 that runs the bundle, and make sure the Server is licensed to use those adapters.

  • Native code. Some applications make use of C++ plug-ins or 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 are preserved in the bundle.

    Despite the warning message, a bundled application that references native libraries can still run on a 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 specified in the original, pre-bundled configuration file.

Bundling and Precompiled Archive Files

When creating bundle files in StreamBase Studio, any precompiled application archive file in the project folder is ignored. All application elements in the server configuration file are ignored, whether or not they specify the path to a precompiled archive file. Thus, bundle files generated from Studio never include, and cannot use, .sbar files.

When creating bundle files with the sbbundle command, if you specify a precompiled application archive file as the argument to –a, or in an application element in the configuration file, sbbundle adds the specified .sbar file to the bundle, but then issues a warning that the application's resource requirements could not be determined. A bundle file that includes an .sbar file may or may not run, depending on the resource requirements of the archived application in the .sbar file. Simple .sbar application files that do not call external resources are likely to run without error. But because sbbundle cannot parse .sbar files to determine their requirements, StreamBase does not guarantee that a bundle file containing an .sbar file will run.

Back to top ^