Application bundle files

An application bundle file is a single, relocatable file that contains all the artifacts that are needed to run your application. You submit an application bundle file to run on an instance.

You can relocate an application by moving the application bundle file. Except for system libraries, the application bundle file includes all toolkit artifacts that are needed to run your application. Your application does not need to access external toolkits when it runs on execution hosts. The streamtool command accepts the application bundle file name.

Logically, an application bundle file includes parts of the application directory and the output directory, plus subdirectories from all toolkits that contributed to the application. When an application bundle file is submitted for execution, the application bundle file is deployed to all hosts on which the application can run. The application bundle file is then unbundled into a runtime application directory hierarchy that is very similar to its compile-time hierarchy with the addition of any external toolkit entities. This information is especially important if you have operators that need to access files that are part of the application directory or external toolkit directory hierarchy.

An application bundle file has an identifier that uniquely distinguishes one build of an application from another. When an application bundle file is submitted for execution, the identifier is used to check whether there is another instance of the same application already running, and if so, it shares the unbundled execution location. In this case, the same runtime application directory hierarchy is used for all executions of a given application bundle file.

Your application, or an external toolkit that your application uses, 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 application bundle file.

A specific set of toolkit subdirectories, including the application directory because an application is a toolkit, are included in the application bundle. By default, the following toolkit subdirectories are included in the application bundle file.

<rootTookitDir>/lib
     /etc
     /opt
     /nl
     /impl/bin
     /impl/java/lib
     /impl/java/bin
     /impl/lib
     /impl/nl 

In addition, the following select parts of the output directory are included in the application bundle file.

<outputDir>/bin
     /etc
     /java

If your operator expects any files it needs to be in one of the directories included by default, then there is nothing extra that needs to be done to ensure the inclusion of such files.

You might prefer that your operator gets files from somewhere other than one of the directories that is included by default. For example, suppose that your operator reads a schema file at initialization time, and you believe that it is more semantically correct to have the file in the <appDir>/schema directory. In this case, the operator developer must inform the compiler that additional subdirectories or files must be included in the application bundle file. This is done by specifying a <sabFiles> element hierarchy in the toolkit's info.xml file. Using the <sabFiles> element hierarchy, you can include files that otherwise are not included, or exclude files that are otherwise included. The <sabFiles> element hierarchy 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, to the file or files to be included or excluded. The path is relative to the location specified by the root attribute.

Continuing with the schema files example, you can specify the an <sabFiles> element hierarchy as part of your toolkit's info.xml file. The following <sabFiles> element hierarchy includes all files in the <appDir>/schema in the application bundle file.

<sabFiles>
   <include path="schema/*" root="applicationDir"/>
</sabFiles>

In this way, toolkits other than the application toolkit can include files from their toolkit directory hierarchy. If the applicationDir is specified, then regardless of which toolkit's info.xml contains the <include> element, the path always is considered relative to the application directory. In this way, arbitrary toolkits can force the inclusion of files from the application directory hierarchy.

To help application and toolkit developers understand which files are included in an application bundle file, you can use the spl-app-info command. For example, the following command lists the toolkits included in the bundle, 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, the execution mode (either stand-alone or distributed), and also to unbundle the application bundle file as it is at submission time. Use this command to verify that all the files needed for execution are included in the bundle.

There are APIs that can be called as execution time to get the application directory (getApplicationDirectory) and the output directory (getOutputDirectory). These APIs return the runtime location of these directories. Continuing the schema example, if you want to access the <appDir>/schema/mySchema.xml file, then you code the API call to get the application directory and add in the relative path to the specific file, resulting in a fully qualified path to the location of the mySchema.xml file. These APIs can be called from SPL, C++, and Java code.

There is an API to access files from the toolkit directory (getToolkitDirectory). This API returns the root directory of the toolkit that contains the operator code that calls the API. In other words, any arbitrary toolkit can get files from its own directory hierarchy using this API to the toolkit's runtime root directory. The paths that are returned by these APIs refer to the runtime location where the application bundle file is unbundled for execution. These paths can vary from host to host depending on where the application bundle is unbundled.