TERR Sample

Introduction

The TIBCO Enterprise Runtime for R adapter (hereafter, the TERR adapter) was designed to make it easy to use TERR within a StreamBase application, and supports many options for dealing with TERR. This sample illustrates the minimum needed to use TERR. Its purpose is not to teach TERR; for that, see the extensive TERR documentation.

This sample requires an installation of TERR 2.7 or later on the same Windows or Linux machine that holds this StreamBase installation. (TERR is not currently available for OS X.) The TERR adapter that is central to this sample does not have a default set for the location of your TERR installation. You must provide a valid TERR installation directory as part of your configuration of the TERR adapter. TERR is not supported for remote execution on a separate machine; the TERR installation used must be local, on the same machine.

The TERR adapter launches TERR to run in a separate JVM from the one hosting StreamBase Server or any StreamBase client. By default, the TERR instance uses the same JDK installed as part of StreamBase, but you can configure TERR to run with any TERR-supported JVM installation.

Only 64-bit versions of TERR are supported by the TERR adapter. However, because TERR is run in its own JVM instance, you can successfully launch a TERR process from either the 64-bit or 32-bit versions of StreamBase Studio.

Running This Sample in StreamBase Studio

Follow these steps:

Make sure that the TERR Home property is set under the Engine tab of the TERR adapter's Property view.
In the Package Explorer view, right-click the Terr.sbapp file and invoke Run As → StreamBase Application.
In the Manual Input view of the SB Test/Debug perspective, enter values for an input tuple (click the button next to names, vals, and bools, respectively; not required for power). This input consists of:
- names — a list of strings
- vals — a list of integers
- bools — a list of booleans
- power — an integer
  
  Each input tuple results in an R dataFrame returned in the dataFrame field of the terrResult output tuple. The status stream shows a message reporting that the script executed successfully.

Notes

Change the TERR adapter's configuration on the Script Options tab to use the provided script.r file. Restart the app and then use a text editor to modify the script. When you save the script file, watch to confirm that the next input tuple uses the new script. Scripts loaded at runtime must provide the same input schema as the initially loaded script, or provide a superset of the initially loaded script.

You do not need to specify every input tuple field every time. However, your input tuple must exactly match at least one field name and data type in the input schema.

When in authoring mode, the script is checked against the input schema and a typecheck error occurs if the input does not have replacements for all the replacement variables in the script.

Certain options use ConfigurationChooserPropertyDescriptors. For these, default values can be placed in the sbd.sbconf file and easily shared among multiple instances. The sbd.sbconf file provided with this sample contains entries for TerrHome, TerrEngineParameters, JavaHOME, JavaOptions, and WhichTERRInstances. The TERR Instance to use and TERR Home elements have values, while the others just have the elements for you to fill in. The two filled-in sections of the example sbd.sbconf use different but valid ways for creating such sections.

Importing This Sample into StreamBase Studio

In StreamBase Studio, import this sample with the following steps:

From the top menu, click File → Load StreamBase Sample.
Select this application from the Applications list.
Click OK.

StreamBase Studio creates a project for each sample.

Sample Location

When you load the sample into StreamBase Studio, Studio copies the sample project's files to your Studio workspace, which is normally part of your home directory, with full access rights.

Important

Load this sample in StreamBase Studio, and thereafter use the Studio workspace copy of the sample to run and test it, even when running from the command prompt.

Using the workspace copy of the sample avoids the permission problems that can occur when trying to work with the initially installed location of the sample. The default workspace location for this sample is:

studio-workspace/sample_terr

See Default Installation Directories for the location of studio-workspace on your system.

In the default TIBCO StreamBase installation, this sample's files are initially installed in:

streambase-install-dir/sample/terr

See Default Installation Directories for the location of streambase-install-dir on your system. This location may require administrator privileges for write access, depending on your platform.