26

Lesson 6: Exploring the Realm

In this lesson we take a step back from FTL API programming and explore the realm definitions madeavailable by the realm server. We’ll look at the definitions through both the realm server web interface andthe realm server web API.

In order to get the most from this lesson, make sure you have read the TIBCO FTL R� Concepts guide beforeproceeding.

Note

Throughout the remaining lessons, it is assumed that the realm server and sample programs arerunning on the same computer. This allows the realm server to be addressed vialocalhost:8080.

If you want to run the realm server on a different computer, a few changes must be made.

• Start the realm server (on the desired computer) using the start_rs script in$TIBFTL_TUTDIR/scripts, and specify the actual address and port. For example, ifthe computer on which the realm server is to run has the address 192.168.10.1, and port9000 is to be used, the command would be:

./start_rs 192.168.10.1:9000

Likewise, when stopping the realm server using the stop_rs script, use:

./stop_rs 192.168.10.1:9000

• When accessing the realm server web interface, rather than navigating tohttp://localhost:8080, use (assuming the values above)http://192.168.10.1:9000.

• Change the URL in any curl command lines to reference the correct address and port.

• Add the -r ip:port option to any sample program command lines. Substitute thecorrect address and port for ip:port.

6.1 The Realm Server Web Interface

Assuming the realm server is still running, open a web browser and navigate to the URLhttp://localhost:8080. The resulting screen is shown in Figure 6.1.

TIBCO FTL R� Programming Tutorial

27

Figure 6.1: Realm server login page

Full documentation on the realm server web interface can be found in the TIBCO FTL R� Administrationguide.

The first page shown is the login page. Normally you would enter the user ID and password assigned byyour administrator. For the sake of simplicity, in this tutorial we are running the realm server withoutsecurity, in insecure mode. Insecure mode allows only a single user ID, “anyone”, with no password.

Click the “SIGN IN” button to display the next page:

TIBCO FTL R� Programming Tutorial

28

Figure 6.2: Applications grid

Figure 6.2 shows the Applications grid, which displays all applications defined in the FTL system. Foreach application, the endpoints associated with it are shown, along with the transports associated with eachendpoint.

Along the left side of the page appear a series of links, each with an icon and description, which navigate tospecific pages in the realm server web interface. For example, the link denoted by the icon, and labeled“Applications”, takes you to the Applications grid.

What is shown in Figure 6.2 is the initial, default configuration provided when starting a new realm server.A single application is defined, “default”, along with its corresponding endpoints and transports.

The samples we’ve developed in previous lessons have implicitly used the “default” application. If youlook back at ftlbasicpub.c from lesson 5 ($TIBFTL_TUTDIR/code/lesson-05/ftlbasicpub.c),you see the line:

21 realm = tibRealm_Connect(ex, "http://localhost:8080", NULL, NULL);

The third argument to tibRealm_Connect() is a character string containing the application name. Byspecifying NULL, we are telling FTL to use the default application, which is conveniently named “default”— and is exactly the “default” application shown in Figure 6.2.

So, let’s take a look at the “default” application in more detail by clicking on the “default” applicationname. You should see a screen similar to Figure 6.3.

TIBCO FTL R� Programming Tutorial

29

Figure 6.3: “default” Application details panel

This panel shows the detailed application information, including the application name (“default”) andapplication description. We can ignore the “Manage All Formats”, “Preload Formats”, and “InstanceMatching Order” items for now.

In the upper-right corner of the application display, a (close) control is shown. Clicking on this controlcloses the currently shown details panel, and is a common interaction used throughout the realm server webinterface. Close the Application details panel by clicking on the close control, which will take you back tothe Applications grid:

TIBCO FTL R� Programming Tutorial

30

Figure 6.4: Applications grid

The “default” application defines a single endpoint named “default”. The samples we’ve developed thus farhave implicitly used not only the “default” application, but also the “default” endpoint.

In $TIBFTL_TUTDIR/code/lesson-05/ftlbasicpub.c we had the line:

23 pub = tibPublisher_Create(ex, realm, NULL, NULL);

The third argument to tibPublisher_Create() is a string containing the endpoint name (within thatapplication) on which to publish. By specifying NULL, we are telling FTL to use the default endpointwithin the application, named “default”.

Similarly, in $TIBFTL_TUTDIR/code/lesson-05/ftlbasicsub.c we had the line:

1 sub = tibSubscriber_Create(ex, realm, NULL, cm, NULL);

The third argument to tibSubscriber_Create() is a string containing the endpoint name (within thatapplication) to subscribe to. By specifying NULL, we are telling FTL to use the default endpoint within theapplication, named “default”.

So let’s take a deeper look at the “default” endpoint. Click the “default” endpoint, which will open theEndpoint details panel:

TIBCO FTL R� Programming Tutorial

31

Figure 6.5: “default” Endpoint details panel

“Store”, “Dynamic Durable template”, and “Subscriber Name Mapping” deal with persistence and can beignored for now. “Endpoint Abilities” lists the transports associated with this endpoint: in this case, asingle transport called “default”. Also shown are the abilities this endpoint has for each transportassociated with it: whether it can Receive messages, Send messages, receive Inbox messages, or Send toanother application’s Inbox. Inboxes will be discussed in a later lesson.

It is important to note that the default application, endpoint, and transport really are named “default”. Thisis not a reserved, hidden, or otherwise special name, but is the object reference used by the realm serverwhen no explicit application or endpoint is specified. In the case of transports, this is an actual transportnamed “default” which is explicitly defined for the “default” application’s “default” endpoint, just like anyother explicitly named transport. These “default” configuration settings are available when starting from anempty realm configuration and will remain part of the realm configuration unless they are explicitly deleted.

Let’s take a look at the “default” transport. Along the left side of the page you’ll see a icon labelled“Transports”. Click it, which will take you to the Transports grid as shown in Figure 6.6.

TIBCO FTL R� Programming Tutorial

32

Figure 6.6: Transports grid

The “default” transport uses the Dynamic TCP protocol. Click the transport name to display the details forthe “default” transport:

Figure 6.7: “default” Transport details panel

The specific configuration settings for the Dynamic TCP transport, as well as other transport types, arediscussed in a later lesson.

TIBCO FTL R� Programming Tutorial

33

It should be noted that while an endpoint is associated with and belongs to a specific application, and atransport is associated with an endpoint, transports do not belong to an endpoint. Rather, they belong to therealm as a whole. A single transport may be used by multiple endpoints in a single application, as well asendpoints in different applications.

6.2 The Realm Server Web API

The realm server web API can also be used to view, add, and modify definitions for FTL objects. For oursamples, we’ll use the open-source curl utility to access the realm server web API.

Consult the TIBCO FTL R� Administration guide for details on the realm server web API.

JSON is used to represent FTL configuration information, both as input to add and modify objects, and asoutput to return the results of a realm server web API operation.

Assuming the realm server is still running, open a command window and type:

curl -X GET http://localhost:8080/api/v1/realm/applications/default

The resulting output is shown in Listing 6.1.

1 {2 "last_modified": "XXXX-XX-XXTXX:XX:XX.XXXXXXXXX-XX:XX",3 "last_modified_millis": XXXXXXXXXXXXX,4 "last_modified_by": "ftl",5 "name": "default",6 "id": XXX,7 "description": "",8 "manage_all_formats": false,9 "preload_format_names": [],

10 "endpoints": [11 {12 "name": "default",13 "id": XXX,14 "description": "",15 "transports": [16 {17 "name": "default",18 "receive": true,19 "receive_inbox": true,20 "send": true,21 "send_inbox": true22 }23 ],24 "dynamic_durable": {},25 "subscribers": []26 }27 ],28 "instances": []29 }

Listing 6.1: “default” application realm server web API output

This corresponds to the application definition from Figure 6.3, and you should be able to correlate itemsvisible via the realm server web interface with items in the JSON output.

A few things to note:

• Line 5 defines the name of the application, "default".

TIBCO FTL R� Programming Tutorial

34

• Lines 10 through 27 list the endpoints. The value of the "endpoints" key is an array of objects. Inthis case the array contains a single endpoint object.

– Line 12 is the endpoint name, "default".

– Lines 15 through 22 list the transports associated with that endpoint. Since an endpoint canhave more than one transport, the value of the "transports" key is an array of objects, in thiscase a single object, the transport ("default") associated with this endpoint.

The JSON output also contains other information which we will discuss in later lessons.

Next we will retrieve the definition for the “default” transport. In the open command window, type:

curl -X GET http://localhost:8080/api/v1/realm/transports/default

The output is shown in Listing 6.2.

1 {2 "last_modified": "XXXX-XX-XXTXX:XX:XX.XXXXXXXXX-XX:XX",3 "last_modified_millis": XXXXXXXXXXXXX,4 "last_modified_by": "ftl",5 "name": "default",6 "description": "",7 "relationships": [],8 "id": XXX,9 "config": {

10 "transport_type": "dtcp",11 "backlog_full_wait": "0",12 "recv_spin_limit": "0.01",13 "backlog_size": "64mb",14 "port": "0",15 "subnet_mask": "",16 "mode": ""17 }18 }

Listing 6.2: “default” transport realm server web API output

There are just two items of note here:

• Line 5 is the transport name, "default".

• Lines 9 through 17, the "config" key and its value object, describe the transport configurationitself. The actual keys in the value object depend on the transport type, which is the value on line 10.This default transport definition specifies a dynamic TCP type ("dtcp"). The remaining keys in theconfiguration object are the default values for that transport type.

TIBCO FTL R� Programming Tutorial