- Index

< Previous |  | Next >

# Client Sample

## Introduction

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

| Run this ... | Source code provided in:
--- | --- | ---
Scenario | Server | Dequeuer | Enqueuer | Java | C++ | Python
Simple Enqueue and Dequeue | `SimpleServer.sbapp` | SimpleDequeuer | SimpleEnqueuer | yes | yes | yes
Dequeuer with Interceptor | `SimpleServer.sbapp` | InterceptingDequeuer | SimpleEnqueuer | yes | — | —
Reconnecting Clients | `SimpleServer.sbapp` | ReconnectingDequeuer | ReconnectingEnqueuer | yes | — | —
Filtered Subscribe Client | `FilteredSubcribeServer.sbapp` | FilteredSubscribe | Feed simulation, `FilteredSubscribeTest.sbfs` | yes | yes | —

Simple Enqueue and Dequeue

  In this scenario, `SimpleEnqueuer` enqueues ten tuples, while `SimpleDequeuer` dequeues the processed tuples. You can keep the `SimpleServer.sbapp` server running while you enqueue and dequeue from clients written in all three languages. For example, you can enqueue from the Java enqueuer, then dequeue from the C++ or Python dequeuer.

Dequeuer With Interceptor

  This scenario illustrates the use of an interceptor Java module in the dequeuer client program. In this case, the interceptor passes only the even-numbered tuples.

Reconnecting Clients

  For this scenario, the StreamBase Server instance running `SimpleServer.sbapp` is stopped and restarted while the enqueuer and dequeuer programs are running. This demonstrates that the enqueuer and dequeuer client programs can pause, then automatically reconnect to the restarted server.

  A tuple can be dropped if StreamBase Server emits to 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. Run the `FilteredSubscribeServer.sbapp` StreamBase server application, and feed input data to it using a feed simulation. You then run the `FilteredSubscribeServer` client program to dequeue filtered results.

## Importing This Sample into StreamBase Studio

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

- From the top-level menu, click File → Load StreamBase Sample.

- Enter `cli` to narrow the list of options

- Select client from the Client Libraries list.

- Click OK.

StreamBase Studio creates a project for each sample.

## Building the Source Files

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.

To build the C++ client programs on UNIX, invoke targets in the provided Makefile with a Gnu-compatible make command. This requires GCC and G++ 4.5.

## 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

- Run the Simple Enqueue and Dequeue Scenario in Studio

- Run the Dequeuer With Interceptor Scenario in Studio

- Run the Reconnecting Clients Scenario in Studio

- Run the Filtered Subscribe Scenario in Studio

### 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 Output Streams 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:

1. Open Windows → Preferences.

2. In the left side navigation column, open StreamBase Studio → Test/Debug.

3. Confirm that the Default Port setting is 10000. If not, change it to 10000.

4. 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:

1. In the Project Explorer view, open the sample you just loaded.

   If you see red marks on a project folder, wait a moment for the project to load its features.

   If the red marks do not resolve themselves after a minute, select the project, right-click, and select Maven → Update Project from the context menu.

2. Open the `src/main/eventflow/`packageName`` folder.

3. Open the `SimpleServer.sbapp` file and click the Run button. This opens the SB Test/Debug perspective and starts the module.

4. 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 `SimpleServer.sbapp`. The Console view reports:

       SimpleDequeuer: Ready

5. Open the Run History list again and select the `SimpleEnqueuer` launcher. This Java program connects to `SimpleServer.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"

6. 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.

7. When done, press F9 or click the Terminate EventFlow Fragment button. This closes the StreamBase application and all Java client programTableOperators.

### Run the Dequeuer With Interceptor Scenario in Studio

Follow these steps to run this scenario in StreamBase Studio:

1. In the Project Explorer view, open the sample you just loaded.

   If you see red marks on a project folder, wait a moment for the project to load its features.

   If the red marks do not resolve themselves after a minute, select the project, right-click, and select Maven → Update Project from the context menu.

2. Open the `src/main/eventflow/`packageName`` folder.

3. Open the `SimpleServer.sbapp` file and click the Run button. This opens the SB Test/Debug perspective and starts the module.

4. 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 `SimpleServer.sbapp`. The Console view reports:

       InterceptingDequeuer: Ready

5. Open the Run History list again and select the `SimpleEnqueuer` launcher. This Java program connects to `SimpleServer.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.

6. As with the first scenario, use the Debug view in the upper right to manage the running programs.

7. When done, press F9 or click the Terminate EventFlow Fragment 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:

1. In the Project Explorer view, open the sample you just loaded.

   If you see red marks on a project folder, wait a moment for the project to load its features.

   If the red marks do not resolve themselves after a minute, select the project, right-click, and select Maven → Update Project from the context menu.

2. Open the `src/main/eventflow/`packageName`` folder.

3. Open the `SimpleServer.sbapp` file and click the Run button. This opens the SB Test/Debug perspective and starts the module.

4. 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 `SimpleServer.sbapp`. The Console view reports:

       ReconnectingDequeuer: Connected to StreamBase at [sb://localhost/]

5. Open the Run History list again and select the `ReconnectingEnqueuer` launcher. This Java program connects to `SimpleServer.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"""
       ...

6. While the enqueuer is running, press F9 or click the Terminate EventFlow Fragment button. The following events occur:

   - The `SimpleServer.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.

7. Click the Run button to restart `SimpleServer.sbapp`. Both client programs detect the restarted server and continue processing tuples.

8. When done, press F9 or click the Terminate EventFlow Fragment 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:

1. In the Project Explorer view, open the sample you just loaded.

   If you see red marks on a project folder, wait a moment for the project to load its features.

   If the red marks do not resolve themselves after a minute, select the project, right-click, and select Maven → Update Project from the context menu.

2. Open the `src/main/eventflow/`packageName`` folder.

3. Open the `FilteredSubscribeServer.sbapp` file and click the Run button. This opens the SB Test/Debug perspective and starts the module.

4. 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

5. Bring the Output Streams view to the foreground so that you can see tuples exiting from the `FilteredSubscribe.sbapp` application.

6. 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`.

7. 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

8. When done, press F9 or click the Terminate EventFlow Fragment 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

- Running the Python Samples

### Running the C++ Samples

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

1. 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.

2. Build the C++ samples as follows:

   - On UNIX, including macOS, in window 1, type:

         make all

   - On Windows, load the

3. In window 1, type:

       sbd SimpleServer.sbapp

4. In window 2 on UNIX, type:

       ./SimpleDequeuer

   For Windows, type:

       SimpleDequeuer

   Window 2 now shows:

       SimpleDequeuer: Ready

5. In window 3 on UNIX, type:

       ./SimpleEnqueuer

   For Windows, type:

       SimpleEnqueuer

6. 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"

7. 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:

1. 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.

2. In window 1, type:

       sbd FilteredSubscribe.sbapp

3. In window 2 on UNIX, type:

       ./FilteredSubscribe

   For Windows, type:

       FilteredSubscribe

   Window 2 now shows:

       FilteredSubscribe: Ready

4. In window 3, type:

       sbfeedsim FilteredSubscribeTest.sbfs

5. 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

6. 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:

1. 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.

2. In window 1, type:

       sbd SimpleServer.sbapp

3. In window 2 on UNIX, type:

       ./SimpleDequeuer.py

   For Windows, type:

       python SimpleDequeuer

4. In window 3 on UNIX, type:

       ./SimpleEnqueuer.py

   For Windows, type:

       python SimpleEnqueuer

5. In window 2, look for output lines from the dequeuer.

6. In window 3, type the following command to terminate the server and dequeuer:

       sbadmin shutdown

## This Sample's Files

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

File | Description
--- | ---
`SimpleServer.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.
`FilteredSubscribeServer.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, as described below.
`SimpleEnqueuer.cpp`, `SimpleDequeuer.cpp`, `FilteredSubscribe.cpp` | C++ source code for the client programs.
`SimpleEnqueuer`, `SimpleDequeuer`, `FilteredSubscribe` | UNIX and macOS only. Executable client programs built from the C++ source code.
`Makefile` | UNIX and macOS only. A makefile to build and run the client programs from C++ source code on UNIX or macOS, using GCC 4.2.
`*.exe` | Windows only. Executable client programs built from the C++ source code are provided in the `%STREAMBASE_HOME%\sample\client` directory and are copied to your Studio workspace when you load the sample in Studio. Programs with the `.exe` extension were built 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. Programs with the `v100.exe` extension were built with Visual C++ 10.0, as were the 64-bit programs with extension `x64-v100.exe`.
`*.sln` | Windows only. Solution files for three versions of Visual Studio: `client.sln` — for Visual Studio 2003 (Visual C++ 7.1) `client-vc8.sln` — for Visual Studio 2005 (Visual C++ 8.0) `client-vc10.sln` — for Visual Studio 2010 (Visual C++ 10.0) Use these files with Visual Studio to rebuild the C++ or .NET client programs. You can open the `vc8.sln` file with Visual C++ 9.0.
`*.vcproj`, `*.vcxproj` | Windows only. Project files for three versions of Visual Studio: `*.vcproj` — for Visual Studio 2003 (Visual C++ 7.1) `*-vc8.vcproj` — for Visual Studio 2005 (Visual C++ 8.0) or Visual C++ 9.0. `*.vcxproj` — for Visual Studio 2010 (Visual C++ 10.0) ### 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.

## 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 permission problems. The default workspace location for this sample is:

    studio-workspace/sample_client

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