Output Filtering Sample

Contents

Importing This Sample into StreamBase Studio
Sample Location
This Sample's Files
Running the Output Filtering Sample

This sample demonstrates the use of output filtering to allow multiple StreamBase client applications to connect to an instance of StreamBase Server, where each client receives only the tuples that match a keyword associated with that client.

The client applications in this sample connect to an instance of StreamBase Server, then send their connection ID and a keyword. The filter expression in the output stream only allows tuples with the keyword associated with the connection ID to be sent to the clients.

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

By default, the sample files are installed in:

On Windows: C:\Program Files\StreamBase Systems\StreamBase.n.m\sample\outputfiltering
On UNIX: /opt/streambase/sample/outputfiltering

When you load the sample into StreamBase Studio, Studio copies the sample project's files to your Studio workspace. StreamBase Systems recommends that you use the workspace copy of the sample, especially on UNIX, where you may not have write access to /opt/streambase. In the default installation, the path to this sample in your Studio workspace is:

UNIX:       
  ~/streambase-studio-n.m-workspace/sample_outputfiltering
Windows XP:
  C:\Documents and Settings\username\My Documents\StreamBase Studio n.m Workspace\
      sample_outputfiltering
Windows Vista:
  C:\Users\username\Documents\StreamBase Studio n.m Workspace\
      sample_outputfiltering

This Sample's Files

The output filtering sample consists of:

Three StreamBase applications that illustrate three approaches that achieve the same results:

outputfilter.sbapp

This version of the application uses only StreamBase operators and functions. For a large number of clients, this approach is somewhat less efficient than the versions of the application that use custom Java functions.

outputfilter-calljava.sbapp

This version of the application uses custom Java functions to maintain the association between connection IDs and keywords.

outputfilter-jfun.sbapp

This version of the application also uses custom Java functions to maintain the association between connection IDs and keywords. In this case, the functions are named in the configuration file so they can be called directly, rather than with the calljava function.
A JAR file, ofilter.jar, that contains the classes called by the second and third versions of the application.
Java source files for the classes in the JAR file, plus an Ant script that builds the JAR file (and a Makefile that calls Ant). A prebuilt JAR file is provided for running the sample using the instructions below, so you do not need to use the source files. The source files are provided in case you want to extend or experiment with the Java classes.
A StreamBase configuration file, sbd.sbconf, that maps the custom Java functions and loads the JAR file.
A UNIX shell script, runclient.sh, or Windows command script, runclient.cmd, used in running the sample, as described below.

Running the Output Filtering Sample

You can and should open this sample's application files in StreamBase Studio to study how the applications are assembled. However, this sample is designed to be run in UNIX terminal windows or Windows command prompt windows. On Windows, be sure to use the StreamBase Command Prompt from the Start menu as described in the Test/Debug Guide, not a standard command prompt.

Open six terminal windows on UNIX, or six StreamBase Command Prompts on Windows. In each window, navigate to the directory where the sample is installed, or to your workspace copy of the sample, as described above.
In window 1, start StreamBase Server running the first version of the application:
```
sbd outputfilter.sbapp
```
Wait for the Listening message to appear.
In window 2, start an enqueue session on the stream named in.
```
sbc enq in
```
This command pauses and waits for input. Do not type any input yet.
In window 3, start dequeuing all tuples from the stream named in. This window will show every tuple we enqueue on this stream, which provides a baseline comparison.
```
sbc deq in
```
This command pauses and waits for enqueued input.
In window 4, run this sample's client with the argument blue. The argument is the keyword to be filtered on for this client session.
```
UNIX:     ./runclient.sh blue
Windows:  runclient blue
```
This command and the next also pause and wait for enqueued input.
In window 5, run the client with another keyword argument, red:
```
UNIX:     ./runclient.sh red
Windows:  runclient red
```
Position the windows so you can watch what happens in windows 3, 4, and 5 while you enter tuples in window 2. At the sbc enq prompt in window 2, enter several tuples in the form: integer comma color-name. For example, enter:
```
1,yellow
2,green
3,red
4,purple
5,blue
```
Notice that in window 3, the dequeue command echoes your input tuples exactly. But in window 4, the running client is only sent the tuple with the keyword blue:
```
Read tuple: 5,95085E54379A0B9857A0A8D0CAB8D5CE
```
Likewise, window 5 shows that this client only received the tuple with keyword red:
```
Read tuple: 3,E0BDF5CBEF7E947B0C2ABA021B4C44B0
```
In window 6, run the following command to shut down the server started in step 2:
```
sbadmin shutdown
```
In window 2, type Ctrl-C to close the enqueue. The dequeue and client sessions in windows 3, 4, and 5 automatically end when the server shuts down.
Back in window 1, run the following command to run the second form of the application:
```
sbd -f sbd.sbconf outputfilter-calljava.sbapp
```
Repeat steps 3 through 7. Windows 4 and 5 again show only the tuples allowed by their keyword arguments, this time echoing the input tuple. In window 4, you see:
```
Read tuple: 5,blue
```
In window 5:
```
Read tuple: 3,red
```
Issue another sbadmin shutdown command, and run the third form of the application in window 1:
```
sbd -f sbd.sbconf outputfilter-jfun.sbapp
```
Repeat steps 3 through 7 again and look for the same output.
Issue a final sbadmin shutdown to close the last server session.