Multiple version toolkit support with SPL operators

Composite operators might need some modification to make them work with multiple versions of the IBM® Streams product.

There are a number of SPL language APIs that are typically called from the logic clause of operator invocations. For example, many of the functions defined in the spl.file namespace take a file name. Prior to IBM Streams Version 4.0 a relative file name was assumed to be relative to the data directory. As of IBM Streams Version 4.0, all file names should be absolute. Given a relative file name, you can use the dataDirectory API to access the current location of the data directory and use that to compose an absolute path to the file.

In some cases it can be necessary for an operator in a toolkit to load the contents of a file from somewhere within the toolkit directory hierarchy. In order to make this function correctly with IBM Streams Version 4.0 or later, and previous streams versions, some care must be taken with where the file to be loaded is placed within the toolkit, and how the path to that file is built.

The first decision to be made is if the file should reside in the application bundle or be accessed from the data directory. If a unique version of the file should be used with each instance of the application, then it should be accessed via the data directory using the mechanism we've already discussed. For the following example we will assume that the file is common across all instances of a given application, and so should be included in the application bundle.

Given that we want to have the file included in the bundle, it should be placed somewhere in the toolkit's directory hierarchy that is included in the application bundle by default. For example, in the toolkit's etc sub-directory. For the purpose of this example we will assume we have now got a file called config.txt in the etc sub-directory.

The next thing we must do is build a fully qualified path to the file we wish to load. Let's assume for a moment that the SPL code where our operator lives is the operators sub-directory. In IBM Streams versions prior to Version 4.0 you might have used code like the following:

rstring fileName = getThisFileDir() + "/../etc/config.txt"

fileName in this case would contain something like <toolkitDir>/operators/../etc/config.txt. This will not work in IBM Streams Version 4.0 or later because the operators sub-directory is not part of the application bundle. To compute a path that will work with IBM Streams Version 4.0 or later, and earlier versions you need to construct a path that is based off the toolkit's root directory. The following code snippet demonstrates how it can be done for this example:

rstring fileNameBase = getThisFileDir();
rstring fileName = substring(fileNameBase, 0, length(fileNameBase)-length("operators")) + "etc/config.txt";

In this example we have taken the path returned by getThisFileDir and removed the operators part, giving us the root toolkit directory path. Then we simply append the relative path to the file in our toolkit.

If you only plan on supporting IBM Streams Version 4.0 and later, then consider using the getToolkitDirectory API, which returns the root path to the toolkit directory regardless of where it the toolkit the calling source is located.