Application bundle files

A Streams application bundle file (SAB) is a single, relocatable file that contains artifacts needed to run your application. The file can be invoked directly to run the application on a single host or submitted to a Streams instance.

Application bundles contain all application logic, dependent toolkits, and configured files and subdirectories of the application and output directories. However, they do not include system or Teracloud® Streams libraries, so those must be present where the application is run.

For example, some shipped toolkits, like the Network or DPS toolkits, require additional system libraries to be installed on the system(s) running the application. Be sure to check for any system requirements for specialized toolkits.

Bundled directories and files

Applications or dependent toolkits might rely on reading files that are in the application directory hierarchy. For example, an operator might read the contents of file <appDir>/etc/init.cfg when the operator is initialized. It is therefore important that the init.cfg file is included in the SAB.

By default, the following subdirectories in application directories and dependent toolkits are included in the SAB:
<appOrToolkitDir>/
├── etc/
├── lib/
├── nl/
├── opt/
├── impl/
│   ├── bin/
│   ├── java/
│   │   ├── lib/
│   │   └── bin/
│   ├── lib/
│   └── nl/
└── opt/
Additionally, the following subdirectories of the output directory are included in the SAB:
<outputDir>/
├── bin/
└── etc/

Adding or excluding artifacts

If additional directories or files need to be included or excluded in the bundle, developers must specify a <sabFiles> element in the info.xml file. The <sabFiles> element has the following form:
<sabFiles>
   <include path="path-specification" root="root-option"/>
   <exclude path="path-specification"/>
</sabFiles>

The <include> element causes additional files to be included. While the <exclude> element causes files to be excluded. The mandatory path attribute specifies a relative path using Ant pattern syntax for the file or files to be included or excluded. The path is relative to the location specified by the root attribute.

The root attribute is an optional attribute and can be set to one of the following values:
  • toolkitDir for the toolkit directory. This option is the default.
  • applicationDir for the application directory.
  • outputDir for the output directory.
Important: For info.xml files in application directories there is no difference between a root value of toolkitDir and applicationDir. However, there is a distinction for info.xml files in toolkit directories. If toolkitDir is specified, the path is considered relative to the toolkit directory. If applicationDir is specified, the path is considered relative to the application directory. This allows toolkits used in an application to be able to include files from the application directory hierarchy.
For example, to add all files under a schema/ directory in the application directory to the SAB, specify the following in the info.xml:
<sabFiles>
   <include path="schema/*" root="applicationDir"/>
</sabFiles>

Behavior in distributed runtime environments

When an SAB is submitted to a distributed Streams instance, the SAB is deployed to all eligible hosts. The SAB is then unbundled into a runtime application directory hierarchy that is very similar to its compile-time hierarchy with the addition of dependent toolkit entities. This information is especially important for operators that need to access files that are part of the application directory or dependent toolkit directory hierarchy.

Streams instances are optimized to reuse runtime application directory hierarchies if multiple instances of the application are running and nothing in the bundles have changed.

spl-app-info command

Use the spl-app-info command to understand which files are included in a SAB. For example, the following command lists the toolkits and the files within those toolkits that are included in the bundle.

spl-app-info output/MyApp.sab --files

The spl-app-info command can also be used to display the bundle identifier, the build date, and also to unbundle the SAB. Use this command to verify that all the files needed for execution are included in the bundle.