Search Results

TIBCO eFTL™ Go Quick Start

Contents

Getting Started

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

Building and running samples

Follow the steps below to build and run the Go samples. The Go samples are implemented as a Go module. Dependencies are defined in the included go.mod files.

Linux and macOS

  • Unzip eftl-go-samples.zip
  • Change into module directory: cd eftl-go-samples/eftl
  • Set GOBIN: export GOBIN=$PWD/bin
  • Generate vendor directory: go mod tidy then go mod vendor
  • Build and install binaries: go install tibco.com/eftl...
  • Use -f option to specify the configuration file.
  • Run sample: $GOBIN/eftl_consumer -f <path-to>\tcm-config.yaml

Windows

  • Unzip eftl-go-samples.zip
  • Change into module directory: cd eftl-go-samples\eftl
  • Set GOBIN: set GOBIN=%CD%\bin
  • Generate vendor directory: go mod tidy then go mod vendor
  • Build and install binaries: go install tibco.com/eftl...
  • Use -f option to specify the configuration file
  • Run sample: %GOBIN%\eftl_consumer -f <path-to>\tcm-config.yaml

Description of sample applications

Producer

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

Usage eftl_producer:
  -c int
    	the number of messages to send before exiting (default -1)
  -dest string
    	destination on which to publish messages (default "sample")
  -f string
    	the path to a configuration yaml (default "tcm-config.yaml")
  -i duration
    	the duration between sends, e.g. 500ms, 1s, etc. (default 1s)
  -id string
    	client identifier (default "eftl_producer")
  -t duration
    	duration before timeout, e.g. 1h, 5m, 10s, etc.

Consumer

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

Usage of eftl_consumer:
  -c int
    	the number of messages to receive before exiting (default -1)
  -client-ack
    	enable explicit client acknowledgements
  -dest string
    	destination on which to receive messages (default "sample")
  -durable-name string
    	durable name (default "eftl_consumer")
  -durable-type string
    	durable type must be one of default, shared, or last-value (default "default")
  -f string
    	the path to a configuration yaml (default "tcm-config.yaml")
  -id string
    	client identifier (default "")
  -t duration
    	duration before timeout, e.g. 1h, 5m, 10s, etc.

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

For Go programs, include the eFTL client Go library: import "tibco.com/eftl"

Install Dependencies

You must also download and install the WebSockets and YAML packages:

go get github.com/gorilla/websocket
go get gopkg.in/yaml.v3`

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

// Create connection options
opts := &eftl.Options{
   Password: "<tcm_authentication_key>",
   ClientID: "abc123",
}

// Create channel on which to receive connection errors
errChan := make(chan error, 1)

// Connect to TIBCO Cloud Messaging
conn, err := eftl.Connect("<eftl_url>", opts, errChan)
if err != nil {
   log.Println("connect failed: ", err)
}

// Disconnect from TIBCO Cloud Messaging when done
defer conn.Disconnect()

// listen for connection errors
for err := range errChan {
    log.Println("connection error: ", err)
}

Publishing Messages

After clients are connected to TIBCO Cloud Messaging, they can publish messages. To publish messages, use the connection returned by the Connect method.

// Publish a message to TIBCO Cloud Messaging
// Fields and arrays of type string, numeric, date, and sub-messages are used in messages.
err := conn.Publish(eftl.Message{
   "event": "hello",
   "text": "Hello, World!",
});
if err != nil {
   log.Println("publish failed: ", err)
}

Receiving Messages

After the 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 by the Connect method to register subscriptions.

// Channel on which messages are received
msgChan := make(chan eftl.Message, 100)

// Create a subscription in TIBCO Cloud Messaging
//
// This subscription matches all published messages that contain a
// field named `event` with a value of `hello`
//
// This subscription also sets the durable name to "hello" which allows
// the client to receive messages that were published while disconnected
sub, err := conn.Subscribe("{\"event\":\"hello\"}", "hello", msgChan)
if err != nil {
   log.Println("subscribe failed: ", err)
}

// Unsubscribe from messages when done
defer conn.Unsubscribe(sub)

// Listen for messages
for msg := range msgChan {
   log.Println("received message: ", msg)
}

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 event whose value is hello.

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.