lesson 9: properties - tibco softwarelesson 9: properties a properties object (tibproperties)...

64

Lesson 9: Properties

A properties object (tibProperties) represents a set of configuration name/value pairs. Properties areused when creating or initializing objects, allowing additional control over an object’s configuration.

Properties can be used with realms, publishers, subscribers, event queues, and various other objects.

9.1 The Properties API

Each property consists of a character string name and a value.

Six types are supported for a property value:

• Boolean

• 32-bit signed integer

• 64-bit signed integer

• Double precision floating-point

• String

• Message (tibMessage).

9.1.1 FTL API Functions to Create and Destroy Properties

tibProperties tibProperties_Create(tibEx e);void tibProperties_Destroy(tibEx e, tibProperties properties);

As with other FTL objects, a properties object must be created before use and should be destroyed when itis no longer needed. tibProperties_Create() is used to create a properties object, andtibProperties_Destroy() destroys a properties object.

9.1.2 FTL API Functions to Set Property Values

void tibProperties_SetBoolean(tibEx e, tibProperties properties, const char* name,tibbool_t value);

void tibProperties_SetInt(tibEx e, tibProperties properties, const char* name, tibint32_t value);void tibProperties_SetLong(tibEx e, tibProperties properties, const char* name,

tibint64_t value);void tibProperties_SetString(tibEx e, tibProperties properties, const char* name,

const char* value);void tibProperties_SetMessage(tibEx e, tibProperties properties, const char* name,

const tibMessage value);void tibProperties_SetDouble(tibEx e, tibProperties properties, const char* name,

tibdouble_t value);

Six functions are provided to set property values, one for each supported value type. Each takes anexception (tibEx) object as the first argument, the properties (tibProperties) object on which to

TIBCO FTL R� Programming Tutorial

65

operate as the second argument, and a string containing the property name as the third argument. The finalargument is the value to be set for the property.

9.1.3 FTL API Functions to Get Property Values

tibbool_t tibProperties_GetBoolean(tibEx e, tibProperties properties, const char* name);tibint32_t tibProperties_GetInt(tibEx e, tibProperties properties, const char* name);tibint64_t tibProperties_GetLong(tibEx e, tibProperties properties, const char* name);const char* tibProperties_GetString(tibEx e, tibProperties properties, const char* name);const tibMessage tibProperties_GetMessage(tibEx e, tibProperties properties, const char* name);tibdouble_t tibProperties_GetDouble(tibEx e, tibProperties properties, const char* name);

Corresponding to each FTL API function to set a property value is a function to get a property value. Eachtakes an exception (tibEx) object as the first argument, the properties (tibProperties) object on whichto operate as the second argument, and a string containing the property name to fetch as the third argument.Each returns the value as the proper type.

9.1.4 FTL API Property Utility Functions

tibbool_t tibProperties_Exists(tibEx e, tibProperties properties, const char* name);tibbool_t tibProperties_Remove(tibEx e, tibProperties properties, const char* name);tibProperties tibProperties_Copy(tibEx e, tibProperties properties);

tibProperties_Exists() allows the existence of a specific name within a properties object to betested, and tibProperties_Remove() removes an individual name from a properties object. Each takesan exception (tibEx) object as the first argument, the properties (tibProperties) object on which tooperate as the second argument, and a string containing the property name to test for or remove as the thirdargument.

tibProperties_Copy() can be used to duplicate a properties object, returning a new tibPropertiesobject which contains the same name/value pairs as the original object.

9.2 Property Names

Valid property names are defined in several header files provided with the FTL distribution, located in$TIBFTL_DIR/include/ftl. Realm property names are defined in realm.h, publisher property namesin pub.h, subscriber property names in sub.h, and event queue property names in queue.h.

All property name symbols are of the form TIB_obj_PROPERTY_type_name. obj denotes the FTLobject to which the property applies, and is one of REALM, PUBLISHER, SUBSCRIBER, or EVENTQUEUE.type denotes the data type of the property value, and is one of BOOL, INT, LONG, STRING, DOUBLE, orBOOLEAN. name denotes the property name.

Note that this naming convention applies only to the property name symbols defined in the header files. Theproperty names themselves do not follow the same conventions. Property names may change, but theproperty name symbols will not. For compatibility with future versions of FTL only the symbol namesshould be used.

While there are dozens of properties, for now we will discuss only a few of them.


66

9.2.1 Realm Connect Maximum Retries

The realm connect maximum retries property (TIB_REALM_PROPERTY_LONG_CONNECT_RETRIES) is along realm property which determines how many attempts are made to connect to a realm service. Itdefaults to zero, which indicates to retry forever.

We made use of this property in the sample programs: without it, if the FTL server is not running, the callto tibRealm_Connect() would never return to indicate an error.

9.2.2 Realm Connect Interval

The realm connect interval property (TIB_REALM_PROPERTY_DOUBLE_CONNECT_INTERVAL) is a doublerealm property which determines how long to wait between connect attempts to a realm service. It defaultsto 1.0 seconds.

9.2.3 Publisher Release Ownership of Messages Property

The publisher release ownership of messages property(TIB_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND) is a boolean publisher property whichcontrols ownership of message objects sent through a publisher. It defaults to tibfalse, in which case theclient program retains ownership of messages.

If set to tibtrue, the FTL library takes ownership of messages sent through this publisher whentibPublisher_Send() is called. From that point forward, the client program must no longer referencethe tibMessage object, including calling tibMessage_Destroy(). The FTL library could destroy themessage object at any time.

Lesson 4 presented the concept that a client program is responsible for destroying a message it creates, andit was noted that lesson 9 would cover the single exception. This is the exception: if the FTL library isgiven ownership of the message by virtue of theTIB_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND property, the client program must notdestroy the message.

Recall from lesson 8, ftlpub.c reuses the message object it created. This approach worked because thedefault value for the publisher release property is tibfalse, and the code did not explicitly set theproperty, meaning the client program retained ownership of the message object after thetibPublisher_Send() call. An important concept noted at the time (Concept 6, page 48) was that amessage could be reused.

At this point we need to slightly amend that concept:

Concept 6. (Revised) A message object can be reused multiple times as long as the client program retains

ownership of the message object.

9.2.4 Client Label Property

The client label property (TIB_REALM_PROPERTY_STRING_CLIENT_LABEL) is a string realm propertywhich sets the client label for a client program. Its primary purpose is to help distinguish one clientprogram from another (or one instance of a given client program from another) in monitoring, including theFTL server monitoring displays, essentially allowing you to name the role a client program plays.

Monitoring is covered in depth in a future lesson.


67

It is highly recommended that this property be set for all client programs. Set it using a convention thathelps you distinguish clients in the ways that are imporant to your enterprise — whether by role, byprogram name, by unique identity, or any combination of identifying information.

9.3 Using Properties

The modified versions of ftlpub.c and ftlsub.c, which include support for FTL properties, can befound in $TIBFTL_TUTDIR/code/lesson-09. Rather than look at the entire programs in detail, we’llfocus on the modifications made to support FTL properties.

9.3.1 ftlpub.c

9 #define DEFAULT_REALM_SERVICE "http://localhost:8080"10 #define DEFAULT_APPLICATION NULL11 #define DEFAULT_ENDPOINT NULL12 #define DEFAULT_CLIENTLABEL "tibpub"13 #define DEFAULT_MSG_COUNT 201415 const char * RealmService = DEFAULT_REALM_SERVICE;16 const char * Application = DEFAULT_APPLICATION;17 const char * Endpoint = DEFAULT_ENDPOINT;18 const char * ClientLabel = DEFAULT_CLIENTLABEL;19 tibint64_t MsgCount = DEFAULT_MSG_COUNT;

Listing 9.1: ftlpub.c Part 1

We’ve added a default value for the client label property, and a variable for the client label, with the intentof allowing it to be set from the command line.

21 const char * Options = "a:c:e:hl:r:";2223 void print_usage(void)24 {25 fprintf(stderr,26 "Usage: ftlpub [options]\n"27 " -a APPLICATION set application name\n"28 " -c COUNT send COUNT data messages\n"29 " -e ENDPOINT set endpoint name\n"30 " -h print this help\n"31 " -l CLIENTLABEL set the client label\n"32 " -r URL use realm service URL\n"33 );34 exit(1);35 }


One new command-line argument is added: -l sets the client label. parse_arguments() has also beenextended to handle the new argument, and we’ve added it to the usage message as well.


68

69 int main(int argc, char** argv)70 {71 tibEx ex = NULL;72 tibRealm realm = NULL;73 tibPublisher pub = NULL;74 tibMessage msg = NULL;75 tibProperties props = NULL;76 tibint64_t idx;


main() now defines a tibProperties variable for creating the properties object.

83 props = tibProperties_Create(ex);84 tibProperties_SetString(ex, props, TIB_REALM_PROPERTY_STRING_CLIENT_LABEL, ClientLabel);85 realm = tibRealm_Connect(ex, RealmService, Application, props);86 CHECK(ex);87 tibProperties_Destroy(ex, props);


We’ve added code to create the properties and set the string propertyTIB_REALM_PROPERTY_STRING_CLIENT_LABEL. The properties object is passed as the last argument totibRealm_Connect(); previously a NULL had been specified here. Finally, the properties object isdestroyed when no longer needed.

95 printf("using Realm Service=%s\n\tApplication=%s\n\tEndpoint=%s\n\tClientLabel=%s\n",96 RealmService,97 (Application != NULL ? Application : "default"),98 (Endpoint != NULL ? Endpoint : "default"),99 ClientLabel);


We’ll also expand the output message to include the client label, so we can see that information at run time.

9.3.2 ftlsub.c

The changes made to ftlsub.c parallel those made to ftlpub.c.

9 #define DEFAULT_REALM_SERVICE "http://localhost:8080"10 #define DEFAULT_APPLICATION NULL11 #define DEFAULT_ENDPOINT NULL12 #define DEFAULT_CLIENTLABEL "tibsub"1314 const char * RealmService = DEFAULT_REALM_SERVICE;15 const char * Application = DEFAULT_APPLICATION;16 const char * Endpoint = DEFAULT_ENDPOINT;17 const char * Matcher = NULL;18 tibbool_t Verbose = tibfalse;19 const char * ClientLabel = DEFAULT_CLIENTLABEL;

Listing 9.6: ftlsub.c Part 1


69

We add a default value and variable for the client label property.

26 const char * Options = "a:e:hl:m:r:v";2728 void print_usage(void)29 {30 fprintf(stderr,31 "Usage: ftlsub [options]\n"32 " -a APPLICATION set application name\n"33 " -e ENDPOINT set endpoint name\n"34 " -h print this help\n"35 " -l CLIENTLABEL set the client label\n"36 " -m CONTENT use matcher\n"37 " -r URL use realm service URL\n"38 " -v verbose output\n"39 );40 exit(1);41 }


We have made the same changes to the command-line parsing code to handle the client label options.

170 int main(int argc, char** argv)171 {172 tibEx ex = NULL;173 tibRealm realm = NULL;174 tibEventQueue queue = NULL;175 tibSubscriber sub = NULL;176 tibContentMatcher cm = NULL;177 tibProperties props = NULL;


We define a new tibProperties variable for creating the properties object.

184 props = tibProperties_Create(ex);185 tibProperties_SetString(ex, props, TIB_REALM_PROPERTY_STRING_CLIENT_LABEL, ClientLabel);186 realm = tibRealm_Connect(ex, RealmService, Application, props);187 CHECK(ex);188 tibProperties_Destroy(ex, props);


The same changes are made (as in ftlpub.c) to create the properties object, set its value, pass it to thetibRealm_Connect() call, then destroy it when no longer needed.

204 printf("using Realm Service=%s\n\tApplication=%s\n\tEndpoint=%s\n\tMatcher=%s\n\tClientLabel=%s\n",

205 RealmService,206 (Application != NULL ? Application : "default"),207 (Endpoint != NULL ? Endpoint : "default"),208 (Matcher != NULL ? Matcher : "none"),209 ClientLabel);



70

Finally, we add the client label to the program output so we can see the client label used.

9.4 Build and Run the Samples

To build and run the samples, make sure the Realm Server is running, and open a command window.Navigate to $TIBFTL_TUTDIR/code/lesson-09, rebuild the samples, and run the subscriber:

make./ftlsub

In another command window, navigate to $TIBFTL_TUTDIR/code/lesson-09 and run the publisher:

./ftlpub

The output from ftlpub should be familiar, with the addition of the new client label information:

using Realm Service=http://localhost:8080Application=defaultEndpoint=defaultClientLabel=tibpub

sending initial messagesending 20 data messagessending final message

Listing 9.11: ftlpub output

The output from ftlsub should also include the new client label information:

using Realm Service=http://localhost:8080Application=defaultEndpoint=defaultMatcher=noneClientLabel=tibsub

waiting for message(s)received BOS indicatorreceived EOS indicatorReceived 2 control, and 20 of 20 data messages.

Listing 9.12: ftlsub output

The output from both is as expected. The default application, endpoint, and client label values are being setand used.

9.5 Identifying Clients Revisited

In lesson 8 (Section 8.6, page 63), we looked at the Client Details in the realm service web interface, notingthat at that point there was no way to distinguish the publisher client from the subscriber client. The use ofthe client label property (TIB_REALM_PROPERTY_STRING_CLIENT_LABEL) provides a solution to thisproblem.

In the subscriber command window, start the subscriber with client label “subscriber”:


71

./ftlsub -l subscriber

In the publisher command window, start the publisher with the client label “publisher”, and have it send100 messages:

./ftlpub -c 100 -l publisher

Now it’s time to see what the monitoring information looks like now that we’ve added client label support.Open a web browser and navigate to the URL http://localhost:8080. If the FTL server login page isdisplayed, login as you did in Section 6.1, page 27. Bring up the Applications grid by clicking on thelink on the left side of the screen.

Figure 9.1: Applications grid

Click anywhere in the status area at the top of the page to show the Status Dashboard:


72

Figure 9.2: Status Dashboard

Click “Clients” to display client information:

Figure 9.3: Client Status Display

We are now able to easily identify each client by the value under “Client Label”.


lesson 9: properties - tibco softwarelesson 9: properties a properties object (tibproperties)...

Documents