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/str/11.0/sample/client/FilteredSubscribe.java

/opt/tibco/str/11.0/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:

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.