Contents
When you start StreamBase Server from the command line with the sbd command, you normally specify the name of a StreamBase application source file to run on that server instance. The specified application source file can be in EventFlow or StreamSQL format, or can be a deployment file.
The sbd command also supports
precompiled application archive files as an argument. The recognized file extension
for precompiled archive files is .sbar.
You can specify a precompiled archive file name on the sbd command line, or when using sbadmin addContainer or modifyContainer to add an application to an
existing container on a running server. You can also specify an .sbar file name in an <application> element of a deployment file.
The advantage of using precompiled archives is faster startup times. When you start a StreamBase Server instance with an EventFlow or StreamSQL application source file, the server compiles the application on the fly to its runtime format, then runs the compiled application. It can take time to compile the application, especially for large or multi-module applications. By contrast, if you start a server with a precompiled application archive file, the server runs the application immediately.
The startup time for applications becomes significant in the context of StreamBase clustering and high availability scenarios. In a cluster pair of servers, primary and secondary, using precompiled archives allows a secondary server to start up and take over with minimal delay for a non-responding primary server.
Important
Precompiled application archives are version-specific. That is, a precompiled
application archive file can be started and run only with the exact version of the
sbd server as the command that
created the file. The version is specific down to the maintenance release number,
which is the third position in the release number. Thus, an .sbar file created with the sbargen command from StreamBase release 7.0.2 can
only be run with the sbd server from
release 7.0.2.
Create precompiled StreamBase application archive files with the sbargen command. In general, if you can successfully launch and run an application source file from the command line with the sbd command, optionally using a server configuration file, then sbargen can create a runnable archive file for that application.
There are cases where a project 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 (usually named sbd.sbconf) that
identifies the same Java resources in <jar> or
<dir> elements. When you can successfully run your
application with sbd -f sbd.sbconf , you are ready to use
sbargen to create a precompiled archive
of the same application.
appname
The following example compiles the orderBook EventFlow
application to precompiled format:
sbargen orderBook.sbapp orderBook.sbar
The next example includes the name of a customized configuration file to control the application:
sbargen -f ob.sbconf orderBook.sbapp orderBook.sbar
The following example specifies the name of a subdirectory that contains modules
called by the top-level application, feedsplitter-top.sbapp:
sbargen -m module_dir feedsplitter-top.sbapp feedsplitter.sbar
You can run the precompiled application archive like any other StreamBase application:
sbd orderBook.sbar sbadmin addContainer ob orderBook.sbar
See sbargen for further details on using the sbargen command.
A precompiled application archive file contains the compiled runtime code of a top-level EventFlow or StreamSQL application, plus any application modules called by the top-level application. Even if a large application consists of a top-level module that calls dozens of other modules, sbargen compiles the application complex into a single archive file that contains all the functionality of the top module and all its submodules.
An application archive contains a single StreamBase application that runs in a single
container. The sbargen command ignores
any configuration file <application> elements that
specify different applications to start in different containers.
EventFlow applications cannot call precompiled archive files as a module reference,
and StreamSQL applications cannot call archive files with the APPLY command. In
StreamBase Studio, even if an .sbar file appears in the
Package Explorer for your project, you cannot right-click and launch it from Studio.
For these reasons, there is no advantage to precompiling each module separately. The
precompiling process does all the work of resolving inter-module references,
containers, and container connections. Thus, for complex multi-module applications,
it only makes sense to run sbargen on
the top-level module.
The top-level application you precompile might require external resources as designated in the project's server configuration file. External resources might include custom Java operators or adapters in Java JAR or class format, native code libraries in DLL or .so files, or data files in plain text or CSV format. External resources such as these are NOT included in the archive file. The path to such resources is preserved in the configuration file, so all you need to do is specify the same configuration file when running the archive as when running the uncompiled application source. If you are running an archive file plus configuration file on a remote machine, any external resource files must be found at the same path locations specified in the configuration file — or use a machine-specific configuration file for the remote server with new locations for the same resources.
Similarly, the server configuration file might contain references to environment variables or operator parameters. The sbargen command attempts to resolve those references during the precompilation of the top-level application. The same environment or parameter settings are expected to be set up on the machine hosting the StreamBase Server instance where you will run the archive file.
Note
The application you are precompiling might be designed to access an external database through the JDBC operator. The database tables and queries are validated at application generation time. If the underlying database's structure changes between running sbargen and running the precompiled application, the application may fail in unanticipated ways. To put this risk in perspective, the same failures can occur with applications running without precompiling, if the underlying database structure changes while the application is running.
Caution
It is not possible to configure extension points for deployed precompiled StreamBase applications.
StreamBase Studio supports precompiling applications and running precompiled applications. Just as when running applications on the sbd command line, when Studio starts a precompiled application, the startup time is faster than when running the source code equivalent. For large, multi-module applications, the startup time can be significantly faster.
You can specify precompiling Studio applications in two ways:
-
At the project level
-
At the individual application file level
When you specify precompiling applications at the project level, Studio automatically precompiles the top-level EventFlow or StreamSQL applications in the specified project, and preserves each precompiled application file in an internal folder. When you ask Studio to run one of these applications, Studio runs the precompiled version. If you change the application before running it, Studio re-compiles the application to an application archive file before launching the application.
Precompiling at the project level is NOT suggested for a project that has a module called by another module. A module cannot invoke another module in precompiled form, so there is no advantage in precompiling the modules in a project folder with this configuration.
Precompiling at the project level is correct for a project containing several
independent application files. The operator sample
shipped with StreamBase is an example of a project of this type.
To specify precompiling applications at the project level, select a project folder in the Package Explorer, right-click, and select Properties. In the project Properties dialog, select → . Select the Speed up launches check box.
|
When you specify the precompiling of individual applications in a project, Studio keeps track of the state of the specified application and runs a compilation build every time the application changes. The precompiled application file is preserved in an internal folder, and it is this precompiled file that is run when you ask Studio to run the application.
Precompiling individual files is the best choice for projects with a top-level module that calls other applications as modules. In this case, specify precompiling on the top-level file. The precompiling process reconciles the inter-module references and compiles the top-level module and all its submodules into a single precompiled application file.
To specify precompiling individual applications, select an EventFlow or StreamSQL application file in the Package Explorer, right-click, and select Properties. In the application Properties dialog, select StreamBase. Use the drop-down list to select between Use Project Settings, Always, and Never.
|
You can specify precompiling at the project level, and then use the Never setting to override the project-level setting for individual files.
|