Creating StreamBase .NET Clients

Contents

Writing .NET Enqueue Clients
Buffering for .NET Enqueue Clients
Writing .NET Dequeue Clients
Deploying .NET Clients
Related Topics

This topic describes how to create enqueue and dequeue .NET client applications for StreamBase applications. The .NET library is available only in the Windows version of the StreamBase installation. You can use Visual Studio 2012 or Visual Studio 2013 to develop .NET client and server monitor applications with the StreamBase .NET Client Library.

Writing .NET Enqueue Clients

This section describes how to use the StreamBase .NET library to write a client application that enqueues data to a StreamBase Server. Although the example below is written in C#, you can write a StreamBase .NET client in any .NET-compatible language, including Visual Basic .NET, managed C++, and J#.

The StreamBase .NET library reference is added to the Windows Start menu when you install StreamBase on Windows. To open it, select StreamBase n.m .NET API from the StreamBase API Documentation menu.

Sample source code: streambase-install-dir\sample\dotnet\SimpleEnqueuer\SimpleEnqueuer.cs

The basic procedure for enqueuing data into a StreamBase node in C# is:

Use Microsoft Visual Studio 2012 or later to create a new Visual C# project.
Add a reference to StreamBase.SB.Client.dll, which is installed by default in C:\TIBCO\sb-cep\n.m\bin
Add the following lines to top of the C# source file to access the StreamBase classes:
```
using StreamBase.SB;
using StreamBase.SB.Client;
```
Create an instance of the StreamBaseClient class. If needed, specify the String URI of the desired StreamBase node as an argument. For example:
```
StreamBaseClient client = new StreamBaseClient("sb://localhost:10000/");
```
Retrieve a Schema object for each stream you want to enqueue. For example:
```
Schema schema = client.GetSchemaForStream("InputStream");
```
where InputStream is the name of an input stream in your StreamBase application.
Create a Tuple instance of the schema for the stream specified above. For example:
```
Tuple tuple = schema.CreateTuple();
```

For every tuple of data to enqueue:

Set values for each of the tuple's fields. For example:

tuple.SetInt("myint",5);
tuple.SetString("mystring","hello");
// ...
// where "myint" and "mystring" are field names 
// in the input stream of your StreamBase application

Enqueue the tuple onto the stream. For example:
```
client.Enqueue("InputStream", tuple);
```

Compiling and Running a StreamBase .NET Client (Windows Only)

The enqueuing client can be compiled and run from Visual Studio. It can also be run outside of Visual Studio by typing the following at the StreamBase Command Prompt:

sample\SimpleEnqueuer\bin\Release\SimpleEnqueuer.exe

Buffering for .NET Enqueue Clients

For enqueue clients that use the StreamBase .NET Client library, you can enable tuple buffering and set the following parameters:

The buffer size (number of tuples per buffer)
The buffer's flush interval

You can also explicitly flush the buffer of a specified stream, or flush all buffers.

By enabling tuple buffering and experimenting with these parameters, you may be able to improve the efficiency and performance of your enqueue code. A single enqueue of a buffer containing, for example, 100 tuples should be more efficient than making 100 separate enqueue operations.

The examples in this section demonstrate how to use this feature. Here the buffer size is set to 100 tuples and the buffer flush interval is set to 1000 milliseconds (one second).

Notes: In the StreamBase Client library, buffering is only enabled if the value for the buf_size parameter is greater than zero. (The buf_size parameter specifies the number of tuples, not a byte limit.) Also the buffer is flushed at the regular interval specified by the flush_interval parameter. If the flush_interval is not greater than zero, the buffer is only flushed when it reaches capacity (that is, when it is filled with tuples).

The following example demonstrates how to enable buffering in .NET:

using StreamBase.SB;
using StreamBase.SB.Client;
    .
    .
    .
    // connect to the StreamBase Server.
    string uri = "sb://localhost:10000";
    int buf_size = 100;
    int flush_interval = 1000;
    StreamBaseClient client = new StreamBaseClient(uri);
    client.EnableBuffering(buf_size,flush_interval);

Note: As with the C++ library, if buffering is enabled and the flush_interval is set, the buffer is flushed periodically based on the specified interval. However, to have more control over enqueuing buffered tuples, you can also use the flushBuffer(stream_name) method of the StreamBaseClient class to enqueue the contents of a buffer immediately. Or, you can use the flushAllBuffers() method to enqueue the contents of all buffers. These methods assume that the caller has a lock on _buffers_lock.

Generally you want to flush a buffer when you are concerned that the tuples in the buffer may become stale. The determination of staleness depends on the particular application.

For example, suppose your buffer size is 1000 and your flush_interval is 0 (this value turns off periodic flushing). The buffer is automatically flushed when it is filled (that is, when the 1000th tuple has been enqueued). If 300 tuples have just been enqueued and it is unclear when or whether more tuples will arrive to fill the buffer, it would be a good idea to call flushBuffer() or flushAllBuffers().

Writing .NET Dequeue Clients

This section describes how to use the StreamBase .NET library to write a client application that dequeues data from a StreamBase Server.

Note: You can make your application dequeue a subset of the server output instead of all the output. For details, see Narrowing Dequeue Results with Filtered Subscribe.

Performance Note: Dequeue (producer) clients that are slow may eventually get disconnected from the StreamBase Server process. The sbd process disconnects clients that try to allocate more memory than the limit set by the max-client-pages parameter in the server configuration file, which is designed to protect sbd from a slow or hung dequeue client.

Sample source code: streambase-install-dir\sample\dotnet\SimpleDequeuer\SimpleDequeuer.cs

The basic procedure for dequeuing data from a StreamBase node in .NET is as follows:

Use Visual Studio 2012 or later to create a new Visual C# project.
Add a reference to StreamBase.SB.Client.dll, as in the previous procedure.
Add the following lines to the top of the C# source file to access the StreamBase classes:
```
using StreamBase.SB;
using StreamBase.SB.Client;
```
Create an instance of the StreamBaseClient class. If needed, specify the String URI of the desired StreamBase node as an argument. For example:
```
StreamBaseClient client = new StreamBaseClient("sb://localhost:10000/");
```
Subscribe to each stream you want to dequeue. For example:
```
client.Subscribe("OutputStream");
```
where OutputStream is the name of an output stream in your StreamBase application.
Call the Dequeue() method on the client, which blocks until a tuple becomes available. This method returns a DequeueResult object that contains the names of each of the streams to which you subscribed, and the tuples dequeued on the streams. For example:
```
DequeueResult dr = client.Dequeue();
```
If the result's Status property is set to DequeueResult.CLOSED, the server (or your client from another thread) is requesting that you close the connection. In this case, exit the dequeue() method. For example:
```
if (dr.Status == DequeueResult.CLOSED) return;
```

Otherwise, you can:

Discover the stream from which the tuple was dequeued. For example:
```
String stream = dr.GetStreamName();
```

Use it to access the tuple's constituent fields. For example:

foreach (Tuple tuple in dr) {
    int myint = tuple.GetInt("myint");
    // ...
    // where "myint" and "mystring" are field names in the output stream
    // of your StreamBase application
}

If you wish to cancel the blocking dequeue call from any thread (for example, if your client is shutting down), call client.Close(). In fact, before exiting, always call client.Close() to flush the client network buffers.

Compiling .NET Dequeue Clients

The procedure is the same as for enqueue clients. Remember to always call client.close() to flush the client network buffers before exiting.

Deploying .NET Clients

You can run .NET client applications on computers that do not have StreamBase installed on them. To run StreamBase .NET client applications, the target machine must have the .NET framework 4.0 or later, and must have a set of StreamBase assemblies and supporting DLLs. These components are installed as part of your StreamBase installation. You need to place the StreamBase .NET redistributables on each target machine. For details, see Redistributing the .NET Client Library.