development tibco eftl software release 6...tibco messaging - community edition is ideal for getting...

TIBCO eFTL™

DevelopmentSoftware Release 6.3December 2019

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (ORPROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THEEMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANYOTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDERSEPARATE SOFTWARE LICENSE TERMS AND IS NOT PART OF A TIBCO PRODUCT. AS SUCH,THESE SOFTWARE ITEMS ARE NOT COVERED BY THE TERMS OF YOUR AGREEMENT WITHTIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES,AND INDEMNITIES. DOWNLOAD AND USE OF THESE ITEMS IS SOLELY AT YOUR OWNDISCRETION AND SUBJECT TO THE LICENSE TERMS APPLICABLE TO THEM. BY PROCEEDINGTO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THEFOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.

This document is subject to U.S. and international copyright laws and treaties. No part of thisdocument may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, the TIBCO logo, the TIBCO O logo, TIB, Information Bus, eFTL, FTL, and Rendezvous areeither registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or othercountries.

Java and all Java based trademarks and logos are trademarks or registered trademarks of Oracle and/orits affiliates.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

This software may be available on multiple operating systems. However, not all operating systemplatforms for a specific software version are released at the same time. Please see the readme.txt file forthe availability of this software version on a specific operating system platform.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer toTIBCO's Virtual Patent Marking document (https://www.tibco.com/patents) for details.

2

TIBCO eFTL™ Development

https://www.tibco.com/patents

Copyright © 2013–2019 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

3


Contents

About this Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

API Reference Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Client Platform Support and Requirements Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Java Programmer's Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Android Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

.NET Framework and .NET Core Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

iOS and Objective C Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

JavaScript for Browsers Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

JavaScript for Node.js Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

C Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Restrictions on Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Reserved Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Length Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Programming an eFTL Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Listeners and Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

FTL Last-Value Durables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

FTL Key/Value Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Interaction with EMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

eFTL Channel REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Channel API Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

POST chan_name/v1/publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

POST /chan_name/v1/subscribe/dur_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

GET chan_name/v1/subscribe/dur_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

DELETE chan_name/v1/subscribe/dur_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

POST chan_name/kvmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

GET chan_name/kvmap/map_name/key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

DELETE chan_name/kvmap/map_name/key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Push Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Programming Push Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Coordination Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4


About this Product

TIBCO® is proud to announce the latest release of TIBCO eFTL ™ software.

This release is the latest in a long history of TIBCO products that leverage the power of InformationBus® technology to enable truly event-driven IT environments. To find out more about how TIBCOeFTL software and other TIBCO products are powered by TIB® technology, please visit us at www.tibco.com.

TIBCO eFTL software is part of TIBCO® Messaging.

Product Editions

TIBCO Messaging is available in a community edition and an enterprise edition.

TIBCO Messaging - Community Edition is ideal for getting started with TIBCO Messaging, forimplementing application projects (including proof of concept efforts), for testing, and for deployingapplications in a production environment. Although the community license limits the number ofproduction processes, you can easily upgrade to the enterprise edition as your use of TIBCO Messagingexpands.

The community edition is available free of charge. It is a full installation of the TIBCO Messagingsoftware, with the following limitations and exclusions:

● Users may run up to 100 application instances or 1000 web/mobile instances in a productionenvironment.

● Users do not have access to TIBCO Support, but you can use TIBCO Community as a resource(https://community.tibco.com).

TIBCO Messaging - Enterprise Edition is ideal for all application development projects, and fordeploying and managing applications in an enterprise production environment. It includes all featurespresented in this documentation set, as well as access to TIBCO Support.

Bundling

The enterprise edition of TIBCO ActiveSpaces® use the enterprise edition of TIBCO Messaging andinclude a license for it. The community editions of those related products are compatible with both theenterprise and community editions of TIBCO Messaging.

5


HTTP://WWW.TIBCO.COM/

https://community.tibco.com

TIBCO Documentation and Support Services

How to Access TIBCO Documentation

Documentation for TIBCO products is available on the TIBCO Product Documentation website, mainlyin HTML and PDF formats.

The TIBCO Product Documentation website is updated frequently and is more current than any otherdocumentation included with the product. To access the latest documentation, visit https://docs.tibco.com.

Product-Specific Documentation

The following documents for this product can be found on the TIBCO Documentation site:

● TIBCO eFTL Concepts

● TIBCO eFTL Administration

● TIBCO eFTL Development

● TIBCO eFTL Installation

● TIBCO eFTL API Reference (HTML only)

● TIBCO eFTL Release Notes

Additional information resources can be found, after file extraction, in the samples directory. Theseinclude a Quick Start Guide, tutorials, readme.txt files, and sample applications.

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

● For an overview of TIBCO Support, visit http://www.tibco.com/services/support.

● For accessing the Support Knowledge Base and getting personalized content about products you areinterested in, visit the TIBCO Support portal at https://support.tibco.com.

● For creating a Support case, you must have a valid maintenance or support contract with TIBCO.You also need a user name and password to log in to https://support.tibco.com. If you do not have auser name, you can request one by clicking Register on the website.

How to Join TIBCO Community

TIBCO Community is the official channel for TIBCO customers, partners, and employee subject matterexperts to share and access their collective experience. TIBCO Community offers access to Q&A forums,product wikis, and best practices. It also offers access to extensions, adapters, solution accelerators, andtools that extend and enable customers to gain full value from TIBCO products. In addition, users cansubmit and vote on feature requests from within the TIBCO Ideas Portal. For a free registration, go to https://community.tibco.com.

6


https://docs.tibco.com

https://docs.tibco.com

http://www.tibco.com/services/support

https://support.tibco.com

https://support.tibco.com

https://ideas.tibco.com/

https://community.tibco.com

API Overview

The TIBCO eFTL API is a compact version of the TIBCO FTL API, small enough for mobile applicationsand browser applications. It includes everything you need to exchange messages, and it omitseverything else.

Functionality

Programs use the API for these operations:

● Connecting to an eFTL service

● Publishing messages (one-to-many)

● Subscribing to messages (one-to-many) and filtering with content matchers

● Constructing and unpacking messages

Asynchronous Callback Architecture

API calls return quickly, which reflects a requirement of mobile device applications. All API calls thatdepend on a TIBCO eFTL service are asynchronous. When the service responds, the TIBCO eFTLlibrary invokes a user-defined callback method.

Message Data Types

The field data types within eFTL messages are similar to those in FTL messages, except that eFTLmessages do not support the opaque and inbox types.

However, the field data types within eFTL messages are not similar to those in EMS messages. Fordetails of message translation, see “Message Translation: TIBCO eFTL and TIBCO EMS” in TIBCO eFTLConcepts.

7


API Reference Documentation

TIBCO eFTL API reference documentation is available only in HTML format.

The documentation set includes API reference resources for each supported programming language orframework.

8


Sample Programs

Each software development kit (SDK) includes sample programs for the corresponding developmentplatform. After extracting the SDK from its archive file, you can locate the samples directory at eftl/version_number/samples/platform.

9


Client Platform Support and Requirements Reference

TIBCO eFTL software supports these platforms for application development and deployment.

For platform version requirements, see the file readme.txt.

Client Platform API Support

Android Java API

iOS (Apple) Objective C API

Web Browsers JavaScript API

Node.js JavaScript API

Windows (Microsoft) .NET API

C

Golang

Linux

macOS

C

Golang

10


Java Programmer's Checklist

When developing eFTL applications in Java for platforms other than Android, remember these steps.

Environment

● JDK 1.8

Code

Ensure that the following library is in the CLASSPATH:

● TIBCO_HOME/eftl/version/sdks/java/lib/tibeftl.jar

Compile

None.

Run

● Ensure that the TIBCO FTL server is running, and provides a TIBCO eFTL service.

● If your application communicates over EMS channels, ensure that the TIBCO EMS server is running,and that each TIBCO eFTL service can connect to it.

● If your application uses FTL durables, ensure that persistence stores are configured, running, andreachable.

● Ensure that each eFTL client can connect to a TIBCO eFTL service.

11


Android Programmer’s Checklist

When developing eFTL applications for Android platforms, remember these steps.

Environment

● Use the most recent release of Android Studio.

Code

Add the following library to your project:

● TIBCO_HOME/eftl/version/sdks/java/lib/tibeftl.jar

Compile

None.

Run





12


.NET Framework and .NET Core Programmer’s Checklist

When developing eFTL applications for Windows or for Windows tablet devices, use this checklist.

Environment

Set up the environment for .NET Framework 4.7.2. Ensure that it is current with the latest updates.

TIBCO eFTL classes require Microsoft Visual Studio 2017 for development.

TIBCO eFTL software requires 64-bit support (in the operating system and .NET Framework/Core).

Install .NET Framework/Core first, before installing TIBCO eFTL software. If the .NET Framework/Coreis present, then installing TIBCO eFTL automatically registers the appropriate assemblies in Microsoft’sgeneral assembly cache (GAC).

Use the setup script in the samples directory to set environment variables.

For .NET Framework, ensure that the PATH environment variable includes the .NET Framework SDK(%windir%\Microsoft.NET\Framework64\dotnet_version).

For .NET Core, ensure that the dotnet driver version 2.1 is installed.

Code

Import this assembly: TIBCO_HOME/eftl/version/sdk/dotnet/bin/TIBCO.EFTL.dll

Compile

TIBCO eFTL classes require .NET Framework 4.7.2.

To use the TIBCO EFTL classes, programs must reference the assembly TIBCO.EFTL. If the .NETframework is properly installed, then installing TIBCO EFTL registers the assembly with the Windowsgeneral assembly cache (GAC).

The assembly TIBCO.EFTL is compiled with platform target x64. You must compile applications thatuse TIBCO.EFTL accordingly.

Run

● TIBCO FTL classes require .NET Framework 4.7.2.

● You must arrange appropriate .NET security for your applications. The base library callsunmanaged code, and requires full trust.





13


iOS and Objective C Programmer’s Checklist

When developing eFTL applications for Apple iOS platforms, remember these steps.

Environment

● Add TIBCO_HOME/eftl/version/sdk/ios/eFTL.framework to your project.

● Add these Xcode libraries and frameworks to the build phases of your project:

— libicucore.tbd

— CFNetwork.framework

— Security.framework

● Set the Other Linker Flags build setting to include -ObjC.

Code

● Import the TIBCO eFTL header file, eftl/eftl.h, which in turn includes other header files.

Compile

None.

Run





14


JavaScript for Browsers Programmer’s Checklist

When developing eFTL JavaScript programs for browser platforms, remember these steps.

Code

JavaScript programs must reference the TIBCO eFTL library package, TIBCO_HOME/eftl/version/sdks/javascript/lib/eftl.js.

Run





● If you run a secure eFTL service, which listens using wss protocol, ensure that the client browsertrusts the certificate of the TIBCO eFTL service; see “Clients Trust the eFTL Service” in TIBCO eFTLAdministration.

● The Compatibility View feature of Internet Explorer interferes with correct operation of JavaScriptprograms. Instruct application users to disable this feature.

To disable the Compatibility View feature, click Tools > Compatibility View Settings to open thesettings dialog. Clear all the check boxes.

15


JavaScript for Node.js Programmer’s Checklist

When developing eFTL JavaScript programs for Node.js environments, remember these steps.

Code

● JavaScript programs must require the TIBCO eFTL library package, TIBCO_HOME/eftl/version/sdks/javascript/lib/eftl.js.var eftl = require('eftl')

● If you run a secure eFTL service, which listens using wss protocol, the program must register theappropriate certificates that the application trusts. If the program does not register certificates, thenit trusts any certificate. (The JavaScript method that registers certificates applies only when runningin a Node.js environment. It is not effective when running in a browser.)

Run

● eFTL programs require that the WebSocket module is installed in the Node.js environment.

Install it using this command line:npm install ws





● Ensure that the file eftl.js is available in the environment.

16


C Programmer’s Checklist

When developing eFTL applications in C, remember these steps.

The eFTL C API is available as platform-specific binary libraries. It is also available in source form, soyou can compile it for other platforms.

Environment

Use the setup script in the samples directory to set environment variables.

Code

● Include the TIBCO eFTL header file, tib/eftl.h.

Compile

Compile programs with an ANSI-compliant C compiler.

Use the compiler flags in the Makefile in the samples/c/examples directory.

Link

On UNIX platforms, use the linker flags -ltibeftl.

On Windows platforms, link the corresponding C library file, tibeftl.lib.

Run

● On Windows platforms, the PATH variable must include the bin directories to use the DLL files forTIBCO eFTL and TIBCO FTL.

● On UNIX platforms, the LD_LIBRARY_PATH variable must include the lib directories to use thelibrary files for TIBCO eFTL and TIBCO FTL.





17


Restrictions on Names

Names and other literal strings must conform to the restrictions in the following topics.

Reserved NamesAll names that begin with an underscore character (_) are reserved. It is illegal for programs to definefields, endpoints, applications, transports, formats, durables, stores, clusters, or zones with thesereserved names.

You may use the underscore character elsewhere, that is, where it is not the first character of a name.

Length LimitAll names are limited to a maximum length of 256 bytes.

This limit includes names of fields, endpoints, applications, transports, formats, durables, stores,clusters, or zones. It also extends to string values in content matchers.

If you use UTF-8 characters that are larger than one byte, remember that the limit restricts the numberof bytes in the name, rather than the number of characters.

18


Programming an eFTL Application

When programming an eFTL application, use the steps of this task to guide the program structure.

Some programs require only a subset of these structural steps.

Procedure

1. Define Connection CallbacksEvery program must define the four ConnectionListener event methods:

● Connect● Disconnect● Reconnect● Error

2. Define Subscription CallbacksPrograms that subscribe must define the three SubscriptionListener event methods:

● Messages● Subscribe● Error

3. Define completion callbacks.Programs that publish define the two CompletionListener event methods:

● Completion● Error

4. Connect to an TIBCO eFTL Servicea) If the service uses TLS security, the application must register trust in the appropriate certificate.b) Every program must call the connect method to establish a connection.

You may include user name credentials in the url argument. For syntax, see the APIdocumentation. When using the WSS protocol, this information travels encrypted.

5. Sending Messages

Programs that publish must complete both of these substeps.a) Construct outbound messages.b) Call publish the method.

6. Receiving Messages

Programs that subscribe must call the subscribe method.

7. Clean-Up

Consider whether it is appropriate for the program to close subscriptions or durable subscriptions.

Every program must call the disconnect method to disconnect from the eFTL service.

Listeners and CallbacksClient requests to the eFTL service are asynchronous. To ascertain the outcome of a request, clientsmust supply a callback listener.

A send call is a request that the eFTL service send a message for the client. A send call returns before theservice fulfills the request. To receive information about the outcome of the send request, theapplication must supply a completion listener as an argument to the send call.

19


It is good practice to supply a completion listener when using persistence features or when interactingwith an EMS server.

In earlier versions of the TIBCO eFTL API, send calls did not require a completion listener. It is goodpractice to update application programs to supply completion listeners whenever the outcome a sendcall is important to the application.

A subscribe call is a request that the eFTL service subscribe to messages for the client. A subscribe callreturns before the service fulfills the request. To receive messages and information about the status ofthe subscription, the application must supply a subscription listener as an argument to the subscribe call.

A connect call is a request that the eFTL service establish a connection for the client. A connect callreturns before the service fulfills the request. To receive information about the status of the connection,the application must supply a connection listener as an argument to the connect call.

20


Persistence

Your eFTL applications can use the persistence features of either the FTL persistence service or the EMSserver.

Coordination

Persistence depends on proper configuration of the eFTL channel, and of the FTL persistence service orEMS server, corresponding to the channel's message infrastructure. Developers must coordinate withadministrators to agree on the requirements for this configuration. Complete the appropriatecoordination forms together.

Durable Subscriptions

A durable subscription is a subscription that persists even when the application is not running. The FTLpersistence service or the EMS server maintains the durable subscription on behalf of the application.

Unsubscribe

The unsubscribe call deletes the durable subscription. The eFTL service discards all messages that itholds for the subscription.

FTL Persistence

The FTL channel must be configured for persistence. (See "Configuring Persistence for an FTL Channel"in TIBCO eFTL Administration.)

eFTL programs can subscribe to dynamic or static durables of any type: standard, shared, or last-valuedurables.

When you supply a durable name in the subscribe call, the call resolves it to a unique durable name intwo phases:

1. Static If the channel definition includes a static durable mapping, and it maps the durable name to astatic durable in the channel's persistence store, then the result is a subscription to that staticdurable.

Subscriber name mapping is an advanced topic.

2. Dynamic If the first phase did not result in a valid static durable, the subscribe call attempts tocreate and subscribe to a dynamic durable.

● If the call does not specify the durable type property, and the channel definition includes adefault durable template, then the call creates a durable using that template.

● If the call specifies the durable type property, and the channel definition includes a dynamicdurable template corresponding to that type, then the call creates a durable using that template.

The result is a subscription to a dynamic durable with a unique durable name (see the section"Dynamic Durable Names," which follows).

These anomalous situations trigger the subscription listener's error callback:

● You supply a durable name but the FTL channel is not configured for persistence.● The FTL channel is configured for persistence but you do not supply a durable name.● The subscribe call cannot resolve the durable name you supply to either a static or a dynamic

durable.● The channel definition does not specify a dynamic durable template for the durable type of the

subscribe call.

21


See also Last-Value Durables.

EMS Persistence

The EMS server must be configured to support concatenated durable names.

Every subscribe call results in a durable subscription to a concatenated durable name (see the section"Dynamic Durable Names," which follows).

Dynamic Durable Names

For shared durables and last-value durables, the name of the dynamic durable is the durable name thatprogram supplies in the subscribe call.

For standard durables, the client library forms a unique concatenated durable name by prefixing theclient ID string and a period (.) character to the durable name the program supplies in the subscribecall.

Concatenated names must not exceed the maximum name length. See Length Limit.

Client ID

The client ID indicates the particular process instance of the application program that created thedurable subscription. Usually this ID represents either the user of the application or a specific mobiledevice. Two client processes cannot use the same client ID at the same time.

You may supply the client ID in the connect call. For long-term persistence, it is good practice toexplicitly supply a client ID.

If you do not supply a client ID, the connect call assigns a unique client ID. However, such assigned IDstrings can provide only short-term persistence. If the client process disconnects from the eFTL serviceand then reconnects, an assigned ID preserves the durable subscription through that time gap.However, if the application restarts, then the durable subscription is not available.

FTL Last-Value DurablesSubscribing to an FTL last-value durable requires a content matcher.

TIBCO eFTL supports only static last-value durables.

The FTL admininstrator configures the dynamic durable template.

In the client program the content matcher in the subscribe call must match a specific string value of thekey field. For example, if the key field is "flight_num", then the content matcher{"flight_num":"954"} subscribes to updates for a specific flight.

FTL Key/Value MapseFTL clients can access FTL key/value maps through a persistent FTL channel.

TIBCO eFTL supports only dynamic key/value maps.

The FTL administrator configures the dynamic map template for the channel.

Client programs can set, get, and remove key/value pairs in the map (see TIBCO eFTL API Reference).

REST clients can set, get, and remove key/value pairs in the map (see POST chan_name/kvmap and thetopics that follow it).

22


Interaction with EMS

When developing eFTL applications that could communicate over EMS channels, use the _dest fieldfor addressing.

The _dest field contains a string that corresponds to a JMS topic name; for example NYSE.IBM. Topublish or subscribe to an EMS queue, prefix the queue name with QUEUE:; for exampleQUEUE:NYSE.IBM. EMS channels of the eFTL service translate between these two representations.

● Code eFTL publishers to set the _dest field when constructing messages.

● Code eFTL subscriber content matchers to match against the _dest field, and not against any otherfields; for example, {"_dest":"NYSE.IBM"}.

For background information, see “Message Translation: TIBCO eFTL and TIBCO EMS” in TIBCO eFTLConcepts.

23


eFTL Channel REST API

The eFTL channel REST API offers a lightweight alternative for publish, subscribe, and key/value mapoperations. You can use it to publish messages to a channel, to create durable subscribers on a channel,and to get messages from durable subscribers. You can use it to set, get, and remove key/value pairs ina map.

Send REST requests to the FTL server, which redirects them to the eFTL service.

This API can access FTL channels and EMS channels.

With proper authorization, you can publish to any channel.

In contrast, you can subscribe only on channels configured for persistence. The reason is that client andthe eFTL service do not maintain a connection. It is as if every subscribe API request comes from a newclient. The durable subscription paradigm provides continuity for this transient client model.

You can use key/value map operations only on channels configured for persistence with a dynamicmap template.

Response Codes

An HTTP response code in the 200 family indicates asuccessful operation. Other codes indicate errors.

Channel API SecurityThe eFTL service can authenticate channel REST requests using either basic or token authentication. Forencryption, use HTTPS.

In a series of interactions, use HTTP basic authentication in the first request. If that authenticationsucceeds, the response includes an authentication token you can use in subsequent requests.

Clients must handle error response 401, unauthorized. This error could indicate an expired token. Acient with an expired token can obtain a new token by sending another request with basicauthentication.

Basic Authentication

For HTTP basic authentication, supply a user name and password in the request, for example:Authorization: Basic <base64(user_name:password)>

curl -u user_name:password http://host:port/chan_name/v1/REST_request

Token Authentication

For token authentication, extract the token from the HTTP header X-Auth-Token of a valid response,and supply it in subsequent requests, for example:X-Auth-Token: token

curl -H "X-Auth-Token: token" http://host:port/chan_name/v1/REST_request

POST chan_name/v1/publishThe web method POST chan_name/v1/publish publishes a message on a specific channel. The requestbody is the message to publish (in JSON format).

chan_name in the URI is the channel name.

Example Requestscurl http://host:port/chan_name/v1/publish -d '\{"name":"joe","id":123\}'

24


Publishing on EMS Channels

When publishing on an EMS channel, you must supply the topic name as the value of the _dest field inthe argument of the request. For example:curl http://host:port/chan_name/v1/publish -d '\{"_dest":"symbol.amzn","text":"sell"\}'

POST /chan_name/v1/subscribe/dur_nameThe web method POST chan_name/v1/subscribe/dur_name creates a durable subscription on aspecific channel. The request body specifies the content matcher in JSON format.

● chan_name in the URI is the channel name.

● dur_name in the URI is the durable name for the subscription.

The channel definition must configure FTL or EMS persistence.

HTTP Parameters

Syntax Description

type=durable_type Optional.

This parameter selects for one of an FTLchannel's dynamic durable templates.

You can specify a durable type, either shared orlast-value.When absent, the channel creates the newdurable using its default durable template.

key=key_field_name Required when the type is last-value.

Specify the key field of a last value durable. Thekey field must be present in the subscription'scontent matcher.

Example Requestscurl http://host:port/chan_name/v1/subscribe/dur_name -d '{"color":"blue"}'

curl http://host:port/chan_name/v1/subscribe/dur_name?type=shared -d '{"db":"db4"}'

curl http://host:port/chan_name/v1/subscribe/dur_name?type=last-value&key=symbol -d '{"symbol":"amzn"}'

GET chan_name/v1/subscribe/dur_nameThe web method GET chan_name/v1/subscribe/dur_name gets zero or more messages from a specificdurable subscription on a specific channel.


● dur_name in the URI is the durable name of the subscription.

One common usage pattern would be to repeat this request until the response array is empty, indicatingthat no messages remain in the durable.

25


HTTP Parameters

Syntax Description

timeout=wait_time Optional.

When present, the request waits this interval (inseconds) for messages to become available. If thevalue is less than 1, the request waits theminimum time of 1 second.

When absent, the request waits the defaultinterval.

matcher=json_content_matcher Required for last-value durables.

Specify a content matcher that includes the keyfield of a last-value durable.

type=durable_type Required if the durable subscription wasoriginally created using the durable typeparameter (via POST REST request).

If required, specify a durable type of eithershared or last-value.

Example Requestscurl http://host:port/chan_name/v1/subscribe/dur_name?timeout=10

curl http://host:port/chan_name/v1/subscribe/lv_dur_name?matcher='\{"symbol":"amzn"\}'

Example Response

{ "messages":[ { "symbol":"amzn", "bid":1732 } ]}

Subscribing on EMS Channels

When subscribing on an EMS channel, you must supply the topic name in the matcher parameter of therequest. For example:curl http://host:port/chan_name/v1/subscribe/lv_dur_name?matcher='\{"_dest":"symbol.amzn"\}'

DELETE chan_name/v1/subscribe/dur_nameThe web method DELETE chan_name/v1/subscribe/dur_name deletes a specific durable subscriptionon a specific channel.


● dur_name in the URI is the durable name of the subscription.

26


Example Requestscurl -X DELETE http://host:port/chan_name/v1/subscribe/dur_name

POST chan_name/kvmapThe web method POST chan_name/v1/kvmap/map_name/key sets the value of a key within a specificmap on a specific channel. The request body is the value message (in JSON format).


map_name in the URI is the map name.

key in the URI is the key string.

Example Requestscurl http://host:port/chan_name/v1/kvmap/personnel/joe -d '{"name":"Joe Williams","id":123}'

GET chan_name/kvmap/map_name/keyThe web method GET chan_name/v1/kvmap/map_name/key gets the value of a key within a specificmap on a specific channel.




Example Requestscurl http://host:port/chan_name/v1/kvmap/personnel/joe

Example Response

{ "value":{ "price":154.80 }}

DELETE chan_name/kvmap/map_name/keyThe web method GET chan_name/v1/kvmap/map_name/key deletes a key/value pair from a specificmap on a specific channel.




Example Requestscurl -X DELETE http://host:port/chan_name/v1/kvmap/personnel/joe

27


Push Notifications

Mobile devices can receive push notifications that inbound messages are waiting at the eFTL service.

If push notifications are enabled, the eFTL service retains the client's subscriptions, even when the clientapplication is disconnected from the eFTL service. When the application reconnects, the service deliversthe backlogged messages to the application.

If a message arrives while the client is disconnected, the eFTL service requests that the platformvendor's push notification service (PNS) send a silent notification to the device. Upon receiving anotification, the device runs the application's notification callback. (Silent notifications do not implicitlydisplay badges or text to the device user. However, your notification callback can explicitly implementthese or other appropriate behaviors.)

Notifications are available through the following push notification services:

● Apple Push Notification Service (APNS) for iOS platforms

Push notifications are an optional feature of TIBCO eFTL software.

To use push notifications, the developer must code the application appropriately, and the administratormust configure the eFTL service appropriately. (See "Configuring Push Notifications" in TIBCO eFTLAdministration.)

Programming Push NotificationsTo implement push notifications for an eFTL application, complete these steps in your mobileapplication code.

Prerequisites

● Your application runs on a mobile platform that supports push notification.

● Your application already has an ID and authentication with the platform vendor's push notificationservice (PNS).

Procedure

1. Code a notification callback.Conform to the requirements of the vendor's push notification service.

2. Request a notification token from the PNS.The token uniquely represents your application running on a specific mobile device. The token alsorepresents your application within the device's operating system.

3. Supply the notification token as a property in the eFTL client connect call.

4. Create eFTL sbuscriptions as usual.

5. Disconnect from the eFTL service when the application exits or transitions to a background state.While the client is disconnected, the eFTL service maintains the client's eFTL subscriptions, andsends a push notification whenever an eFTL message arrives.

6. Reconnect to the eFTL service when the application transitions to a foreground state.The eFTL service automatically delivers any eFTL messages that are waiting for the client.

28


Coordination Forms

Coordination forms help developers and administrators to agree upon application details and todocument those details.

You can duplicate these PDF forms, renaming the copies, and complete them online. Alternatively, youcan print them and complete them on paper.

● TIBCO eFTL Application Coordination Form

● TIBCO eFTL EMS Channel Coordination Form

● TIBCO eFTL FTL Channel Coordination Form

29


https://docs.tibco.com/pub/eftl/6.3.0/doc/pdf/TIBCO_eFTL_Application_Coordination_Form.pdf

https://docs.tibco.com/pub/eftl/6.3.0/doc/pdf/TIBCO_eFTL_EMS_Channel_Coordination_Form.pdf

https://docs.tibco.com/pub/eftl/6.3.0/doc/pdf/TIBCO_eFTL_FTL_Channel_Coordination_Form.pdf

development tibco eftl software release 6...tibco messaging - community edition is ideal for getting...

Documents