Search Results

TIBCO eFTL™ Python3 Quick Start

Contents

Getting Started

This quick start guide provides basic instructions for writing TIBCO eFTL applications in Python 3 for TIBCO Cloud™ Messaging.

Building and running samples

Follow the steps below to build and run the Python 3 samples:

  • Unzip eftl-python3-samples.zip
  • (Optional) To preserve your default Python 3 environment use a virtual environment:
    • Create a virtual environment: python3 -m venv eftl-python3-samples
    • Activate virtual environment: source eftl-python3-samples/bin/activate
  • Change directories into eftl-python3-samples/
  • Upgrade pip: python3 -m pip install --upgrade pip
  • Install requirements: python3 -m pip install -r requirements.txt
  • Use -f option to specify the configuration file.
  • Run sample: python3 eftl_consumer.py -f <path-to>/tcm-config.yaml

Description of sample applications

Producer

The producer demonstrates connecting an eFTL Python 3 application to Cloud Messaging and publishing eFTL messages:

usage: eftl_producer.py [-h] [-f CONFIG_YAML] [-c COUNT] [-r RATE] [-id CLIENT_ID] [-dest DEST]

optional arguments:
  -h, --help      show this help message and exit
  -f CONFIG_YAML  the path to a configuration yaml (default: tcm-config.yaml)
  -c COUNT        the number of messages to send before exiting (default: infinite)
  -r RATE         messages per second (default: 1)
  -id CLIENT_ID   client identifier (default: eftl_producer)
  -dest DEST      destination on which to publish messages (default: sample)

Consumer

The consumer demonstrates connecting an eFTL Python 3 application to Cloud Messaging, creating a subscription, and receiving eFTL messages:

usage: eftl_consumer.py [-h] [-f CONFIG_YAML] [-c COUNT] [-id CLIENT_ID] [-dest DEST] [-durable-name DURABLE_NAME] [-durable-type DURABLE_TYPE] [-client-ack]

optional arguments:
  -h, --help            show this help message and exit
  -f CONFIG_YAML        the path to a configuration yaml (default: tcm-config.yaml)
  -c COUNT              the number of messages to receive before exiting (default: infinite)
  -id CLIENT_ID         client identifier (default: eftl_consumer)
  -dest DEST            destination on which to publish messages (default: sample)
  -durable-name DURABLE_NAME
                        durable name (default: eftl_consumer)
  -durable-type DURABLE_TYPE
                        one of default, shared or last-value durable types
  -client-ack           enable explicit client acknowledgements

Run the consumer and producer at the same time to demonstrate real-time messaging. To demonstrate persistence, stop the consumer, run the producer, and restart the consumer using the same durable name. For default durables, you will also need to supply the same client id each time.

Using the eFTL SDK

  • Include the line from messaging.eftl.connection import Eftl in your source file.
  • Declare an instance of the eFTL class: eFTL = Eftl()

Connecting to TIBCO Cloud Messaging

The client configuration file contains all the information client applications need to securely connect to TIBCO Cloud Messaging. Generate the client configuration file using the roles REST API or user interface. Generate as many configuration files as needed for each Role.

Note: TIBCO Cloud Messaging samples require a client configuration file to run.

Client Identifiers

You must provide a unique identifier for your client if you want it to receive any messages missed while disconnected. Only one application can connect with a given client id at any given time. If a second application connects with a client id already in use by another application, the first application will disconnect.

Connection Example

connection = await eFTL.connect(url=<eftl_url>,
                                user="ignored", # the user field is ignored by TCM
                                password=<tcm_authentication_key>,
                                client_id=<client_id>,
                                trust_all=True,
                                event_loop=loop,
                                on_connect=on_connect,
                                on_reconnect=on_reconnect,
                                on_disconnect=on_disconnect,
                                on_error=on_error)

on_connect callback

The on_connect callback is invoked once the connection to TIBCO Cloud Messaging is established. The Connection callback passed to the on_connect callback can be used for subscribing to messages and publishing messages.

on_disconnect callback

If the connection cannot be established, or is lost, the on_disconnect callback is invoked.

on_reconnect callback

The on_reconnect callback is invoked when the client successfully reconnects to TIBCO Cloud Messaging.

on_error callback

The on_error callback is invoked when TIBCO Cloud Messaging sends an error to the client.

Publishing Messages

Clients can publish messages after they are connected to TIBCO Cloud Messaging. To publish messages, use the connection returned in the on_connect callback.

sent += 1
msg = connection.create_message()
msg.set_string("type", "hello")
msg.set_string("text", "This is a sample eFTL message")
msg.set_long("long", sent)
msg.set_datetime("time", datetime.datetime.now())

await connection.publish(msg, on_complete=on_publish_complete, on_error=on_publish_error)

Receiving Messages

After clients are connected to TIBCO Cloud Messaging, they can create one or more subscriptions to receive messages of interest. You can subscribe to messages by matching the message fields of interest. Use the connection returned in the on_connect callback to register subscriptions.

matcher = "{\"_dest\":\"%s\"}" % args.dest
await connection.subscribe(matcher=matcher,
                            ack=args.ack_mode,
                            durable=args.durable,
                            on_subscribe=on_subscribe,
                            on_message=on_message,
                            on_error=on_subscribe_error)

Matcher field

The matcher field specifies the messages that are to be received by matching their content. In this case, the subscription receives all published messages containing a field named _dest whose value is specified by the -destination option.

Durable field

The durable field is the unique subscription name used by TIBCO Cloud Messaging to store messages for the client when the client is not connected.

on_subscribe callback

The on_subscribe callback is invoked when the client successfully subscribes.

on_message callback

The on_message callback is invoked when the content of a published message matches the subscription’s matcher.

on_error callback

The on_error callback is invoked when an error occurs while registering the subscription, typically because of an invalid matcher or invalid durable.