TERR Sample

Introduction

The TIBCO Enterprise Runtime for R Output operator (hereafter, the TERR operator) 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.

The TERR operator requires an installation of TERR 4.0 or later on the same Windows or Linux machine on which StreamBase is installed. The TERR operator also offers provisional support for TERR 4.2 or later on Macintosh machines.

Note

StreamBase releases since 7.6.3 have bundled a Developer Edition of TERR in STREAMBASE_HOME/terr. You can use the bundled edition of TERR for experimentation and development, but not for deployment, , as described in License Considerations.

The TERR operator in this sample does not have a default for the location of your TERR installation. You must provide a valid TERR installation directory as part of your configuration of the TERR operator. TERR is not supported for remote execution on a separate machine; the TERR installation used must be local, on the same machine.

The TERR operator 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 operator.

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 operator's Properties view.
In the Package Explorer view, right-click the terrSample.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 operator's configuration on the Script Options tab to use the provided script.r file. Restart the application 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 TerrEngineParameters, JavaHOME, JavaOptions, and WhichTERRInstances. The TERR Instance to use element has 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.

TERR Configuration for Mac OS X

If your TERR sample fails to load on a Mac system with a "TERR library not found error", ensure you have the environment variable OR Java property configured in the sbd.sbconf as specified in Using the TERR Operator.

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.