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>Import Samples and Community Content.

  • Enter client lib to narrow the list of options

  • Select How to use the C++, Java, and Python Client Libraries from the Client Libraries list.

  • Click Import Now.

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

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 Apply and Close.

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

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 Linux. In each window, navigate to your workspace copy of the sample, as described above.

  2. In window 1, run epadmin install node and start node commands for an EventFlow module that contains SimpleServer.sbapp.

  3. In window 2, type:

    ./SimpleDequeuer.py
    
  4. In window 3, type:

    ./SimpleEnqueuer.py
    
  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:

    epadmin --servicename=node.cluster stop nod
    eepadmin --servicename=node.cluster remove node
    

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.