Creating StreamBase .NET Clients

This topic describes how to create enqueue and dequeue .NET client applications for StreamBase applications. The .NET API is available only in the StreamBase installation for Microsoft Windows.

Note

StreamBase 5.0 introduced a new version of the StreamBase .NET API, as described in this topic. This new API uses version 2.0 of the .NET Framework, and requires Microsoft Visual Studio 2005 or later.

If you have existing .NET StreamBase clients, you must adjust your code to work with StreamBase 5.0 or later servers. See Migrating .NET Clients.

Topics:

Writing .NET Enqueue Clients

This section describes how to use the StreamBase .NET API 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 API reference is added to the Windows Start menu when you install StreamBase on Windows. To open it, select Start > (All) Programs > StreamBase > StreamBase API Documentation > StreamBase .NET API Documentation.

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

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

Use Microsoft Visual Studio 2005 or later to create a new Visual C# project.
Add a reference to sbclient.dll, which is installed by default in C:\Program Files\StreamBase Systems\StreamBase.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 enqueueing client can be compiled and run from Visual Studio. It can also be run outside of Visual Studio by typing:

sample\SimpleEnqueuer\bin\Release\SimpleEnqueuer.exe

Buffering for .NET Enqueue Clients

For enqueue clients that use the StreamBase .NET Library API, 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 APIs, 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++ API, 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 enqueueing 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 API 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, sbd. StreamBase uses the memory parameter Maximum pages per client connection in StreamBase Studio, and max-client-pages in the server's *.sbconf configuration file. The sbd process will disconnect clients that try to allocate more memory than the limit set by this parameter. It is designed to protect sbd from a slow or hung dequeue client. For more information, see Defining a StreamBase Server Configuration in the Administration Guide.

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

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

Use Visual Studio 2005 or later to create a new Visual C# project.
Add a reference to sbclient.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 Writing .NET Enqueue Clients. Remember to always call client.close() to flush the client network buffers before exiting.

Deploying .NET Clients on Non-StreamBase Systems

StreamBase .NET clients can be installed and run on systems that do not have StreamBase installed. For details on the StreamBase .NET Redistributables kit, contact StreamBase Technical Support.