Client Sample

Contents

Importing This Sample into StreamBase Studio
Sample Location
This Sample's Files
Running the Java Client Sample Scenarios in Studio
Running the C++ or Python Client Samples in Terminal Windows

This sample features several demonstrations of StreamBase client programs. The sample consists of two StreamBase applications and several client programs written in different languages that enqueue to and dequeue from one of the two StreamBase applications. The sample illustrates the following client program scenarios:

Simple Enqueue and Dequeue

Runs the simple.sbapp StreamBase application, then runs the SimpleEnqueuer and SimpleDequeuer client programs. SimpleEnqueuer enqueues ten tuples, while SimpleDequeuer dequeues the processed tuples.

Dequeuer With Interceptor

Runs the simple.sbapp StreamBase application, then runs the SimpleEnqueuer and InterceptingDequeuer client programs. This scenario illustrates the use of an interceptor Java module in the dequeuer client program. In this case, the interceptor passes only even-numbered tuples.

Reconnecting Clients

Runs the simple.sbapp StreamBase application, then runs the ReconnectingDequeuer and ReconnectingEnqueuer client programs. In this case, the StreamBase Server instance running simple.sbapp is stopped and restarted while the enqueuer and dequeuer programs are running, demonstrating that the enqueuer and dequeuer client programs can pause, then reconnect to the restarted server.

A tuple can be dropped if StreamBase Server puts it on an output stream for which there are no subscribers. The dequeue program may miss one or more tuples that have been dropped in this fashion.

Filtered Subscribe Client

This sample demonstrates how to narrow the result set using predicates in the dequeuing client program. It runs the FilteredSubscribe.sbapp StreamBase application, and feeds input data to it using a feed simulation. You then run the FilteredSubscribe client program to dequeue filtered results.

Source code is provided in Java for all four scenarios, in C++ and Python for the Simple Enqueue and Dequeue scenario, and in C++ for the Filtered Subscribe scenario.

Note

The Java code in this sample is delivered only in source code form. To build the code, you must load the sample into StreamBase Studio, which automatically builds the Java code.

Importing This Sample into StreamBase Studio

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

From the top menu, select File → Load StreamBase Sample.
Select client from the Client Libraries category.
Click OK.

StreamBase Studio creates a project for the 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

StreamBase Systems strongly recommends that you load this sample in Studio, and use the 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 are inevitable when trying to work with the installed location in C:\Program Files or /opt/streambase. The default workspace location for this sample is:

studio-workspace/sample_client

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

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

streambase-install-dir/sample/client

See Default Installation Directories for the location of streambase-install-dir on your system. This location usually requires administrator privileges for write access.

This Sample's Files

The Client sample consists of the files shown in the following table.

File	Description
`simple.sbapp`	A simple StreamBase application with a Map operator that negates its incoming int and double fields, and adds "processed" to its incoming string fields. The input schema includes a field of type tuple with a nested tuple field.
`FilteredSubscribe.sbapp`	A simple StreamBase application with a pass-through Map operator.
`*.java`	Java source code for the client enqueue and dequeue programs, placed in `java-src/com.streambase.sample.clients` and automatically compiled by Studio.
`*.launch`	Studio launchers for the six Java client programs. The presence of the `.launch` files is what places the launchers in the Run History list.
`SimpleEnqueuer.cpp`, `SimpleDequeuer.cpp`, `FilteredSubscribe.cpp`	C++ source code for the client programs.
`SimpleEnqueuer`, `SimpleDequeuer`, `FilteredSubscribe`	UNIX only. Executable client programs built from the C++ source code.
`Makefile`	UNIX only. A makefile to build and run the client programs from C++ source code on UNIX.
`*.exe`	Windows only. Executable client programs built from the C++ source code. Programs with `.exe` extension were build with Visual C++ 7.1; programs with `-vc8.exe` extension were built with Visual C++ 8.0, while files with extension `x64-vc8.exe` were built with 64-bit client libraries in Visual C++ 8.0 These files are installed in `sample\client`, and are not copied to the Studio workspace when you load the sample in Studio.
`.sln`, `.vcproj`	Windows only. Solution and project files for Visual Studio .NET 2005 (Visual C++ 8.0). Use these files with Visual Studio to rebuild the C++ client programs. These files are installed in `sample\client`, and are not copied to the Studio workspace when you load the sample in Studio. Note In the Visual Studio project files, the paths to the StreamBase Include files and libraries are configured for the standard default StreamBase installation directory. You may need to adjust these paths for your installation.
`SimpleEnqueuer.py`, `SimpleDequeuer.py`	Python versions of the simple enqueuer and dequeuer programs. See Running the Python Samples.
`FilteredSubscribeTest.sbfs`	Feed simulation file for the `FilteredSubscribe.sbapp` StreamBase application.
`FilteredSubscribeTest.csv`	CSV data file used by the above feed simulation file.

Running the Java Client Sample Scenarios in Studio

The Java sample clients are intended to be run in StreamBase Studio, while the C++ and Python sample clients are intended to be run in UNIX terminal windows or Windows Command Prompt windows, as described in Running the C++ or Python Client Samples in Terminal Windows.

The sample has no provision for running the Java sample clients at the command line, but experienced Java developers can do so by adding the java-bin directory to the classpath.

This section has the following subsections:

Introduction and Setup

When you load this sample in Studio, the sample places launchers for the Java client sample programs in Studio's Run History list. For each sample application, the overall procedure is:

Run a provided StreamBase application in Studio. The StreamBase application accepts input from the Manual Input or Feed Simulations view, and shows output in the Application Output view, as normal.
Use one of the launchers in the Run History list to run one or more Java client programs at the same time the StreamBase application is running. Java client programs show their output in one or more Console views.

Run a Java client launcher from the Run History list using one of the following methods:

From the Studio top-level menu, invoke Run → Run History, and select the specified launcher from the list.
Open the Run Configurations dialog, select the specified launcher from the Java application category, then click Run.
Click the down-arrow next to the Run button in the Studio toolbar, and select the specified launcher from the list.

The Java client launchers placed in the Run History list presume that Studio is running the StreamBase application on port 10000, which is the installed default port for StreamBase application launches. Before you proceed, use these steps to confirm that port 10000 is the default launch port:

Open Windows → Preferences.
In the left side navigation column, open StreamBase Studio → Test/Debug.
Confirm that the Default Port setting is 10000. If not, change it to 10000.
Click OK.

When you run a Java program's launcher, it prints output lines to the Console view. There is one Console view for each running program; switch between Console views with the drop-down arrow of the Display Selected Console button.

Use the Remove All Terminated Launches button to close unneeded Console views.

Run the Simple Enqueue and Dequeue Scenario in Studio

Follow these steps to run this scenario in StreamBase Studio:

In the Package Explorer, double-click to open the simple.sbapp application. Make sure the application is the currently active tab in the EventFlow Editor.
Click the Run button. This opens the SB Test/Debug perspective and starts the application.
Open the Run History list as described in Introduction and Setup, and select the SimpleDequeuer launcher. This runs the Java program of that name, which connects to the StreamBase Server instance running simple.sbapp. The Console view reports:
```
SimpleDequeuer: Ready
```

Open the Run History list again and select the SimpleEnqueuer launcher. This Java program connects to simple.sbapp, emits ten tuples, then exits. The dequeuer's Console view reports:

SimpleDequeuer: Ready
SimpleDequeuer: dequeue: -1,Tuple #1 processed!,-0.1,"0,processed: Tuple #1"
SimpleDequeuer: dequeue: -2,Tuple #2 processed!,-0.2,"4,processed: Tuple #2"
SimpleDequeuer: dequeue: -3,Tuple #3 processed!,-0.3,"13,processed: Tuple #3"
SimpleDequeuer: dequeue: -4,Tuple #4 processed!,-0.4,"32,processed: Tuple #4"
SimpleDequeuer: dequeue: -5,Tuple #5 processed!,-0.5,"62,processed: Tuple #5"
SimpleDequeuer: dequeue: -6,Tuple #6 processed!,-0.6,"107,processed: Tuple #6"
SimpleDequeuer: dequeue: -7,Tuple #7 processed!,-0.7,"171,processed: Tuple #7"
SimpleDequeuer: dequeue: -8,Tuple #8 processed!,-0.8,"256,processed: Tuple #8"
SimpleDequeuer: dequeue: -9,Tuple #9 processed!,-0.9,"364,processed: Tuple #9"
SimpleDequeuer: dequeue: -10,Tuple #10 processed!,-1.0,"500,processed: Tuple #10"

Use the Debug view in the upper right to manage the running programs. Select a terminated program, right-click and relaunch it from the context menu. Use the context menu and the buttons of the Debug view to restart or close the Java programs at will.
When done, press F9 or click the Stop Running Application button. This closes the StreamBase application and all Java client programs.

Run the Dequeuer With Interceptor Scenario in Studio

Follow these steps to run this scenario in StreamBase Studio:

In the Package Explorer, double-click to open the simple.sbapp application. Make sure the application is the currently active tab in the EventFlow Editor.
Click the Run button. This opens the SB Test/Debug perspective and starts the application.
Open the Run History list as described in Introduction and Setup, and select the InterceptingDequeuer launcher. This runs the Java program of that name, which connects to the StreamBase Server instance running simple.sbapp. The Console view reports:
```
InterceptingDequeuer: Ready
```

Open the Run History list again and select the SimpleEnqueuer launcher. This Java program connects to simple.sbapp, emits ten tuples, then exits. The dequeuer's Console view reports:

InterceptingDequeuer: Ready
InterceptingDequeuer: dequeue [sb://localhost/]: -2,Tuple #2 processed!,-0.2,"4,processed: Tuple #2"
InterceptingDequeuer: dequeue [sb://localhost/]: -4,Tuple #4 processed!,-0.4,"32,processed: Tuple #4"
InterceptingDequeuer: dequeue [sb://localhost/]: -6,Tuple #6 processed!,-0.6,"107,processed: Tuple #6"
InterceptingDequeuer: dequeue [sb://localhost/]: -8,Tuple #8 processed!,-0.8,"256,processed: Tuple #8"
InterceptingDequeuer: dequeue [sb://localhost/]: -10,Tuple #10 processed!,-1.0,"500,processed: Tuple #10"

Notice that the Intercepting Dequeuer program only processes tuples with an even number in the incoming int field.

As with the first scenario, use the Debug view in the upper right to manage the running programs.
When done, press F9 or click the Stop Running Application button. This closes the StreamBase application and all Java client programs.

Run the Reconnecting Clients Scenario in Studio

Follow these steps to run this scenario in StreamBase Studio:

In the Package Explorer, double-click to open the simple.sbapp application. Make sure the application is the currently active tab in the EventFlow Editor.
Click the Run button. This opens the SB Test/Debug perspective and starts the application.
Open the Run History list as described in Introduction and Setup, and select the ReconnectingDequeuer launcher. This runs the Java program of that name, which connects to the StreamBase Server instance running simple.sbapp. The Console view reports:
```
ReconnectingDequeuer: Connected to StreamBase at [sb://localhost/]
```
Open the Run History list again and select the ReconnectingEnqueuer launcher. This Java program connects to simple.sbapp, emits one tuple every five seconds, exiting after the tenth tuple. The dequeuer's Console view reports:
```
ReconnectingEnqueuer: Connected to StreamBase at [sb://localhost/]
ReconnectingEnqueuer: enqueue: Tuple #1,1,0.1,"0.05,""10,#1"""
ReconnectingEnqueuer: enqueue: Tuple #2,2,0.2,"0.1,""20,#2"""
...
```
While the enqueuer is running, press F9 or click the Stop Running Application button. The following events occur:
- The simple.sbapp application stops and Studio returns to the SB Authoring perspective.
- The Reconnecting Dequeuer immediately detects that the connection is down and enter its reconnection loop.
- The Reconnecting Enqueuer sends one more tuple without an error, but then receives a network exception when sending the following tuple. It then enters its reconnection loop.
Click the Run button to restart simple.sbapp. Both client programs detect the restarted server and continue processing tuples.
When done, press F9 or click the Stop Running Application button. This closes the StreamBase application and all Java client programs.

Run the Filtered Subscribe Scenario in Studio

Follow these steps to run this scenario in StreamBase Studio:

In the Package Explorer, double-click to open the FilteredSubscribe.sbapp application. Make sure the application is the currently active tab in the EventFlow Editor.
Click the Run button. This opens the SB Test/Debug perspective and starts the application.
Open the Run History list as described in Introduction and Setup, and select the FilteredSubscribe launcher. This runs the Java program of that name, which connects to FilteredSubscribe.sbapp. The Console view reports:
```
FilteredSubscribe: Ready
```
Bring the Application Output view to the foreground so that you can see tuples exiting from the FilteredSubscribe.sbapp application.
Select the Feed Simulations tab, select the FilteredSubscribeTest.sbfs feed simulation line, and click Run. The feed simulation runs to completion, showing five tuples output on the application's OutputStream1.

Compare the dequeuer's Console window, which shows seven lines of output. The FilteredSubscribe program creates two new output streams, IBM_gt_85 and MSFT_big_Trade, in addition to OutputStream1.

FilteredSubscribe: Ready
FilteredSubscribe: dequeue: GE,35.0,200 from stream: OutputStream1
FilteredSubscribe: dequeue: IBM,84.5,300 from stream: OutputStream1
FilteredSubscribe: dequeue: IBM,88.0,200 from stream: IBM_gt_85
FilteredSubscribe: dequeue: IBM,88.0,200 from stream: OutputStream1
FilteredSubscribe: dequeue: MSFT,25.0,300 from stream: OutputStream1
FilteredSubscribe: dequeue: MSFT,24.75,1003 from stream: MSFT_big_Trade
FilteredSubscribe: dequeue: MSFT,24.75,1003 from stream: OutputStream1

When done, press F9 or click the Stop Running Application button. This closes the StreamBase application and all Java client programs.

Running the C++ or Python Client Samples in Terminal Windows

If you have access to StreamBase Studio, run all four Java scenarios in Studio before running the C++ or Python versions at the command prompt, to get a feel for what to expect.

You can mix and match different library implementations of SimpleEnqueuer and SimpleDequeuer. For example, you can dequeue with a C++ client and enqueue with a Python client.

On Windows, you must use the StreamBase Command Prompt from the Start menu as described in the Test/Debug Guide, not the default command prompt.

This section has the following subsections:

Running the C++ Samples

Follow these steps to run the C++ Simple Enqueue and Dequeue scenario in terminal windows:

Open three terminal windows on UNIX, or three StreamBase Command Prompts on Windows. In each window, navigate to your workspace copy of the sample, as described above.
In window 1, type:
```
sbd simple.sbapp
```
In window 2 on UNIX, type:
```
./SimpleDequeuer
```
For Windows, type:
```
SimpleDequeuer
```
Window 2 now shows:
```
SimpleDequeuer: Ready
```
In window 3 on UNIX, type:
```
./SimpleEnqueuer
```
For Windows, type:
```
SimpleEnqueuer
```

In window 2, look for output lines from the dequeuer:

SimpleDequeuer: Ready
SimpleDequeuer: dequeue: -1,Tuple #1 processed!,-0.1,"0,processed: Tuple #1"
SimpleDequeuer: dequeue: -2,Tuple #2 processed!,-0.2,"4,processed: Tuple #2"
SimpleDequeuer: dequeue: -3,Tuple #3 processed!,-0.3,"13,processed: Tuple #3"
SimpleDequeuer: dequeue: -4,Tuple #4 processed!,-0.4,"32,processed: Tuple #4"
SimpleDequeuer: dequeue: -5,Tuple #5 processed!,-0.5,"62,processed: Tuple #5"
SimpleDequeuer: dequeue: -6,Tuple #6 processed!,-0.6,"107,processed: Tuple #6"
SimpleDequeuer: dequeue: -7,Tuple #7 processed!,-0.7,"171,processed: Tuple #7"
SimpleDequeuer: dequeue: -8,Tuple #8 processed!,-0.8,"256,processed: Tuple #8"
SimpleDequeuer: dequeue: -9,Tuple #9 processed!,-0.9,"364,processed: Tuple #9"
SimpleDequeuer: dequeue: -10,Tuple #10 processed!,-1.0,"500,processed: Tuple #10"

In window 3, type the following command to terminate the server and dequeuer:
```
sbadmin shutdown
```

Follow these steps to run the C++ Filtered Subscribe scenario in terminal windows:

Open three terminal windows on UNIX, or three StreamBase Command Prompts on Windows. In each window, navigate to your workspace copy of the sample, as described above.
In window 1, type:
```
sbd simple.sbapp
```

In window 2 on UNIX, type:

./FilteredSubscribe

For Windows, type:

FilteredSubscribe

Window 2 now shows:

FilteredSubscribe: Ready

In window 3, type:
```
sbfeedsim FilteredSubscribeTest.sbfs
```

Compare the output lines in windows 2 and 3. Notice that there are five lines from the feed simulation in window 3, but the FilteredSubscribe client program has added two extra output ports:

FilteredSubscribe: Ready
FilteredSubscribe: dequeue: GE,35.0,200 from stream: OutputStream1
FilteredSubscribe: dequeue: IBM,84.5,300 from stream: OutputStream1
FilteredSubscribe: dequeue: IBM,88.0,200 from stream: IBM_gt_85
FilteredSubscribe: dequeue: IBM,88.0,200 from stream: OutputStream1
FilteredSubscribe: dequeue: MSFT,25.0,300 from stream: OutputStream1
FilteredSubscribe: dequeue: MSFT,24.75,1003 from stream: MSFT_big_Trade
FilteredSubscribe: dequeue: MSFT,24.75,1003 from stream: OutputStream1

In window 3, type the following command to terminate the server and dequeuer:
```
sbadmin shutdown
```

Running the Python Samples

Before running the Python sample clients, make sure your Python environment is configured as described in Creating Python Clients.

Follow these steps to run the C++ Simple Enqueue and Dequeue scenario in terminal windows:

Open three terminal windows on UNIX, or three StreamBase Command Prompts on Windows. In each window, navigate to your workspace copy of the sample, as described above.
In window 1, type:
```
sbd simple.sbapp
```

In window 2 on UNIX, type:

./SimpleDequeuer.py

For Windows, type:

python SimpleDequeuer

In window 3 on UNIX, type:

./SimpleEnqueuer.py

For Windows, type:

python SimpleEnqueuer

In window 2, look for output lines from the dequeuer.
In window 3, type the following command to terminate the server and dequeuer:
```
sbadmin shutdown
```