- Index

< Previous |  | Next >

# Narrowing Dequeue Results with Filtered Subscribe

You can use the StreamBase Java, C++, or (on Windows only) .NET Client library to write a dequeue client that narrows the result set, by using a predicate on the subscription to an output stream. The predicate is applied to the data output from the stream before it is delivered to the client. The predicate language follows the same rules and syntax as implemented in the Filter operator.

We have provided Java and C++ client application examples with the installed `client` sample:

`/opt/tibco/sb-cep/`n.m```/sample/client/FilteredSubscribe.java`

/opt/tibco/sb-cep/`n.m``/sample/client/FilteredSubscribe.cpp`

Note: The syntax of the `client.subscribe()` method is nearly identical in the Java, C++, and .NET APIs. When using the Filtered Subscribe API feature with .NET, the caller must provide two additional parameters in addition to the `streamname` parameter:

- `logical streamname`

- `predicate`

The `logical streamname` is the name used to deliver the tuples to the dequeuing application. The `logical streamname` must be unique for all subscriptions within the client connection. Do not use the name of another stream in the application as the `logical streamname`, otherwise you will not be able to subscribe to that other stream. The predicate is a statement that must evaluate to `true` or `false`, and is applied to each tuple before being returned to the client. If the evaluation is `true` then the tuple is delivered, else it is not delivered to the client.

In Java, C++, and .NET, the `client.subscribe` call for a Filtered Subscribe looks like the following example:

        client.subscribe("OutputStream1", "IBM-gt-85", "symbol=='IBM' && price>85.0");

Note: In .NET, the Subscribe method starts with an uppercase 'S'.

In this example, `"OutputStream1"` is the stream and `"IBM-gt-85"` is the `logical streamname`. The string `"symbol=='IBM' && price>85.0"` is the predicate. Note that the predicate must be surround by a pair of double quotes or single quotes. Tuples are returned to the dequeue client if the two clauses evaluate to true, namely all shares of IBM whose price is greater than 85.0. In the following code in C++:

        client.dequeue(streamname);

where `streamname` contains the string `"IBM-gt-85"`. The corresponding Java example is:

        DequeueResult dr = null;
        dr = client.dequeue();
        streamname = dr.getStreamName();

A client can apply multiple predicates to a single stream, as long as the `logical streamnames` are unique. Also, a client may dequeue as before, without a predicate, on the same or a different stream. If a tuple matches more than one predicate, it is delivered more than once, to each `logical streamname`. For example, if a tuple contains the values `"IBM,86.2,300"` where `IBM` is the symbol, `86.2` is the price, and `300` is the volume, and the subscribe calls are:

        client.subscribe("OutputStream1", "IBM-price-LT-90", "symbol=='IBM' && price<90.0");
        client.subscribe("OutputStream1", "Volume-GT-200", "volume>200");
        client.subscribe("OutputStream1");

Then the output will be:

        stream:             tuple:
        IBM-price-LT-90:    IBM,86.2,300
        Volume-GT-200:      IBM,86.2,300
        OutputStream1:      IBM,86.2,300

Because both predicates evaluate to true on this tuple and the third subscribe returns all tuples on `OutputStream1`.

In order to unsubscribe from a stream with a predicate, you must supply the `logical streamname`. Other filtered subscribes on that stream are unaffected by such an unsubscribe.

## Related Topics

- API Guide