sbbundle

StreamBase Application Bundle Generator — Creates StreamBase application bundles.

SYNOPSIS

sbbundle {-a appname.[sbapp|ssql|sbdeploy]} [-f config.sbconf] [-I|--include file1[@path1],file2[@path2],...] [-o] [-c] [-i ignorelist] [-Jjvm-option] {filename.sbbundle}

sbbundle {-a appname.[sbapp|ssql|sbdeploy]} [-p|-P projectdir1[:;]projectdir2[:;]...] [-V|--classpath-variable name=path...] [-I|--include file1[@path1],file2[@path2],...] [-o] [-c] [-i ignorelist] [-Jjvm-option] {filename.sbbundle}

sbbundle {-x sbconf-out} [-Jjvm-option] {filename.sbbundle}

sbbundle {-r sbconf-in} [-Jjvm-option] {filename.sbbundle}

DESCRIPTION

Use sbbundle to create or modify a StreamBase application bundle file, which must have the .sbbundle extension. A bundle file is an archive file that contains a deployable application environment. That is, it contains the collection of files needed to deploy and run a StreamBase application on StreamBase Server on a supported platform. A typical use for bundle files is to package a StreamBase application along with all required modules and resource files so that it is ready for deployment.

To run a bundled application, pass a bundle file as an argument to the sbd command that starts StreamBase Server. For example: 

sbd myapplication.sbbundle

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

To create a new bundle, you must specify one of the following starting points for the bundler to parse:

--A top-level EventFlow or StreamSQL application file.
--A StreamBase deployment file (.sbdeploy) that specifies a top-level module to run in its <application> element.
--A server configuration file (.sbconf file) that specifies a top-level application to run in its <application> element. (This is a deprecated configuration.)

The bundling process determines the necessary files to bundle by reading the top-level EventFlow or StreamSQL application specified directly or specified in a deployment or configuration file. The file is parsed to determine any modules called and resources referenced. If a server configuration file is provided, it is parsed by the bundler to determine the application's current requirements. All definitions in the configuration file are preserved, and any referenced JAR files or other native resource files are included in the bundle.

Just as with unbundled StreamBase applications, you can create and run an application bundle on any supported machine configuration. 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 version is normally specific down to the minor release, which occupies the second position in the release number. However, occasionally a maintenance release introduces changes that require the same or later maintenance release to run. For example, .sbbundle files created with the sbbundle command from StreamBase release 7.3.12 are likely to run with the StreamBase server from release 7.3.0 through 7.3.11, but in rare circumstances might use features that require a 7.3.12 sbd.

The StreamBase version is specific down to the minor release number, which is the second position in the release number. Thus, an .sbbundle file created with the sbbundle command from StreamBase release 7.0 can only be run with the sbd server from release 7.0.

If a specified configuration file references Java resources in <jar> and <dir> elements, those resources are included in the bundle, and the bundle's configuration file is rewritten to specify the bundled path of those resources.

If the application being bundled references a JDBC data source, then the same JDBC URI to access that data source must be accessible from the server host that runs the bundle. As an alternative, you can specify the path to a test data source during development, and bundle the application with a configuration file that references the test data source. You can later extract the configuration file from the bundle using the -x option, edit the JDBC URI to point to a production data source, then replace the edited configuration file back into the bundle using the -r option.

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

The following resource types are NOT included in the bundle:

--Global operators and adapters.
--Native code, such as C++ plug-ins in the form of native DLL or .so library files.

For more information, see What Files Do Not Get Bundled on the Application Bundling page in the Administration Guide.

OPTIONS

-h, --help

Displays usage text.

-a appname.sbapp | appname.ssql | appname.sbdeploy

To create an application bundle, you must specify either -a or -f or both. Use -a to specify a top-level EventFlow or StreamSQL application file to be the primary application in the bundle; or specify the name of a StreamBase deployment file that in turn specifies a top-level module in an <application> element. The specified application is bundled to run in the default container.

-c

Includes in the bundle a precompiled application generated from the specified top-level application file. This option cannot be used to specify an existing .sbar file; it always generates a new precompiled application.

-i ignorelist

Specifies a comma-separated list of path names to ignore when generating a bundle. This is especially useful when working on a version-controlled working directory, to exclude the version control system's metadata files or directories from the bundle. For example, sbbundle -i .svn ....

-I file1@path1,file2@path2, --include file1@path1,file2@path2

Specifies a comma-separated list of files or folders to copy into the bundle. Files are copied to the bundle's /resources folder when no path is specified, or to the specified directory path resolved relative to the bundle root. Specifying a directory for the file argument is equivalent to specifying every file immediately contained within that directory. Use this feature to specify resource files needed by third-party libraries used in your application, including logging system configuration files, or to specify files used by adapters or operators that are not loaded normally in StreamBase. When used in conjunction with -p|-P, this option appends to and supplements the configuration determined by examining the specified Studio project directory.

-f sbd.sbconf

To create an application bundle, you must specify either -a or -f or both. Specifies the name of a StreamBase Server configuration file to include in the bundle to control the runtime behavior of the primary application in the bundle. If you specify both -a and -f, the configuration file controls the application named with the -a option. If you specify only -f, the configuration file must contain an <application> element that gives the path to a top-level EventFlow or StreamSQL application file. The preferred configuration is to specify a StreamBase deployment file with -a instead of -f without -a.

-J jvm-option

Specifies a system property setting or other JVM argument to be passed to the JVM running the bundle generation process. Use this option to specify temporary settings that affect only the current invocation of sbbundle. You must specify multiple -J options to specify multiple JVM arguments.

A space between the -J and its argument is optional. Use the full option syntax for jvm-option that you would use at the Java command line, including the initial hyphen. For example, specify -J-Dstreambase.log-level=2 to increase the log level for this invocation of sbbundle.

Your jvm-option argument might require surrounding quotes, depending on the characters it contains and the shell you are using. However, do not use quotes to escape the spaces between separate JVM arguments; instead use separate -J options. For example: -J-Xms512M -J-Xmx2G

-o

Overwrites any existing StreamBase bundle file of the same name.

-p projectdir1[:;]projectdir2[:;]..., -P projectdir1[:;]projectdir2[:;]...

Cannot be used in conjunction with -f. Use one of these options to emulate the automatic inclusion of Studio project metadata in the bundle, in the same way as the Studio bundler. Specifies a colon-separated list (UNIX) or semicolon-separated list (Windows) of relative paths to Studio project directories, whose Studio metadata is to be considered when generating the bundle. Studio project metadata includes the Java build path, module search path, resource search path, any project references, and other such information. With this option, the bundler generates a server configuration file for inclusion in the bundle based on the metadata of the specified projects. When used with uppercase -P, each specified project directory is recursively scanned for Studio project directories.

-V name=path ..., --classpath-variable name=path...

Define Java Classpath Variable for Studio-based project bundling. Arguments can be repeated to define additional variables. Remember to escape any spaces in your path when invoking this from the command shell.

-r sbconf.in

Specifies the name of a server configuration file to replace the configuration file currently in the bundle. Use this feature in conjunction with the –x option to extract the configuration file from a bundle, edit it to specify deployment-specific information, then replace the edited configuration file. Only replace the configuration file with one that was extracted with –x from the same bundle.

--v

Displays version information and exits.

-x sbconf.out

Extracts the configuration file from an existing bundle, and writes it to the path and name you specify as the argument to –x. Use this feature as described above for the –r option. Do not edit any path attributes in the extracted configuration file.