Lesson 5: Introduction to Content Matchers

Transcription

1 20 Lesson 5: Introduction to Content Matchers Content matchers (or simply matchers) provide a mechanism to specify which messages a subscribing client program is interested in receiving. Message interest is based on the message content, specifically the presence or value of one or more fields in a message. Matching determines which messages are delivered to the subscriber. In this lesson you will learn about matchers, modify the ftlsamplepub.c and ftlsamplesub.c client programs to use them, and then experiment with the updated programs. The updated files can be found in $TIBFTL_TUTDIR/code/lesson Matcher Specification Matchers use JSON expressions to specify the fields and values of interest. While the details of JSON are available elsewhere, we will briefly describe the format of a matcher string. A matcher string consists of one or more conditions, separated by commas and enclosed in curly braces ({}). A condition consists of a quoted string containing the field name, followed by a colon, followed by the field value. A field value is one of the following: A string contained in double quotes A long integer value A boolean constant (true or false) indicating the presence or absence of the field Some simple examples of matcher strings are: {"tag":"hello"} {"tag":true} {"tag":"hello","content":true} The first example matches a message if its "tag" field contains the value "hello". If the "tag" field is not present in the message, the condition is implicitly false. The second example matches a message if the "tag" field is present in the message, regardless of its value. If a matcher contains more than one condition, each condition must be true for the message to match. In the third example there are two conditions: the "tag" field must contain the value "hello", and the "content" field must be present. Both conditions must be true for the message to be delivered to the subscriber. 5.2 ftlbasicpub.c We ll take the sample code from lesson 3 and add matcher support with only a few minor changes.

2 21 13 const char *fieldname = NULL; if (argc > 1) 16 { 17 fieldname = argv[1]; 18 } ftlbasicpub.c now accepts an optional command-line argument. This argument is used as the name of a field to include in the published messages. Lines 15 through 18 check if the argument is present, and if it is, stores the string in fieldname for later use. 29 if (fieldname!= NULL) 30 { 31 tibmessage_setstring(ex, msg, fieldname, fieldname); 32 } If fieldname is not NULL, then the optional field name argument was specified on the command line. Line 31 adds that field to the message. For simplicity, the field value is the same as the field name. Note that fieldname was initialized to NULL in line 13 above. So if the command line argument was not specified, fieldname is still NULL, indicating not to add the field to the published message. 5.3 ftlbasicsub.c The changes made to ftlbasicsub.c from lesson 3 in support of matchers are a little more extensive. 26 const char *fieldname = NULL; 27 tibcontentmatcher cm = NULL; 28 char matcher[256]; if (argc > 1) 31 { 32 fieldname = argv[1]; 33 sprintf(matcher, "{\"%s\":true}", fieldname); 34 } Like ftlbasicpub.c, ftlbasicsub.c accepts an optional command line argument. This time the argument is used as the name of a field to match. Lines 30 through 34 check for the presence of the argument, and if it exists, line 33 creates a JSON matcher string using the field name. Assuming abc was specified on the command line, the resulting matcher string will look like this: {"abc":true} This matcher string will match a message only if the "abc" field is present in the message. 39 if (fieldname!= NULL) 40 { 41 cm = tibcontentmatcher_create(ex, realm, matcher); 42 } 43 sub = tibsubscriber_create(ex, realm, NULL, cm, NULL); If a matcher field name was specified on the command line, line 41 uses the matcher string to create a matcher object, which is passed to tibsubscriber_create() in line 43. The resulting subscriber will only receive messages which match the content matcher.

3 22 56 if (cm!= NULL) 57 { 58 tibcontentmatcher_destroy(ex, cm); 59 } Lines 56 through 59 destroy the matcher object, as it is no longer needed. 5.4 Build and Run the Samples In a command window, navigate to $TIBFTL_TUTDIR/code/lesson-05 and build the samples: make Once built, run the subscriber with no arguments:./ftlbasicsub In another command window, navigate to $TIBFTL_TUTDIR/code/lesson-05 and run the publisher with no arguments:./ftlbasicpub The output should appear as: sending hello world messages Listing 5.1: Output from ftlbasicpub Back in the subscriber command window, you should see: {string:type="hello", string:contents="hello world", long:seq=1} {string:type="hello", string:contents="hello world", long:seq=2} {string:type="hello", string:contents="hello world", long:seq=3} {string:type="hello", string:contents="hello world", long:seq=4} {string:type="hello", string:contents="hello world", long:seq=5} Listing 5.2: Output from ftlbasicpub run with no arguments Both programs give the same output as seen in lesson 3. Simply adding the code to use matchers has not changed either program s behavior if no argument is given. Now, let s try running them with an argument. In the subscriber command window, stop the subscriber with ctrl + C. Restart it with a command-line argument:

4 23 In the publisher command window, run the publisher with the same command-line argument: The output from the publisher is the same, but the output from the subscriber now shows that the messages include the "abc" field: Listing 5.3: Output from ftlbasicsub abc This output is similar to the previous run, but notice that each now has a string field called "abc" with the value "abc". Leave the subscriber running. In the publisher command window, run the publisher with no command-line argument:./ftlbasicpub Back in the subscriber command window, you should see no additional output beyond what was already seen in Listing 5.3. The subscriber that was started with the abc command line argument is still running. When started, it created a matcher requiring that the "abc" field be present in a message for that message to be delivered to the subscriber. However, the publisher was started without the command line argument, so it is sending messages without the "abc" field. The incoming messages did not match the subscriber s matcher, preventing the messages from being delivered to the subscriber. The matcher is doing what it is supposed to. Stop the subscriber with ctrl + C. 5.5 Some Variations Next, let s experiment with some variations. In the subscriber command window, restart the subscriber with: Open a new command window, navigate to $TIBFTL_TUTDIR/code/lesson-05, and start a second subscriber:

5 24 We are starting two separate instances of the subscriber, both matching the field "abc". In the publisher command window, start the publisher with: If you look in both subscriber command windows, you should see the same output: Listing 5.4: Output from ftlbasicsub abc Both subscribers match and receive the messages sent by the publisher. Next, stop both subscribers with ctrl + C. In one subscriber command window, start the subscriber with: In the publisher command window, start the publisher with: In another command window, navigate to $TIBFTL_TUTDIR/code/lesson-05. Start a second publisher by typing: This time, the output in the subscriber command window is:

6 25 Listing 5.5: Output from ftlbasicsub abc The subscriber has s from two separate instances of the publisher. Concept 5. In FTL, a publisher can publish to multiple subscribers at the same time, and a subscriber can receive from multiple publishers at the same time, subject to any matching criteria in the subscribers. Depending on how quickly the two publishers are started, the exact ordering of the output may be slightly different than seen in Listing 5.5, but should still show 10 messages: two with "seq" 1, two with "seq" 2, and so forth.