TIBCO FTL Development ® Software Release 4.3

TIBCO FTL Development ® Software Release 4.3
TIBCO FTL®
Development
Software Release 4.3
November 2015
Two-Second Advantage®
2
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH
EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY
(OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE
EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY
OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND
CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED
SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE
CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD
OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)
OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER
LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE
SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND
YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE
BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright laws
and treaties. No part of this document may be reproduced in any form without the written
authorization of TIBCO Software Inc.
TIBCO, Two-Second Advantage, TIB, Information Bus, eFTL and Rendezvous are either registered
trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.
Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise
Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of
Oracle Corporation in the U.S. and other countries.
All other product and company names and marks mentioned in this document are the property of their
respective owners and are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT
ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED
AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE
VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL
ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE
CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO
SOFTWARE 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 OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,
INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
Copyright © 2010–2015 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
TIBCO FTL® Development
3
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About this Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Brief Definitions of Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Messaging Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Infrastructure Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Administrative Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Information for Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
API Reference Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Coordination Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
C Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Java Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
.NET Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Restrictions on Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Reserved Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Length Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
IPv4 and IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Application Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Structuring Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Application Instance Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Callbacks and Recursive Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Inline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Request and Reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Recovery of a Disabled Process Restart versus Reopen the Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Clean-Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Consolidation with Loose Coupling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Abilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Endpoints and Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Send: Blocking versus Non-Blocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message Objects in Program Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message Origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Message Mutability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
TIBCO FTL® Development
4
Copy of a Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Messages and Thread-Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Field Values and Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Field Data Type Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Storage of Field Values within Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Formats: Managed, Built-In, and Dynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Format Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Flexibility in Formats and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Field Access: Names and References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Reusing Message Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Built-In Formats Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Opaque Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Keyed Opaque Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
String Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
DateTime Values Printable String Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Inbound Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Content Matchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Match String Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Match Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Content Matcher Performance and Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Subscriber Interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Inline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Callback Restrictions with Inline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Transport Restrictions with Inline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Realm Server Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Realm Server Connect Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Operation of the Realm Server Connect Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Trust Properties of the Realm Connect Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Trust File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Update and Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Trace Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Tuning the Log Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Log Level Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Log Element Tags Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Log Output Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Log Content and Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
TIBCO FTL® Development
5
Advisory Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Advisory Message Common Fields Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Subscribing to Advisory Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Advisory Messages Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DATALOSS FAILOVER_LOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
DATALOSS SENDER_DISCARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
DATALOSS QUEUE_LIMIT_EXCEEDED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
DATALOSS INCOMPLETE_MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
DATALOSS TPORT_DATALOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
DATALOSS RECONNECT_LOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
DATALOSS STORE_DISCARD_DATALOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
DATALOSS UPSTREAM_LOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
DATALOSS DIRECT_SUB_LOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
ORDINAL_UPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
GROUP_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
RESOURCE_AVAILABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
RESOURCE_UNAVAILABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
RETRANSMISSION RETRANSMISSION_REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
RETRANSMISSION RETRANSMISSION_SENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
RETRANSMISSION RETRANSMISSION_SUPPRESSED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
SUBSCRIBER_FORCE_CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
LOCK_LOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Notifications Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
CLIENT_DISABLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Groups of Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Introduction to Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Simple Fault Tolerance with Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Groups with More than Two Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Groups Principles of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Group Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Group Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Interactions within a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Side Effects of Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Techniques for Programming with Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Program Structure for Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Activation Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Group Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Group Observer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
TIBCO FTL® Development
6
Programmer’s Checklist Addenda for Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Persistence: Stores and Durables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Purposes of Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Basic Definitions for Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Durable Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Standard Durable Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Shared Durable Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Last-Value Durable Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Acknowledgment of Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Message Delivery Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Maximum Message Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Programmer’s Checklist Addenda for Stores and Durables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Key/Value Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Direct Publishers and Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Use Cases for Direct Publishers and Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Programming with Direct Publishers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Programming with Direct Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Multithreading with Direct Publishers and Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Multiple Direct Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Package Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Directory Structure Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Sample Programs Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
TIBCO FTL® Development
7
Figures
Illegal Inline Queue, Simple Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Illegal Inline Queue, Hidden Violation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Legal Inline Queue, Separate Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Legal Inline Queue, Single Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
TIBCO FTL® Development
8
About this Product
TIBCO® is proud to announce the latest release of TIBCO FTL® software.
This release is the latest in a long history of TIBCO products that leverage the power of Information
Bus® technology to enable truly event-driven IT environments. To find out more about how TIBCO
FTL software and other TIBCO products are powered by TIB® technology, please visit us at
www.tibco.com.
TIBCO FTL® Development
9
TIBCO Documentation and Support Services
Documentation for this and other TIBCO products is available on the TIBCO Documentation site:
https://docs.tibco.com
Documentation on the TIBCO Documentation site is updated more frequently than any documentation
that might be included with the product. To ensure that you are accessing the latest available help
topics, please visit https://docs.tibco.com.
Product-Specific Documentation
Documentation for TIBCO products is not bundled with the software. Instead, it is available on the
TIBCO Documentation site. To access the documentation web page for this product from a local
software installation, open the following file:
TIBCO_HOME/release_notes/TIB_ftl_4.3.0_docinfo.html
TIBCO_HOME is the top-level directory in which TIBCO products are installed.
●
On Windows platforms, the default TIBCO_HOME is C:\tibco.
●
On UNIX platforms, the default TIBCO_HOME is /opt/tibco.
The following documents for this product can be found on the TIBCO Documentation site.
®
TIBCO FTL Documentation Set
●
TIBCO FTL Concepts Everyone reads this booklet first, for an intuitive introduction to the
fundamental concepts of FTL software.
●
TIBCO FTL Development Application developers and architects read this manual to understand
concepts relevant in any supported programming language.
●
TIBCO FTL API Reference Application developers use this HTML documentation to learn the details
of the FTL API in specific programming languages.
●
TIBCO FTL Administration Administrators read this manual to learn how to use the realm server
and its interfaces, and how to define a realm. Developers can also benefit from understanding FTL
software from an administrator’s perspective.
●
TIBCO FTL Installation Read this manual before installing or uninstalling the product.
●
TIBCO FTL Glossary The glossary contains brief definitions of key terms used in all other parts of
the documentation set.
●
TIBCO FTL Release Notes Read the release notes for a list of new and changed features. This
document also contains lists of known issues and closed issues for this release.
TIBCO eFTL™ Documentation Set
TIBCO eFTL software is documented separately. Administrators use the FTL realm server GUI to
configure and monitor the eFTL service. For information about these GUI pages, see the documentation
set for TIBCO eFTL software.
How to Contact TIBCO Support
For comments or problems with this manual or the software it addresses, contact TIBCO Support:
●
For an overview of TIBCO Support, and information about getting started with TIBCO Support,
visit this site:
http://www.tibco.com/services/support
TIBCO FTL® Development
10
●
If you already have a valid maintenance or support contract, visit this site:
https://support.tibco.com
Entry to this site requires a user name and password. If you do not have a user name, you can
request one.
How to Join TIBCOmmunity
TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a
place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers
forums, blogs, and access to a variety of resources. To register, go to the following web address:
https://www.tibcommunity.com
TIBCO FTL® Development
11
Product Overview
TIBCO FTL® software is a messaging infrastructure product. It features high speed, structured data
messages, and clearly defined roles for application developers and application administrators. TIBCO
FTL software can achieve low message latency with consistent performance.
Components
TIBCO FTL software comprises these main components.
API Libraries
Developers use APIs in application programs.
Realm Server
Applications obtain operational metadata from the realm server.
Persistence Server
Persistence servers store messages for durable subscribers.
Transport Bridge
Bridges forward messages between two endpoints.
Add-On Products
TIBCO eFTL™ software is sold separately.
TIBCO FTL® Development
12
Brief Definitions of Key Concepts
These brief definitions are reminders of the key concepts of TIBCO FTL software.
For a more intuitive picture of TIBCO FTL software and its concepts, please read the booklet TIBCO
FTL Concepts as your first introduction to this product.
Messaging Concepts
Application programs use TIBCO FTL software to communicate by sending messages to one another.
Programs send messages using publisher objects, and receive messages using subscriber objects.
For low latency, messages travel directly between peer application programs, rather than through a
store-and-forward server.
Messages travel only among application processes. They do not travel from publishers to subscribers
within a process. A process transport is an explicit exception to this rule, as it carries messages within a
process.
Messages and Fields
A message is a structured unit of data. The structure is flexible, and developers tailor the structure to the
needs of the application.
Each message consists of a set of named fields. Each field can contain a value of a specific data type.
One-to-Many Communication
Publishers can send messages using one-to-many communication. These messages can reach potentially
many subscribers.
A subscriber can use a content matcher to receive only those messages in which a particular set of fields
contain specific values.
One-to-One Communication
For efficient one-to-one communication, publishers can also send messages that can reach one specific
inbox subscriber.
An inbox is a data structure that uniquely identifies a specific inbox subscriber.
Inbox subscribers cannot use content matchers. An inbox subscriber receives all messages directed to it.
Infrastructure Concepts
Endpoint
An endpoint is an abstraction that represents a set of publishers and subscribers in communicating
programs. Application architects and developers determine the set of endpoints that an application
requires. Administrators formally define those endpoints. Programs create publisher and subscriber
objects, which instantiate those endpoints.
Endpoint Abilities
From the perspective of a running application instance, each endpoint carries messages in up to four
abilities. Direction and reach are the two dimensions that determine the set of messages that flow along
each ability:
Direction
TIBCO FTL® Development
13
Each ability carries messages in only one of two possible directions: either inbound to the application’s
subscribers, or outbound from the application’s publishers.
Reach
Each ability carries messages from only one kind of send call: either one-to-many or one-to-one,
according to the number of subscribers the message can potentially reach.
Endpoint Abilities Matrix
Inbound
Outbound
One-to-Many
Receive
Send
One-to-One
Receive Inbox
Send Inbox
Transport
A transport is the underlying mechanism that moves message data between endpoint instances in
programs. For example, a shared memory transport can move messages among separate program
processes on a multi-core hardware platform, and a multicast transport can move messages among
programs connected by a network.
Stores and Durables
You can use stores and durables to strengthen message delivery assurance, to apportion message
streams among a set of cooperating subscribers, or to provide last-value availability. For details, see
“Persistence: Stores and Durables”.
Administrative Concepts
A realm is a namespace that defines resources and configurations available to application programs.
(Those resources include endpoints, transports, and formats.)
Administrators use a graphical configuration interface to define the realm, and store that definition in a
realm server. Each process instance of an application program connects to the realm server to download
the part of the realm definition that is relevant to that instance. The TIBCO FTL base library caches that
definition in a realm object. After a program caches the realm definition, it is not necessary to interact
frequently with the realm server. The base library consults the local realm object for information about
endpoints, transports, and message formats. It is not necessary to involve the realm server each time a
program sends or receives a message.
Administrators define transports within the realm. Notice that transports are not visible to application
developers, rather, they are strictly the responsibility of the administrator. From the developer’s
perspective, these details are hidden behind endpoints.
In addition to endpoints, transports, and formats, the realm definition also includes other definitions
and configurations:
●
The term application can refer to an executable program that communicates using TIBCO FTL
software, or to an administrative configuration in the realm (that is, an application definition).
Administrators declare and configure each application, and define the realm resources that process
instances of the application may use.
●
The term application instance can refer either to a process instance of an application program, or to an
administrative configuration in the realm (that is, an application instance definition). Through a
matching algorithm, one such configuration can apply to a set of process instances. When defining a
configuration, administrators can assign different resources to specific sets of process instances,
based on attribute matching, to achieve fine-grained control over communications traffic.
TIBCO FTL® Development
14
When defining an application instance configuration, the administrator must connect each
application endpoint to one or more transports, which actually move message data.
Administrators and developers coordinate the detailed requirements of applications using coordination
forms (see Coordination Forms).
For detailed explanations of these administrative concepts, see TIBCO FTL Administration.
TIBCO FTL® Development
15
Information for Developers
API Reference Documentation
Reference documentation for the TIBCO FTL API is available only in HTML format.
The documentation set includes API reference resources for each supported programming language.
Sample Programs
The directory TIBCO_HOME/ftl/version/samples includes sample programs that you can use as
models for programming, compiling, linking, and running.
For more information, see Sample Programs Reference.
Coordination Forms
Coordination forms help developers and administrators to agree upon application details and to
document those details.
You can duplicate these PDF forms, renaming the copies, and complete them online. Alternatively, you
can print them and complete them on paper.
●
TIBCO FTL Application Coordination Form
●
TIBCO FTL Durable Coordination Form
●
TIBCO FTL Endpoint Coordination Form
●
TIBCO FTL Format Coordination Form
C Programmer’s Checklist
Use this checklist when developing C programs that use the TIBCO FTL API.
When using the group facility, see also Programmer’s Checklist Addenda for Groups.
Environment
Use the setup script in the samples directory to set environment variables.
Code
Include the header file ftl.h (which in turn includes other header files).
Compile
Compile programs with an ANSI-compliant C compiler.
Use the compiler flags in the Makefile in the samples/src/c directory.
Link
On UNIX platforms, use the linker flags -ltib
-ltibutil.
On Windows platforms, link the corresponding C library files, tib.lib and tibutil.lib.
Run
On Windows platforms, the PATH variable must include the bin directory to use the TIBCO FTL DLL
files.
TIBCO FTL® Development
16
On UNIX platforms, the LD_LIBRARY_PATH variable must include the lib directory to use the TIBCO
FTL library files.
Ensure that the TIBCO FTL realm server is running, and that each client process can connect to it.
Java Programmer’s Checklist
Use this checklist when developing programs that use the TIBCO FTL Java API.
When using the group facility, see also Programmer’s Checklist Addenda for Groups.
Environment
The CLASSPATH must include an archive file that contains the TIBCO FTL classes (tibftl.jar from the
lib directory). Use the setup script in the samples directory to set environment variables.
Code
Java programs must import this package:
import com.tibco.ftl.*;
Compile
TIBCO FTL classes require Java 1.8 (or later) 64-bit.
The CLASSPATH must include an archive file that contains the TIBCO FTL classes (tibftl.jar from the
directory).
lib
Run
TIBCO FTL classes requires Java 1.8 (or later) 64-bit.
On Windows platforms, the PATH variable must include the bin directory to use the TIBCO FTL DLL
files.
On Mac OS X platforms, the java.library.path property must include the lib directory to use the
TIBCO FTL library files.
On other UNIX platforms, the LD_LIBRARY_PATH variable must include the lib directory to use the
TIBCO FTL library files.
Ensure that the realm server is running, and that each client process can connect to it.
.NET Programmer’s Checklist
Use this checklist when developing programs that use the TIBCO FTL .NET API.
When using the group facility, see also Programmer’s Checklist Addenda for Groups.
Environment
Set up the environment for .NET Framework 4.0.
TIBCO FTL classes require Microsoft Visual Studio 2010 for development.
TIBCO FTL software requires 64-bit support (in the operating system and .NET Framework).
Use the setup script in the samples directory to set environment variables.
In addition, ensure that the PATH environment variable includes the .NET Framework SDK (%windir%
\Microsoft.NET\Framework64\dotnet_version).
TIBCO FTL® Development
17
Code
To simplify coding, programs can include this statement:
using TIBCO.FTL;
Compile
TIBCO FTL classes require .NET Framework 4.0.
To use the TIBCO FTL classes, programs must reference the assembly TIBCO.FTL, which installs into
the Windows general assembly cache (GAC).
The assembly TIBCO.FTL is compiled with platform target x64. Yyou must compile applications that
use TIBCO.FTL accordingly.
Run
TIBCO FTL classes require .NET Framework 4.0.
To use the TIBCO FTL classes, application processes must access the assembly TIBCO.FTL, which
installs into the Windows general assembly cache (GAC).
The PATH variable must include the bin directory to use the TIBCO FTL DLL files.
You must arrange appropriate .NET security for your applications. The base library calls unmanaged
code, and requires full trust.
Ensure that the realm server is running, and that each client process can connect to it.
Restrictions on Names
Names and other literal strings must conform to the restrictions in the following topics.
Reserved Names
All names that begin with an underscore character (_) are reserved. It is illegal for programs to define
formats, fields, endpoints, and applications with these reserved names.
You may use the underscore character elsewhere, that is, where it is not the first character of a name.
Length Limit
All names are limited to a maximum length of 256 bytes.
This limit includes names of formats, fields, endpoints, and applications. 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 number
of bytes in the name, rather than the number of characters.
TIBCO FTL® Development
18
IPv4 and IPv6
TIBCO FTL software supports both IPv4 and IPv6.
Starting with release 4.2, TIBCO FTL components accept either IPv4 and IPv6 addressing in the
following cases:
●
Realm server GUI fields configuring these transport parameters:
—
RUDP transport: Host field
—
Static TCP transport: Host field
—
Dynamic TCP transport: Subnet
Mask
field
●
Arguments to API calls that specify client connections to realm servers
●
Command line arguments and configuration values that specify realm server client connection
ports, either in a realm server, or in components that connect to a realm server
All other cases accept only IPv4 addressing.
Notation
Specify IPv4 addresses in 4-part dot-decimal notation.
Specify IPv6 addresses in hexadecimal notation, with colon (:) separators, surrounded by square
brackets. Square brackets must be present.
In situations where it is correct and meaningful to specify star (that is, asterisk, *) as a wildcard address,
TIBCO FTL software interprets this wildcard as both an IPv4 wildcard and an IPv6 wildcard. (That is, it
listens on all relevant interfaces in both protocols.)
You can specify the loopback address in IPv4 as either localhost or 127.0.0.1, and in IPv6 as [::1]
or an equivalent notation.
TIBCO FTL® Development
19
Application Design
Structuring Programs
These steps outline the main structural components of most application programs that communicate
using TIBCO FTL.
Procedure
Task A Initializing TIBCO FTL Objects
1. Create a realm object. (C programs must first open the top-level FTL object, and then a realm object.)
Task B Defining Callbacks
2. Define callbacks to process inbound messages.
3. Define callbacks to process advisory messages, as needed.
4. Define callbacks to handle out-of-band notifications.
5. Define callbacks for timer events, timer completion, and queue completion, as needed.
Task C Sending Messages
6. Define methods to construct outbound messages.
7. Instantiate endpoints as publisher objects.
8. Arrange to call the send methods of publishers.
Programs usually call send methods in the context of a data-generation loop, or in the context of
message callbacks, or both. (You can use timer callbacks to implement a data-generation loop.)
Task D Receiving Messages
9. Instantiate endpoints as subscriber objects. (With a durable, supply a subscriber name.)
10. Create event queues, and add each subscriber to an event queue.
11. Start a loop to dispatch event queues.
Task E Recovery and Clean-Up
12. Recover from administrative disable (see Recovery of a Disabled Process Restart versus Reopen the
Realm).
13. Exit cleanly (see Clean-Up).
Application Instance Identifier
Administrators can arrange transports to implement endpoints in different ways, and select among
them at runtime using an application instance identifier.
Application programs can obtain that identifier from the command line, a configuration file, or an
environment variable, and then supply that identifier as a property value in the realm connect call.
Design this ability into all application programs from the outset, even if you do not expect to use it.
Coordinate with administrators to agree upon a standard way for programs to obtain identifiers (see
TIBCO FTL Application Coordination Form).
TIBCO FTL® Development
20
Callbacks and Recursive Dispatch
When designing application callbacks, do not recursively dispatch the same event queue.
Illegal Dispatch of queue A invokes a callback that dispatches queue A.
Legal Dispatch of queue A invokes a callback that dispatches queue B.
Illegal Dispatch of queue A invokes a callback that dispatches queue B, which invokes a callback that
dispatches queue A again.
Inline Mode
Programs that receive time-sensitive messages can use inline mode to favor low latency over high
throughput. Inline mode reduces inbound message latency by consolidating transport I/O and message
callback processing into one thread.
For a complete description of inline mode, its usage, requirements and restrictions, see Inline Mode.
For background information to help you better understand inline mode, read all of Delivery.
Do not use inline mode unless callbacks always return quickly (see Callback Restrictions with Inline
Mode).
When specifying inline mode, programmers and administrators must coordinate to avoid illegal state
exceptions (see Transport Restrictions with Inline Mode, and TIBCO FTL Application Coordination
Form).
Request and Reply
Request/reply is an important communication pattern. Proper use of this pattern places requirements
on the runtime environment.
●
The replying process must be operational before the requesting process sends requests.
●
The transports that carry the requests and replies must have already established operational
communications before either process sends a request or a reply.
Design programs to ensure robust behavior in situations where these requirements are not satisfied.
For example, a program that sends a request and then waits indefinitely for a reply is fragile. If the
replying process is not available, or the transport’s communications are not operating, then the request
message does not reach its intended recipient, and the requesting process does not receive any
information about this failure.
A more robust program would repeat the request at intervals until it receives a reply, or until it exceeds
some reasonable limit.
Recovery of a Disabled Process Restart versus Reopen the Realm
When the realm server disables an application process, the application can recover in one of two ways:
either create a new objects and resume operation, or exit and restart.
The appropriate course of action depends on business factors and program design factors:
●
Process restart cost. The program’s start sequence might be time-consuming, or use resources heavily.
For example, a start sequence might load a large data set into process memory, or establish several
database connections. Seek to avoid that restart cost by re-using the existing context and state.
●
Downtime cost. Business factors might require minimal interruption of an application process.
●
Parallel activities. An application might do some activities which do not require TIBCO FTL
communication. It could be appropriate for those activities to continue non-stop operation while the
program creates a new realm object. For example, a program could control machinery and also send
TIBCO FTL® Development
21
sensor data to other applications. In this example the controller thread must not stop, even if sensor
messages temporarily stop flowing.
●
Simplicity. Unless any of the preceding factors prohibit it, in many cases the simplest and fastest
action is to exit and restart the program.
●
Fresh start. An application’s state could become stale while communications are suspended.
Returning to a valid state might be more complicated or time-consuming than starting fresh.
Disabled Advisory
When the realm server diables an application process, the process receives a CLIENT_DISABLED
advisory. This advisory signals the need for recovery action.
Clean-Up
Design programs to behave appropriately when they exit, and when they create a new realm object and
its associated objects. (For example, creating new realm objects could be a recovery path after the realm
server disables the client process.)
Proper clean-up serves two goals:
●
The realm server and administrators can distinguish application processes that exit cleanly from
processes that exit abnormally. When a process cleans up, you can infer that it exited deliberately,
rather than unexpectedly.
●
Clean-up manages the resources within a process that closes and reopens the realm but does not
exit.
Program Exit
When a program exits, it is important to close the realm object. This step closes the realm server’s
connection to the program process. The realm server stops monitoring the process.
When a program exits, it is not necessary to close or destroy other objects associated with the realm
object.
Nonetheless, in C programs, you must close the top-level FTL object as well as the realm object.
Close and Reopen the Realm
In contrast, the clean-up requirements are different when a program does not completely exit, but
instead creates a new realm object. In this situation, programs must do these steps, in order:
Close or destroy objects associated with the defunct realm object: including messages, property objects,
field reference objects, content matchers, subscribers, publishers, inboxes, and event queues.
Close the defunct realm object.
Open a new realm object (that is, connect to the realm server).
Create objects associated with the new realm.
Consolidation with Loose Coupling
With process transports, program threads within a process can communicate with one another by
publishing and subscribing to messages. The main use case for process transports is consolidation of
several application processes into one process, to boost performance by decreasing message latency.
To understand the concept of consolidation, consider a purely administrative first step toward the goal
of decreasing latency. The administrator can run cooperating application processes on a single host
computer, where they can communicate using a shared memory transport.
TIBCO FTL® Development
22
A second step is analogous, but involves programming. The developer can consolidate the looselycoupled modules of a distributed application into a single program, where they run in separate threads
that communicate using a process transport.
When consolidating application modules, you may retain the same endpoint structure as before
consolidation. That is, if two modules each used a separate endpoint name before consolidation, the
consolidated program can continue to use the same two endpoint names, and the administrator can
bind them both to the same process transport. (Notice that this endpoint structure reflects the loose
coupling among the module threads.)
Avoid Copying Messages
For best performance with a process transport, avoid the need to copy messages:
●
Publish messages to only one subscriber, in one receiving thread. Publishing a message to two or
more subscribers in two or more receiving threads requires a separate copy of the message for each
receiving thread.
●
Set the publisher property to release messages to send, and set the subscriber property to release
messages to callback.
TIBCO FTL® Development
23
Endpoints
An endpoint is an abstraction that represents a set of publishers and subscribers in communicating
programs.
Within an application program, an endpoint begins as a name. Program code uses the endpoint name
to create endpoint instances, that is, publisher and subscriber objects. Then programs use the publishers
to send messages, and the subscribers to receive messages.
For many applications or communicating application suites, a single endpoint name suffices.
Each subscriber object and each call to a publisher send method introduces an ability requirement (see
Abilities). Application developers record these requirements in endpoint coordination forms (see
TIBCO FTL Endpoint Coordination Form). Administrators define connectors within application
instances to satisfy these ability requirements.
Administrators view an endpoint as a complex entity, embracing four separate communication
abilities. Administrators define application instances, with connectors that bind transports to
endpoints. Those transports implement the endpoints, transferring message data from publishers to
subscribers.
Abilities
An endpoint has four communication abilities. A separate aspect of the API embodies each of these
abilities. The following table summarizes the four abilities.
Each of these four abilities and its API embodiment corresponds to a distinct sub-stream of messages,
called an ability sub-stream.
Endpoint Abilities: Definitions
Ability
API
Description
One-to-Many Receive
Subscriber object
Carries one-to-many messages inbound to the
endpoint’s subscribers in the application.
One-to-One Receive
Inbox subscriber
object
Carries one-to-one messages inbound to the
endpoint’s inbox subscribers in the application.
One-to-Many Send
Send call
of a publisher object
Carries one-to-many messages outbound from the
endpoint’s publishers in the application.
One-to-One Send
Send-to-inbox call
of a publisher object
Carries one-to-one messages outbound from the
endpoint’s publishers in the application.
Notice that each ability combines two dimensions: reach and direction:
●
●
Reach
—
One-to-many abilities carry messages that can reach potentially many subscribers.
—
One-to-one abilities carry messages that can reach one specific inbox subscriber.
Direction
—
Receive abilities carry messages inbound to an application.
—
Send abilities carry messages outbound from an application.
TIBCO FTL® Development
24
Endpoints and Stores
When an application uses stores and durables, endpoints play an additional role. Administrators can
associate each application endpoint with at most one store.
That store serves all publisher and subscriber instances of the endpoint, in all process instances of the
application.
Programs can supply either a durable name or a subscriber name to the create subscriber call,
connecting the new subscriber object to a specific durable within the endpoint’s store.
Number of Endpoints
For many applications a single endpoint name suffices.
Minimizing the number of endpoints usually simplifies design, programming, and administration.
Justify each additional endpoint based on requirements, for example:
●
A functional requirement (such as forwarding)
●
A business requirement to separate the data streams (such as security, or data priority)
●
An administrative requirement to control the endpoints in different ways (such as efficiency, or
flexibility)
Notice that endpoint is not analogous to the concept of destination in the Java Messaging System (JMS).
Within a program, one endpoint name can yield several subscriber objects, each selecting a different
subset of inbound messages. Furthermore, one endpoint can instantiate publishers as well as
subscribers.
Tactics to Reduce Endpoints
If you think an additional endpoint might be necessary, consider whether these tactics might reduce
that need, and simplify the situation:
●
A program can create several publishers and subscribers from a single endpoint name.
●
Administrators can define connectors to carry the four abilities of an endpoint in a way that either
merges their sub-streams, or keeps them separate.
●
Administrators can configure all application instance definitions to implement an endpoint using a
common bus as a shared communication medium, or configure disjoint subsets of instances that use
totally separate buses.
Send: Blocking versus Non-Blocking
Administrators determine the behavior of send calls when a transport bus is full. Program developers
may advise administrators concerning the correct behavior. If the bus is full, that is, it cannot accept any
more messages, then two behaviors are possible.
Send calls in an application program place outbound messages on a bus, which external to the program
process. A transport mediates this I/O operation. Under normal circumstances, the I/O operation
completes quickly, and the send call returns.
Administrators select one of these two behaviors, and configure it in the transport definition.
TIBCO FTL® Development
25
Blocking and Non-Blocking Send
Behavior
Description
Blocking Send
When the bus is full, the send call blocks, and does not return until it has
placed all the outbound message data on the bus.
Non-Blocking Send
(Default Behavior)
When the bus is full, the transport buffers outbound messages in a backlog
buffer in process memory until the bus can accept them. The send call returns.
When the bus can accept more messages, the transport automatically moves
them from its backlog buffer to the bus.
If the backlog buffer overflows, the transport discards the oldest messages in
the buffer to make room for new messages. The discarded messages do not
arrive at slow receivers. The base library reports dataloss advisories to slow
receivers.
Use TIBCO FTL Endpoint Coordination Form to document the correct behavior.
TIBCO FTL® Development
26
Messages
Message Objects in Program Code
The following categories describe messages and the ways that your program code can interact with
them.
Message Origin
Origin is the way in which a message object comes into existence. The origin of a message within a
program is either local or inbound:
●
A message that program code creates using an explicit call is a local message.
●
A message that a program receives through a subscriber is an inbound message.
Message Ownership
Either your program code owns a message, or the TIBCO FTL library owns it. Ownership depends in
part upon message origin, but releasing a message can change its ownership.
Release of Message Ownership
Subscribers can release ownership of inbound messages. Such released inbound messages belong to your
program code, effective upon dispatch to your callback.
Releasing messages is appropriate when a callback delegates message processing to a separate thread.
To enable release to callback behavior, the program must supply a property to the subscriber create call.
Message Ownership, Determining Factors
Origin
Released
Ownership
Local
No
Your program code owns a local message.
Inbound
No
The library owns an inbound message.
Release to callback
Your program code owns an inbound message that the
subscriber has released to the callback.
Destruction
The responsibility to destroy a message depends entirely on the current ownership of a message.
Message, Responsibility to Destroy
Ownership
Responsibility to Destroy
Program code
Program code
Library
Library
TIBCO FTL® Development
27
Message Access
Message origin and current ownership determine the time frame within which your program can safely
access a message object and its data.
Message Access, Determining Factors
Origin
Released
(Ownership)
Access
Local
No
(program code owns)
Until your program destroys the message
Inbound
No
(library owns)
Until your callback returns
Released to callback
(program code owns)
Until your program destroys the message
Message Mutability
Mutability indicates whether your program may modify a message:
●
A program may modify a mutable message by adding, deleting, or changing field values.
●
A program cannot modify an immutable message in any way.
Mutability depends entirely on the origin of a message.
Message Mutability Depends on Origin
Origin
Mutability
Local
A local message is mutable.
Inbound
An inbound message is immutable, even if the subscriber released it to the
callback.
Copy of a Message
Programs can copy any message.
●
The copy is local, even if the original message is inbound.
●
Your program owns the copy, even if the library owns the original.
●
Your program can pass the copy to another thread.
●
The copy is mutable, because it is local. Modifying the copy does not affect the original.
●
The copy, along with all of its data content, is completely independent of the original inbound
message. Even if the library destroys the original, the copy remains accessible. (See also, Storage of
Field Values within Messages.)
Messages and Thread-Safety
Messages are not thread-safe. Ensure that only one thread at a time accesses a message and its data.
TIBCO FTL® Development
28
Field Values and Types
Messages contain data values in a set of fields. Structurally, a field pairs a name of type string with a
value of a specific data type.
The format of a message defines the data type of each field that the message can contain.
Field Data Type Reference
A data type describes the value of a field within a message or a message format.
Administrators use the type names in the first column of the following table to define formats.
Programs denote the data type of message fields using the type constants in the second column of the
table.
Field Data Types
Type Name
(in Realm)
Type Constant
(in Programs)
Description
Primitive
long
TIB_FIELD_TYPE_LONG
A long integer.
Yes
long_array
TIB_FIELD_TYPE_LONG_ARRAY
An array of long integers.
No
double
TIB_FIELD_TYPE_DOUBLE
A double-length floating
point number.
Yes
double_array
TIB_FIELD_TYPE_DOUBLE_ARRAY
An array of double-length
floating point numbers.
No
string
TIB_FIELD_TYPE_STRING
A UTF-8 string.
No
string_array
TIB_FIELD_TYPE_STRING_ARRAY
An array of UTF-8 strings.
No
opaque
TIB_FIELD_TYPE_OPAQUE
An opaque byte-array.
No
message
TIB_FIELD_TYPE_MESSAGE
A message (that is, the
field’s value is a submessage).
No
message_array
TIB_FIELD_TYPE_MESSAGE_ARRAY
An array of messages.
No
inbox
TIB_FIELD_TYPE_INBOX
An inbox.
No
datetime
TIB_FIELD_TYPE_DATETIME
A DateTime value.
No
datetime_array
TIB_FIELD_TYPE_DATETIME_ARRAY
An array of DateTime
values.
No
Storage of Field Values within Messages
Values stored in a message field are part of the message, that is, they reside in memory associated with
the message, and allocated by the library.
When a field’s type is a primitive type, calls that get the field’s value copy that value from the message.
In contrast, when a field’s type is non-primitive, calls that get the field’s value return a pointer to
TIBCO FTL® Development
29
memory within the message. (The fourth column of the table in Field Data Type Reference indicates
primitive and non-primitive types.)
Programs must not modify non-primitive values that reside in memory associated with a message. For
example, you must not set the value of a cell in a long array extracted from a message.
Furthermore, non-primitive values remain valid only for a limited time:
●
A subsequent call that sets the value of that field invalidates a pointer returned by a preceding get
call.
●
Destroying the message invalidates all pointers returned by preceding get calls.
DateTime
Application programs can use the TIBCO FTL data type DateTime to represent date and time values
with large range and nanosecond precision.
DateTime
values combine two numeric components:
●
The sec component represents whole seconds with up to 64 bits. Zero denotes the UNIX epoch:
midnight entering January 1, 1970.
●
The nsec component represents nanoseconds after the time that the sec component denotes.
Although the data structure stores this component in a signed 64-bit integer, this component is
always non-negative, between zero and 999,999,999 (inclusive).
For example, the value -1 seconds plus 999,999,998 nanoseconds represents December 31, 1969, 2
nanoseconds before midnight (that is, 2 nanoseconds before the epoch).
Formats: Managed, Built-In, and Dynamic
A format defines the set of fields that a message can contain: including field names and data types.
TIBCO FTL software supports three broad categories of format: managed, built-in, and dynamic
formats. These categories have differing constraints and performance characteristics.
Managed Format
Application architects and developers determine the set of formats that an application needs.
Administrators then define those managed formats globally.
Administrators make managed formats available to an application by including them as preload formats
for the application.
Programs can use these managed formats to compose new messages, or to unpack inbound messages.
A message with a managed format is small and fast. It does not carry format metadata because that
metadata is available to applications from the realm server.
For efficiency and for safety, administrators can use the Manage All Formats parameters to restrict the
formats available to some or all of the applications in a realm. That is, administrators can require that
applications use only preload formats and built-in formats, and prohibit applications from using
dynamic formats.
Built-In Format
TIBCO FTL software defines a set of highly optimized built-in formats, which are defined within the
base library and always available to all applications. No administrative action is required to make them
available.
The performance characteristics of built-in formats are similar to managed formats. When used
properly, a built-in format can outperform a managed format.
For more information, see Built-In Formats Reference.
TIBCO FTL® Development
30
Dynamic Format
An application implicitly can define a format dynamically, as it constructs a message. That is, the
sending program dynamically determines the set of fields and their data types as it sets field values.
When a program creates a message, and specifies a format that is neither built-in nor preloaded, then
TIBCO FTL software automatically treats it as a dynamic format.
A dynamic format is less efficient than a managed format because each message must be selfdescribing. That is, a dynamic format message necessarily includes its own format metadata. Expect
larger message sizes, slower transmission, slower processing, and longer field access times.
Dynamic formats are useful for rapid prototyping projects. You can switch to defining the application’s
formats as managed formats when the project nears the production stage.
Unnamed Dynamic Format
A program can create a message with a dynamic format, but supply null as the format name. Such
unnamed dynamic formats are single-use. Administrators cannot ever upgrade them to managed formats.
You can use unnamed dynamic formats as a convenience when you cannot determine the structure and
content of a message in advance. Unnamed formats save you the effort of naming the formats and
keeping track of the names.
The performance of unnamed dynamic formats is identical to named dynamic formats.
Format Names
Format names must be unique within a realm, and ideally, throughout the network.
Format names cannot be the empty string.
Format names may contain space characters.
See also Restrictions on Names.
Field Names
Field names must be unique within each format. (Nonetheless, two separate formats may use the same
field name.)
Field names cannot be null, nor the empty string.
Field names may contain space characters.
See also Restrictions on Names.
Flexibility in Formats and Messages
An application suite needs a set of message formats that embraces the various purposes for which it
sends messages. Nonetheless, the simplicity of a smaller set of formats usually yields optimal results.
When a format defines many possible fields, and a program sets only a few field values in a message,
the message remains small, bearing only those fields that the program actually sets.
At one extreme, you can define a single catch-all format with all possible fields. Application programs
can use as few or as many fields as is appropriate, without incurring a performance penalty.
When designing the set of formats for an application suite, balance these competing principles:
●
Specificity Define as many formats as the application needs. If an application sends messages for
different purposes, and the content structure of those messages is different, then define separate and
specific formats for those messages.
TIBCO FTL® Development
31
●
Compactness Defining a small number of formats is a good practice. A large set of formats is more
difficult to understand, to configure, to use properly, and to maintain as your application evolves. If
a subset of the formats are similar, and their usage or meanings are similar, then consider merging
them into one format that contains a union of their fields.
Field Access: Names and References
The APIs provide two versions of each message field accessor call: one accepts a field name, while the
other accepts a field reference object.
Accessing a field by name involves string comparison operations, which can increase processing
latency.
Access by field reference is more efficient than access by name. Field reference objects contain a field
name, along with internal information that facilitates efficient access.
Programs can repeatedly use a field reference object to efficiently access a field, even across messages of
different formats. For example, if formats A and B both have a field named foo, then a field reference
object with field name foo accesses the correct field in messages of either format.
Reusing Message Objects
It is faster to reuse an existing message object than to destroy it and create a new one. Programs can
gain efficiency by reusing message objects, whenever possible.
●
If a program repeatedly sends the exact same message content, then the best practice is to create that
message object only once, sending it many times.
●
If a program sends many messages of the same format, with the same fields, but with varying field
values, then the best practice is to reuse one message object, clearing and modifying individual field
values appropriately before each send call.
●
If a program sends many messages of the same format, but the set of fields varies, then the best
practice is to reuse one message object, clearing all of its fields and setting new values before each
send call.
A program that sends a limited variety of messages can combine these tactics for reusing message
objects. For each send call, it can select an appropriate message from a set of pre-constructed message
objects, and modify as needed. To determine the optimum way to combine these tactics, test
performance empirically.
Built-In Formats Reference
Built-in formats are optimized for efficiency, and are always available. Administrators do not need to
explicitly define them, nor specify them among an application’s preload formats.
The C API defines global constants as listed in the following table.
The Java API defines these constants as fields of class Message.
The .NET API defines these constants as fields of class FTL.
TIBCO FTL® Development
32
Built-In Formats
Format Name Constant
Description
TIB_BUILTIN_MSG_FMT_OPAQUE
The message consists of a singleton field of type opaque.
The constant TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME
denotes the name of that singleton field. (The value of the
constant is _data.)
For the fastest and most efficient message transfer, limit
the data payload to
TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE (12000 bytes).
TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE
This keyed opaque format enhances the opaque format
with a key field of type string. Content matchers can
match against the key field.
The constant TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME
denotes the name of the string field. (The value of the
constant is _key.)
The constant value TIB_BUILTIN_MSG_FMT_KEY_MAXLEN
is the maximum length, in bytes, of the key string field,
including the null terminator character.
The constant TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME
denotes the name of the opaque data field. (The value of
the constant is _data.)
For the fastest and most efficient message transfer, limit
the data payload to
TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE (12000 bytes).
Payload size includes the key, with its null terminator
character, and the opaque data.
Opaque Format
Applications can use the built-in opaque format to exchange messages that contain unstructured data.
Opaque messages are very efficient, and can achieve very low-latency performance.
Opaque messages are an excellent choice for streaming data.
Application code can also embed structured data within opaque messages, however, application code
is entirely responsible for the structure: the application must pack the data at the sender, and unpack
the data at the receiver.
Content matchers cannot select opaque messages. (Recall that content matchers require an exact match
on all specified field names and field values. Opaque values vary too much for content matchers.)
To optimize performance, built-in opaque formats limit the size of the data payload. If you need to send
larger payloads, define a static format with an opaque field.
Keyed Opaque Format
When applications require efficient opaque messages, and also require content matching, you can use
the keyed opaque built-in format. Keyed opaque messages are optimized: though less efficient than the
opaque built-in format, they are more efficient than an equivalent managed format.
Applications can use content matchers to match against the key field.
TIBCO FTL® Development
33
To optimize performance, built-in opaque formats limit the combined size of the data payload and the
key. If you need to send larger payloads, define a static format with an opaque field and a string key
field.
String Encoding
To preserve interoperability throughout your enterprise, all strings must use UTF-8 encoding.
●
When the TIBCO FTL Java and .NET libraries send messages, all strings are automatically UTF-8
encoded.
●
C programs must treat strings in inbound messages as UTF-8 encoded strings.
●
C programs must send only UTF-8 encoded strings.
Strings cannot include embedded null characters.
Message: Printable String Form
Programs can convert a message to a printable string. You can output the string to log files, or user
output streams. The string does not contain sufficient information to reconstitute the original message.
Messages as Printable Strings
Element
Form
Detail
Message
{field, field, field, field}
Curly braces surround a list of fields,
separated by commas. (For
readability, you may add space
characters.)
data_type:field_name=value
Data type, colon, field name, equals
symbol, value.
Nested message
Field (with a
value)
Clear field (no
value)
The output omits the field entirely.
Array
[val, val, val, val]
Square brackets surround array
elements, which are separated by
commas. (For readability, you may
add space characters.)
Opaque
<length bytes>
Angle brackets surround the length of
the opaque data.
String
"chars"
Double-quotes surround the
characters of the string. This
representation does not use escape
characters.
DateTime
yyyy-mm-dd hh:mm:ss.fracZ
For more information, see DateTime
Values Printable String Form.
Printable String Example
This example message string has added whitespace to increase readability. (Actual printable strings do
not include vertical formatting or indenting.)
{long:myLong=44,
opaque:myOpaque=<128 bytes>,
TIBCO FTL® Development
34
message:myInner_msg=
{double:a_double_field=5.300000,
string:an_inner_string_field="the inner "value""},
long_array:an_array=[11, 12, 13, 14, 15, 16, 17, 18, 19, 20],
message_array:a_msg_array=
[{double:a_double_field=5.300021,
string:an_inner_string_field="first inner string"},
{double:a_double_field=123.4506,
string:an_inner_string_field="second inner string"},
{double:a_double_field=72.90927,
string:an_inner_string_field="third inner string"},
{double:a_double_field=17.17017,
string:an_inner_string_field="fourth inner string"},
{double:a_double_field=42.00000,
string:an_inner_string_field="fifth inner string"}]}
Several aspects of this example are noteworthy:
●
The second field, myOpaque, displays a token representing a byte-array. It does not attempt to
display the actual bytes in the byte-array.
●
The third field, myInner_msg, contains a nested sub-message. Curly braces surround the submessage, which in turn has two fields.
The second of those two fields in the nested sub-message contains a string. The string value is
surrounded by double-quote character, and the string itself contains two double-quote characters
(around the word "value"). Those inner double-quote characters are not preceded by an escape
character.
●
The fourth field, an_array, contains an array. The array values are surrounded by square brackets,
and separated by commas.
●
The fifth field, a_msg_array, contains an array of 5 messages. Each message contains two fields: a
double and a string.
DateTime Values Printable String Form
The TIBCO FTL library calls print DateTime field values as strings. Double-quotes surround the
characters of the string.
DateTime values print in UTC format, also known as Zulu time or GMT. The ISO-8601 standard
requires appending a Z character in this notation.
For example, November 19, 2010 6:50:55 PM PST prints as:
2010-11-20 02:50:55.000000000Z
DateTime printing uses Common Era numbering for years. This system does not include a year zero. So
for example, the time 1 second before 0001-01-01 00:00:00.000000000Z would print as
-0001-12-31 23:59:59.000000000Z.
printing uses a proleptic Gregorian calendar. That is, when formatting dates earlier than the
adoption of the Gregorian calendar, it projects the Gregorian calendar backward beyond its actual
invention and adoption.
DateTime
TIBCO FTL® Development
35
Delivery
Inbound Message Delivery
These six phases define the precise terminology that describes the delivery of an inbound message:
Phases of Inbound Message Delivery
Phase
Description
1
Receive
A transport presents a message to a subscriber.
2
Match
If a subscriber has a content matcher, it filters the message. A matching
message advances to the next phase. A message that does not match is
discarded.
3
Distribute
The library adds the message to the event queue associated with the
subscriber.
4
Dispatch
A dispatch call in your program removes messages from the event
queue, and invokes the appropriate callback.
5
Process
Your callback gets data from the message and uses it.
6
Release
The callback returns, releasing the message and its resources.
Phases, Pipelines, and Threads
Consider the six delivery phases as two pipelines. Event queues serve as a stopover point between the
two pipelines:
●
The receive pipeline includes the receive, match, and distribute phases.
●
The dispatch pipeline includes the dispatch, process, and release phases.
Specific threads do the work that moves a message through each pipeline. Each thread requires CPU
resources to do that work.
●
●
One or more receive threads drive the receive pipeline. Inbound data arrives on a transport’s data
source.
—
In the receive phase, receive threads pump messages out of those data sources.
—
In the match phase, receive threads filter messages through the content matcher.
—
In the distribute phase, receive threads place messages on the appropriate event queues.
One or more dispatch threads drive the dispatch pipeline.
—
In the dispatch phase, dispatch threads pump messages out of event queues.
—
In the process phase, dispatch threads process messages using application callbacks.
—
In the release phase, dispatch threads reclaim message resources.
The functional definition of a dispatch thread is any program thread that calls an event queue’s
dispatch method. Your application program determines the number of dispatch threads required to
dispatch and process messages from all its event queues in a timely and efficient manner. (Developers:
record the number of dispatch threads on each programs’ application coordination form.)
TIBCO FTL® Development
36
With regular event queues, receive threads are internal to the TIBCO FTL library, and the library
determines the number of receive threads. In contrast, with inline event queues, the application’s
dispatch thread also serves the functional role of a receive thread, as it combines all six phases into a
single pipeline (see Inline Mode).
Both pipelines begin by polling for available messages: the receive phase polls a transport’s data source,
and the dispatch phase polls an event queue. For the details of polling, see “Receive Spin Limit” in
TIBCO FTL Administration.
Content Matchers
A content matcher filters the inbound stream of messages for a subscriber.
Content matchers operate during the match phase of message delivery (but see Subscriber Interest).
A subscriber can have at most one content matcher. A subscriber without a content matcher distributes
all inbound messages to its event queue: it does not filter out any messages. In contrast, a subscriber
with a content matcher distributes only the messages that match it.
An inbox subscriber cannot have a content matcher. An inbox subscriber always receives all the
messages sent to its inbox.
Each content matcher has a match string, which defines its filtering action. The match string specifies a
set of field names paired with corresponding values. The match string matches a message if and only if
every field specification in the match string correctly matches the presence, absence, or value of a
corresponding field in the message (see Match Semantics).
Match String Syntax
Construct match strings on this syntactic template in JSON format.
{ "fieldname1" : value1 , ... , "fieldnameN" : valueN }
●
Enclose the list of field:value pairs in curly braces.
●
Separate field:value pairs with commas.
●
Enclose field names and string values in double-quote characters. You may precede quote
characters with an escape character, as needed.
●
Do not enclose boolean tokens in double-quote characters.
●
Each field name can appear at most once.
●
Values can be long integers, strings, or the special boolean tokens true or false.
●
When value is a string, its maximum length is 256 characters (see Restrictions on Names).
●
Whitespace is ignored, except within double-quote characters.
Content Matcher: Match String Examples
{"Symbol":"TIBX"}
{"Symbol":"TIBX","Order":"Buy","Price":"Market"}
{"Item":"Book","Title":"The Power of Now"}
{"Answer":42}
{"MustHave":true,"MustNotHave":false,"MustBeZero":0}
Match Semantics
Content matchers interpret match strings using these simple rules.
●
If the match string specifies a field with boolean token true, that field must be present in the
message in order to match.
●
If the match string specifies a field with boolean token false, that field must be absent from the
message in order to match.
TIBCO FTL® Development
37
●
If the match string specifies a field with either a string or long integer value, that field must be
present in the message with that value.
●
When comparing a field name or a value, all comparisons must be exact. Matching does not support
wildcards nor regular expressions.
Content Matcher Performance and Architecture
For best performance, match against no more than 10 fields. (Fewer is faster.)
If your application requires regular expression matches, numeric value ranges, or more than 10 match
fields, then the best practice is to narrow the field of messages with a content matcher, and then code
your callback to refine the filtering even further.
Subscriber Interest
Whenever possible, publishers send messages only to interested subscribers. That is, publishers send
only those messages that match at least one subscriber content matcher. This behavior can reduce
bandwidth consumption, and can enhance subscriber performance in some situations.
To support this feature, subscribers send content matchers to publishers, which apply them to outbound
messages.
Inline Mode
Programs that receive time-sensitive messages can use inline mode to favor low latency over high
throughput. Inline mode reduces inbound message latency by consolidating transport I/O and message
callback processing into one thread.
Before using inline mode, you must understand thoroughly understand the important details in this
topic and the topics that follow.
Background
The term inline mode refers to the execution thread of the six phases of message delivery (see Inbound
Message Delivery).
In regular operation the first three phases are separate from the last three phases. That is, the receive,
match, and distribute phases occur in an internal receive thread, separate from program code.
Meanwhile, the dispatch, process, and release phases occur in a dispatch thread, starting with a
dispatch API call within application program code. The event queue is a loose coupling between these
two triplets of phases: namely, the receive and dispatch pipelines.
In contrast, inline mode co-locates all six phases in the same thread. That is, the entire phase stack
operates as a single I/O pipeline from the underlying transport, through the application program’s
dispatch call, to message processing and release. All six phases occur within one program thread, at the
application’s dispatch call. This tactical optimization eliminates a source of latency, namely, contextswitching overhead between the distribute and dispatch phases. However, this tight coupling
introduces several restrictions and potential pitfalls, which become the responsibility of the application
programmer.
Callback Restrictions with Inline Mode
Inline mode requires that callbacks always return quickly. Otherwise, long callbacks could delay
message I/O, which would defeat the purpose of inline mode.
For example, the negative consequences of long callbacks could include a large I/O backlog. As a result,
the receiving program could lose inbound messages. Furthermore, message buffers at the publishing
end of a transport could fill up. To prevent overflow at these buffers, the transport could block
programs at the publishing end, delaying their outbound messages.
TIBCO FTL® Development
38
Transport Restrictions with Inline Mode
Inline mode restricts underlying transports. Read this entire topic carefully to ensure proper
conformance with the restriction.
When a transport is associated with an inline event queue, it cannot be associated with any other
event queue.
Violating this principle results in an illegal state exception. (The add subscriber API call throws this
exception when the program attempts to add a subscriber that would violate the principle.)
When specifying inline mode, programmers must coordinate with administrators to avoid illegal state
exceptions.
Programmer Violation
The first diagram illustrates the simplest violation, attributable entirely to programmer error. The
programmer creates two subscribers (S1 and S2) from a single endpoint (E1), and adds them to two
event queues, at least one of which (Q1) is an inline queue. This situation would associate the
underlying transport (T1) of the subscribers with two incompatible queues (Q1 and Q2), violating the
restriction.
Illegal Inline Queue, Simple Case
To rectify the violation, either add both subscribers to a single inline event queue (Q1), or to two
ordinary event queue, neither of which use inline mode.
Hidden Violation
While it would appear straightforward for programmers to avoid the violation of the simple case of the
first diagram, the situation is more complicated because responsibilities are divided between
programmers and administrators.
From a programmer’s perspective, transports are ordinarily hidden behind endpoint names.
Conversely, administrators can ordinarily employ transports to implement endpoints without
understanding the specifics of subscribers and queues in application programs. However, inline mode
tightly couples transport I/O to program code, which in turn blurs the usual separation of
responsibilities between programmer and administrator. As a result, the restriction requires that
programmers and administrators coordinate whenever a program uses inline event queues.
TIBCO FTL® Development
39
Consider the following example. The situation in the second diagram might appear correct from the
separate perspectives of the programmer and the administrator, but combining their perspectives
reveals a hidden violation.
Illegal Inline Queue, Hidden Violation
The programmer instantiates two subscribers (S1 and S2) on two separate endpoints (E1 and E2), and
associates them with separate queues (Q1 and Q2). Q1 is an inline queue.
Meanwhile, the administrator employs a single transport (T1) to implement the two endpoints (E1 and
E2).
Because T1 is associated with Q1, which is an inline queue, this arrangement violates the principle.
When the program adds S2 to Q2, the add subscriber call throws an exception, whether or not Q2 uses
inline mode.
By coordinating their information, the programmer and administrator can cooperate to avoid the
violation in any of three ways:
●
Use ordinary queues instead of inline mode.
●
Use separate transports to implement the two endpoints E1 and E2 (see Separate Transports to
Correct a Violation, which follows).
●
Add subscribers S1 and S2 to only one inline queue (see Single Queue to Correct a Violation, which
follows).
Separate Transports to Correct a Violation
In the third diagram, transport T1 is associated with only one inline event queue, Q1. This arrangement
does not violate the restriction.
TIBCO FTL® Development
40
Legal Inline Queue, Separate Transports
Single Queue to Correct a Violation
In the fourth diagram, even though two subscribers (S1 and S2) share the same underlying transport
(T1), they are associated with the same inline event queue (Q1). This arrangement does not violate the
restriction.
Legal Inline Queue, Single Queue
TIBCO FTL® Development
41
Realm Server Interactions
Realm Server Connect Call
Every application program must connect as a client to a realm server. The realm connect call identifies
the client to the realm server, and receives the realm definition in return.
Developers must coordinate with administrators regarding the information that programs supply in
the realm connect call:
●
Realm Server URL (required)
●
Application Name (required)
●
Application Instance Identifier (optional)
●
Security Credentials (optional)
●
Secondary URL (optional, for fault tolerance)
●
Trust Properties (required to connect to a secure realm server)
Operation of the Realm Server Connect Call
When a client program contacts a realm server, the realm connect call uses these algorithms:
One Server
If the program’s realm object has only a single URL for the realm server, the realm connect call sends
requests to the server at that URL.
If the server does not respond to repeated requests, the realm connect call throws an exception.
Fault-Tolerant Servers
If the program’s realm object has two URLs for the realm server, they indicate primary and secondary
realm servers. The realm connect call sends requests first to the primary URL.
If the primary server does not respond to the first request, the realm connect call sends the request to
the secondary URL. If the secondary server also does not respond, the realm connect call sends
repeated requests, alternating between primary and secondary.
If neither server responds to repeated requests, the realm connect call throws an exception.
Trust Properties of the Realm Connect Method
In an enterprise with TLS security, client applications must trust the realm server. Properties of the
realm connect method specify the behavior of this interaction.
●
- This property indicates the way that the client
determines trust in the realm server. Its value is one of the following constants:
TIB_REALM_PROPERTY_LONG_TRUST_TYPE
- The client trusts the realm server based on
the trust file created by the realm server and distributed by the administrator. Specify the file
path of the trust file in an adjunct parameter, TIB_REALM_PROPERTY_STRING_TRUST_FILE.
—
HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE
—
HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING - The client trusts the realm server based a
trust string. Specify that data content in an adjunct parameter,
TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING.
—
HTTPS_CONNECTION_TRUST_EVERYONE
trust in the server's certificate.
- The client trusts any realm server without verifying
TIBCO FTL® Development
42
Do not use this value except for convenience in development and testing. It is not
secure.
●
TIB_REALM_PROPERTY_STRING_TRUST_FILE
trust file.
●
- The string value of this property is the file path of the
TIB_REALM_PROPERTY_STRING_TRUST_PEM_STRING
string in PEM format.
- The string value of this property is the trust
The names of properties and constants vary slightly among the languages that the API supports.
Trust File
A secure realm server automatically generates a trust file. The content of the trust file instructs clients to
trust the realm server's certificate. Administrators and developers coordinate to supply the trust file to
application programs.
A secure realm server generates the trust file in its data directory. The trust file is named ftlThe file contains one or more PEM-encoded public certificates, each of which is typically 1 2 kilobytes of data.
trust.pem.
Realm administrators give the trust file to the clients: that is, developers and application administrators
coordinate so that client programs can access the trust file at run time.
Administrators also supply the trust file directly to TIBCO FTL client processes such as affiliated realm
servers and persistence servers.
Users can load the trust file into a web browser’s trust store.
Affiliated Realm Servers and the Trust File
An affiliated realm server uses the same trust file as its primary realm server. That is, although a
backup or satellite server generates its own keystore file, nonetheless the trust file it generates is an
exact copy of the primary server's trust file. As a consequence, you do not need to distribute separate
trust files to clients of a family of affiliated servers: one trust file suffices for the whole family.
Regeneration and Redistribution of the Trust File
If a realm server cannot access its TLS data files, or it cannot decrypt the keystore file, then it generates
new TLS data files. The newly generated data files replace any existing data files.
If a primary realm server generates new TLS data files, you must redistribute the new trust file to all
clients, including affiliated realm servers, other TIBCO FTL components, application programs, and
browsers that access the realm server GUI.
Two scenarios can trigger this requirement:
●
No Access: A primary realm server restarts and cannot access its TLS data files: for example, they
have been deleted or moved, or their file access permissions have changed.
●
New Password: An administrator restarts the primary realm server, supplying a different
password. The server cannot decrypt the existing keystore file using the new password.
(If a secondary realm server generates new TLS data files, you need not redistribute its trust file.)
Update and Disable
After the initial connect call, the client and server remain in contact.
●
Administrators can use the realm server monitoring interface to view the status of client processes.
●
Administrators can modify the realm definition, and deploy the updated definition to all clients.
TIBCO FTL® Development
43
●
Administrators can disable individual client processes. A disabled client cannot use TIBCO FTL
communications resources.
TIBCO FTL® Development
44
Trace Logs
Developers, administrators, and TIBCO Support staff can use trace logs for diagnostic purposes.
Application developers can set the log level, and the log output target.
Log Levels
The log level determines the level of detail and the quantity of log statements. Properly tuned logging
can help diagnose unexpected behaviors. Excessively detailed logging can contribute to message
latency and consume storage resources.
Application developers can set the log level using an API entry point. In addition, TIBCO FTL
executable components accept the same log level specifications through command line arguments.
Tuning the Log Level
You can tune the log level either for all logging elements, or tune it separately for individual elements.
Procedure
Task A Tuning for All Elements
1. Supply one of the log level strings or string-valued constants in Log Level Reference.
Task B Tuning Separately for Individual Elements
2. Supply a string of this form:
"element:level; ... ;element:level"
That is, pair each element and its log level with a colon, and delimit the pairs with semicolons. Log
Element Tags Reference presents the available elements.
When elements collide, pairs that appear later in the list override earlier pairs. For example,
all:off;RS:warn turns off logging for all elements, except for the realm server element, which logs
warnings and severe events. That is, RS overrides the preceding all element.
Log Level Reference
These API constants and their string values denote the available log levels.
Log Level Constants and Values
Log Level Constant
String
Description
TIB_LOG_LEVEL_OFF
off
Disable all tracing.
TIB_LOG_LEVEL_SEVERE
severe
Output trace entries only for severe events.
TIB_LOG_LEVEL_WARN
warn
Output trace entries for warning and severe events.
TIB_LOG_LEVEL_INFO
info
Output trace entries for information, warning, and
severe events.
If an application program does not explicitly set the log
level, the library uses this default value.
TIBCO FTL® Development
45
Log Level Constant
String
Description
TIB_LOG_LEVEL_VERBOSE
verbose
Output trace entries for verbose, information, warning,
and severe events.
TIB_LOG_LEVEL_DEBUG
debug
Output trace entries for debug, verbose, information,
warning, and severe events.
The output from debug and verbose can result in very large log files. This level of detail is generally
not useful unless TIBCO staff specifically requests it.
Log Element Tags Reference
These strings denote the available log element tags.
Log Element Tags
Element
Description
all
Tune logging for all elements, embracing all the categories in this table.
application
Tune logging related to the application program, such as the program’s use of
API calls, message formats, and content matchers.
IO
Tune logging related to data I/O, such as message data entering or leaving the
program, and message packetization.
RS
Tune logging related to the realm server.
●
In realm server client processes, this category includes client communication
with the realm server.
●
In realm server processes, this category includes operations within the realm
server, such as communication with clients, with affiliated realm servers, and
with group servers.
transports
Tune logging related to transports, including peer connections, subscriber
interest, message send operations, protocols.
store
Tune logging related to stores and durables, such as store and durable operations,
quorum formation, and leader election.
Log Output Targets
Developers can select the output target for log statements. Application programs can use one of three
mutually exclusive targets.
Log Targets
Log Target
Description
Default Log Target
Output all log statements to stderr.
Log Files in Rotation
Output all log statements to a set of rotating log files.
TIBCO FTL® Development
46
Log Target
Description
Log Callback
The program defines a callback, which intercepts all log statements.
Each program process may set its log target only once. Attempting to set it again is an error.
Default Log Target
If a program does not set a log target, TIBCO FTL software directs all log statements to stderr.
Log Files in Rotation
Rotating log files organize log output into a set of files, and limit the file system storage that log
statements can consume.
The call that arranges rotating log files accepts a file prefix, the file size that triggers rotation, and the
maximum number of files.
Log files receive filenames consisting of the prefix you supply, a dot (.) character, and an integer suffix.
Suffix zero indicates the current log file. Suffix 1 indicates the next most recent. Higher suffixes indicate
older files.
Rotating renames each file in the set by incrementing its numeric suffix. If rotating would exceed the
maximum number of files, then it discards the oldest file. These file I/O operations can affect message
latency.
The TIBCO FTL library requires that the total length of any log file name must be strictly less than 1024
characters. The host computer’s operating system may require a smaller file name length.
Log Callback
Applications can define and register a log callback. Instead of directing log statements to the file
system, the TIBCO FTL libary invokes the callback to process each log statement (that is, to enter it into
the application’s log system).
This type of target can introduce overhead costs and potential latency.
Log Callback Restrictions
Programmers must ensure that the callback always returns promptly. The log callback executes
inline, that is, synchronously, and can affect message latency.
●
●
Your callback must not call any TIBCO FTL API entry point.
●
Your callback must be thread-safe.
●
For best results, your callback must not acquire any lock that might require a long wait time.
Log Content and Form
The form and content of trace log output are not part of a defined interface: they could change in
subsequent releases.
Avoid programming techniques that rely on parsing log output, or depend on log content.
TIBCO FTL® Development
47
Advisory Messages
TIBCO FTL software presents asynchronous advisory messages to application programs. Advisory
messages can indicate errors, warnings, or other information.
In contrast with exceptions and error codes, which indicate success or failure within a specific TIBCO
FTL call, asynchronous advisory messages notify programs of incidents that occur outside of the
program’s direct flow of control.
When it is not possible to communicate through an advisory message, TIBCO FTL software presents an
out-of-band notification instead (see Notifications).
Programs must arrange to receive and process information through both of these mechanisms:
advisories and notifications.
Advisory Message Common Fields Reference
Advisory messages contain fields that present information to programs. Some fields are present on all
advisory messages. Other fields are present only when information is available. Still other fields are
associated only with specific advisory messages. Programs can use content matchers to select subsets of
advisory messages from the advisory endpoint.
Advisory Message, Common Fields
Field
Present
Description
name
Always
The value denotes the general category of the advisory.
reason
Only as needed
The value distinguishes among several possible reasons
for the advisory.
severity
Always
The value classifies the advisory according to the ability
of TIBCO FTL software to fulfill its function as a message
carrier.
module
Always
The value denotes the part of TIBCO FTL software to
which the advisory pertains.
timestamp
Always
The DateTime value of this field indicates the time that
the library generated the advisory.
Although DateTime values can represent time with
nanosecond precision, the actual resolution of the
timestamp is only as fine-grained as the host computer's
operating system supports.
aggregation_count
Only for
aggregate data
The value represents the number of aggregated incidents.
aggregation_time
Only for
aggregate data
The value represents the length of the time interval, in
seconds, for aggregated data.
TIBCO FTL® Development
48
Subscribing to Advisory Messages
To receive advisory messages, programs can create subscribers on a special endpoint named
(In each supported programming language, an API constant has the name of this
endpoint as its value.)
_advisoryEndpoint.
Scope and Restrictions
The realm object scopes the advisories that a subscriber can receive on the special advisory endpoint,
_advisoryEndpoint. That is, a subscriber to this endpoint receives only those advisories produced by
other objects in the same program and the same realm as the advisory subscriber.
It is illegal to create publishers on the special advisory endpoint.
Procedure
1. Determine the set of advisory messages to receive.
2. Determine the action of your program in response to each advisory message.
3. Define message callbacks to process the advisory messages.
For example, an advisory callback might respond by logging the content of the advisory, by
notifying an administrator, or by exiting.
4. Optional. Define content matchers.
A subscriber may receive all advisory messages without distinguishing among them, or it may
select a specific subset of advisory messages using a content matcher.
5. Create subscribers on the special advisory endpoint.
6. Create a special event queue, dedicated only to dispatching and processing advisory messages.
This queue must never discard events.
7. Code a special dispatch thread within your program, dedicated only to dispatching the advisory
event queue. Ensure that this thread always receives sufficient CPU cycles in a timely fashion, even
when other dispatch threads might be stuck.
8. Add the advisory subscribers to the dedicated advisory event queue.
Advisory Messages Catalog
Application programs can receive the advisory messages in this table.
Advisory Message Catalog
Name and Reason
Description
DATALOSS FAILOVER_LOSS
Failover to a backup forwarding component, such as a
transport bridge.
DATALOSS INCOMPLETE_MESSAGE
A transport could not reassemble the complete message.
DATALOSS QUEUE_LIMIT_EXCEEDED
An event queue discarded events.
DATALOSS SENDER_DISCARD
A transport discarded messages in accordance with its
backlog settings (non-blocking send).
DATALOSS TPORT_DATALOSS
A transport lost data packets.
TIBCO FTL® Development
49
Name and Reason
Description
DATALOSS RECONNECT_LOSS
A connection-oriented transport became disconnected.
DATALOSS
A subscriber to a last-value durable missed messages.
STORE_DISCARD_DATALOSS
DATALOSS UPSTREAM_LOSS
A forwarding component detected an upstream dataloss
advisory.
DATALOSS DIRECT_SUB_LOSS
A direct subscriber lost data.
RESOURCE_AVAILABLE
A resource is available.
RESOURCE_UNAVAILABLE
A resource is unavailable.
Groups
ORDINAL_UPDATE
Change to a group ordinal.
Stores and Durables
SUBSCRIBER_FORCE_CLOSE
A store forced a subscriber object to close.
LOCK_LOST
The client program no longer holds a lock.
Multicast Retransmission
RETRANSMISSION
A subscriber requested retransmission.
RETRANSMISSION_REQUEST
RETRANSMISSION
A publisher sent a retransmission.
RETRANSMISSION_SENT
RETRANSMISSION
A subscriber suppressed a retransmission request.
RETRANSMISSION_SUPPRESSED
DATALOSS FAILOVER_LOSS
This advisory reports potential dataloss. The reason is failover to a backup forwarding component.
Details
Only connection-oriented transports can detect this condition.
This advisory does not indicate the volume of lost data, but rather the number of data loss incidents.
Each data loss incident represents the potential for lost messages. (The volume of lost data could be
zero.)
Actions
Report this advisory to an administrator. Check the forwarding component.
TIBCO FTL® Development
50
Fields
Field
Description
name
DATALOSS
reason
FAILOVER_LOSS
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of failover
incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS SENDER_DISCARD
The advisory reports an unrecoverable dataloss. The reason is transport backlog overflow at the
publisher, in accordance with the transport’s backlog settings.
Details
This advisory reports only inbound dataloss to subscribing programs. It does not report outbound
dataloss to the publishing program.
This advisory does not indicate the volume of lost data, but rather the number of dataloss incidents.
Each dataloss incident represents at least one lost message, but could represent many lost messages.
For more information about backlog overflow, see Send: Blocking versus Non-Blocking.
Actions
Report this advisory to an administrator.
TIBCO FTL® Development
51
Fields
Field
Description
name
DATALOSS
reason
SENDER_DISCARD
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of dataloss
incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS QUEUE_LIMIT_EXCEEDED
The advisory reports dataloss. The reason is overflow of an event queue.
Details
The queue has discarded some events, in accordance with its property values.
Diagnoses
●
Lengthy processing in callbacks could delay prompt dispatch of the queue.
●
The program could not process the volume of inbound messages from its subscribers.
●
The program is starved for CPU cycles. Its host computer is too heavily loaded.
●
The maximum events limit of the event queue is too low.
Actions
Consider whether this behavior is reasonable and expected.
Report this advisory to an administrator.
TIBCO FTL® Development
52
Fields
Field
Description
name
DATALOSS
reason
QUEUE_LIMIT_EXCEEDED
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of events that
the queue discarded during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS INCOMPLETE_MESSAGE
Purpose
The advisory reports dataloss. The reason is an incomplete message.
The transport could not reassemble an inbound message because some data fragments did not arrive.
Diagnoses
●
Network issues could interfere with message transmission.
●
The sending process abruptly exited before transmitting all packets.
●
When this advisory occurs alongside DATALOSS
sending process or a forwarding component.
SENDER_DISCARD,
the problem could be within the
Actions
Report this advisory to an administrator.
TIBCO FTL® Development
53
Fields
Field
Description
name
DATALOSS
reason
INCOMPLETE_MESSAGE
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of incomplete
message incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS TPORT_DATALOSS
The advisory reports an unrecoverable dataloss. The reason is a transport malfunction.
Details
This advisory reports only inbound data loss, not outbound.
This advisory does not indicate the volume of lost data, but rather the number of data loss incidents.
Each data loss incident represents the potential for lost messages. (The volume of lost data could be
zero.)
Actions
Report this advisory to an administrator.
TIBCO FTL® Development
54
Fields
Field
Description
name
DATALOSS
reason
TPORT_DATALOSS
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of dataloss
incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS RECONNECT_LOSS
The advisory reports potential dataloss. The reason is a temporary network disconnect between two
connection-oriented transports.
Details
This advisory reports only inbound data loss, not outbound.
This advisory does not indicate the volume of lost data, but rather the number of data loss incidents.
Each data loss incident represents the potential for lost messages. (The volume of lost data could be
zero.)
Actions
Report this advisory to an administrator.
TIBCO FTL® Development
55
Fields
Field
Description
name
DATALOSS
reason
RECONNECT_LOSS
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of disconnect
incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS STORE_DISCARD_DATALOSS
The advisory reports potential data loss at a subscriber to a last-value durable. The reason is that the
subscriber has either missed one or more messages, or disconnected from the persistence store.
Details
A subscriber to a last-value durable receives every message that updates that durable. However, if the
subscriber cannot keep up with the stream of updates from publishers, the subscriber might miss
messages, as the durable stores only the most recent message.
If the subscriber disconnects from the persistence store, it could miss messages during the interval in
which it remains disconnected.
This advisory reports only inbound data loss, not outbound.
This advisory does not indicate the volume of lost data, but rather the number of data loss incidents.
Each data loss incident represents the potential for lost messages. (The volume of lost data could be
zero.)
TIBCO FTL® Development
56
Actions
Report this advisory to an administrator.
Fields
Field
Description
name
DATALOSS
reason
STORE_DISCARD_DATALOSS
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of discard or
disconnect incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS UPSTREAM_LOSS
The advisory reports potential dataloss. The reason is a dataloss advisory detected upstream at a
forwarding component (such as a transport bridge).
Details
This advisory reports only inbound data loss, not outbound.
This advisory does not indicate the volume of lost data, but rather the number of data loss incidents.
Each data loss incident represents the potential for lost messages. (The volume of lost data could be
zero.)
Actions
Report this advisory to an administrator.
TIBCO FTL® Development
57
Fields
Field
Description
name
DATALOSS
reason
UPSTREAM_LOSS
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of dataloss
incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
DATALOSS DIRECT_SUB_LOSS
The advisory reports an unrecoverable data loss at a direct subscriber.
Details
This advisory reports only inbound data loss, not outbound.
This advisory does not indicate the volume of lost data, but rather the number of data loss incidents.
Each data loss incident represents the potential for lost messages. (The volume of lost data could be
zero.)
Actions
Report this advisory to an administrator.
TIBCO FTL® Development
58
Fields
Field
Description
name
DATALOSS
reason
DIRECT_SUB_LOSS
endpoints
The string array value of this field lists the endpoints that could have lost
data.
Although data loss occurs primarily in a transport, its symptoms could
affect all endpoints that use the transport, and by extension, any subscriber
on those endpoints. Furthermore, transport names are meaningful to
administrators, but usually not available to programmers. This advisory
field reports the set of all endpoints through which the program could
access the problematic transport, according to the configuration in the local
realm object.
aggregation_count
The long value of this field reports the cumulative number of data loss
incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
ORDINAL_UPDATE
The advisory reports a change to a group ordinal.
Details
For background information, see Groups of Applications.
Actions
Programs change the member’s operating role and behavior according to the new ordinal.
Fields
Field
Description
name
ORDINAL_UPDATE
TIBCO FTL® Development
59
Field
Description
group
Group name.
The name of the group to which the advisory pertains.
ordinal
Group member ordinal.
The positive long value of the ordinal field represents the new ordinal of
the group member.
The value -1 indicates that the group object is disconnected from the group
server. The group object automatically attempts to reconnect, and continues
until the program explicitly destroys the object. Meanwhile, the group
server could reassign the member's previous ordinal to another group
member.
Zero is a reserved value.
GROUP_STATUS
The advisory reports the status of a group and its members.
Group status messages differ in form and content, depending on the member and the state change. For
more information, see Group Status.
Fields of the Group Status Advisory Message
Field
Description
name
GROUP_STATUS
group
Group name.
The name of the group to which the advisory pertains.
group_server_available
When present, the long value of this field indicates
whether the application process has a functioning
connection to the group server.
group_member_status_list
When present, the value of this field is an array of
submessages. Each submessage describes the status of one
group member.
Fields of the Member Status Submessage
Field
Description
group_member_descriptor
The value of this field is a message that identifies a group
member.
Member programs can supply this optional member
descriptor message when the program joins the group. If
the member does not supply a descriptor, then this field is
absent in the status submessage: the member is
indistinguishable from any other member that omits a
descriptor.
TIBCO FTL® Development
60
Field
Description
group_member_event
The long value of this field is an enumerated constant that
indicates the connection status of the group member.
RESOURCE_AVAILABLE
The advisory reports that a resource is available.
Details
Persistence servers are resources. For background information, see Persistence: Stores and Durables on
page 73.
Diagnosis
A resource that had been unavailable is now available. Operations that required that resource may
proceed. The reason field indicates the resource.
Actions
Report this advisory to an administrator.
Fields
Field
Description
name
RESOURCE_AVAILABLE
reason
PERSISTENCE_STORE_AVAILABLE
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
RESOURCE_UNAVAILABLE
The advisory reports that a resource is unavailable.
Details
Persistence servers are resources. For background information, see Persistence: Stores and Durables on
page 73.
Diagnosis
A required resource is unavailable. The reason field indicates the resource.
●
The tibstore cluster lacks a quorum of available servers for the store. Application clients must wait
until a quorum forms.
●
An insufficient number of store servers are operating. Administrators must attend to server
processes.
TIBCO FTL® Development
61
Actions
Report this advisory to an administrator.
If this state continues for a long duration, investigate whether hardware or network issues are
interfering with resource operation or communication.
Fields
Field
Description
name
RESOURCE_UNAVAILABLE
reason
PERSISTENCE_STORE_UNAVAILABLE
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
RETRANSMISSION RETRANSMISSION_REQUEST
The advisory reports that a subscribing endpoint in the application process requested retransmission
from a publisher.
Details
Retransmission is a normal occurrence for multicast transports. Retransmission advisories give
applications access to data about network conditions.
When the subscribing endpoint of a multicast transport detects that it has missed one or more data
packets, it requests that the publishing endpoint retransmit them. If possible, the publishing endpoint
complies. Otherwise data loss occurs.
This advisory has severity DEBUG. It does not indicate impaired behavior. Applications can receive it
only when the log level is set to DEBUG for the transports element. See also Tuning the Log Level.
Actions
This advisory contains information for debugging. Report this advisory to an administrator.
Fields
Field
Description
name
RETRANSMISSION
reason
RETRANSMISSION_REQUEST
endpoints
The string array value of this field lists the endpoints that detected missed
data packets.
TIBCO FTL® Development
62
Field
Description
aggregation_count
The long value of this field reports the cumulative number of
retransmission request incidents during the time interval (see
aggregation_time).
The base library aggregates this count separately for each transport.
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
RETRANSMISSION RETRANSMISSION_SENT
The advisory reports that a publishing endpoint in the application process retransmitted data packets
as requested as requested by a subscribing endpoint.
Details
Retransmission is a normal occurrence for multicast transports. Retransmission advisories give
applications access to data about network conditions.
When the subscribing endpoint of a multicast transport detects that it has missed one or more data
packets, it requests that the publishing endpoint retransmit them. If possible, the publishing endpoint
complies. Otherwise data loss occurs.
This advisory has severity DEBUG. It does not indicate impaired behavior. Applications can receive it
only when the log level is set to DEBUG for the transports element. See also Tuning the Log Level.
Actions
This advisory contains information for debugging. Report this advisory to an administrator.
Fields
Field
Description
name
RETRANSMISSION
reason
RETRANSMISSION_SENT
endpoints
The string array value of this field lists the endpoints that re-sent missed
data packets.
aggregation_count
The long value of this field reports the cumulative number of data
retransmission incidents during the time interval (see aggregation_time).
The base library aggregates this count separately for each transport.
TIBCO FTL® Development
63
Field
Description
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
RETRANSMISSION RETRANSMISSION_SUPPRESSED
The advisory reports that a subscribing endpoint in the application process would have requested
retransmission, but the request was suppressed. Suppression of retransmit requests can occur when a
multicast transport enables retransmission control, and a subscriber misses packets in excess of a
specified threshold.
Details
Retransmission is a normal occurrence for multicast transports. Retransmission advisories give
applications access to data about network conditions.
When the subscribing endpoint of a multicast transport detects that it has missed one or more data
packets, it requests that the publishing endpoint retransmit them. If possible, the publishing endpoint
complies. Otherwise data loss occurs.
This advisory has severity WARN.
Actions
Report this advisory to an administrator.
Fields
Field
Description
name
RETRANSMISSION
reason
RETRANSMISSION_SUPPRESSED
endpoints
The string array value of this field lists the endpoints that suppressed
retransmission requests.
aggregation_count
The long value of this field reports the cumulative number of
retransmission request suppression incidents during the time interval (see
aggregation_time).
The base library aggregates this count separately for each transport.
TIBCO FTL® Development
64
Field
Description
aggregation_time
The double floating point value, in seconds, of this field indicates the length
of the time interval for aggregating the incidents that aggregation_count
reports.
The time interval ends shortly before the timestamp.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
SUBSCRIBER_FORCE_CLOSE
The advisory reports that the store closed a durable subscriber.
Details
For background information, see Persistence: Stores and Durables on page 73.
Diagnosis
Each durable can serve at most one subscriber object at a time. A durable subscriber connected to the
store, and it maps to a durable that already serves another subscriber object. The store resolves
collisions in favor of the more recent subscriber, deactivating the older subscriber.
Actions
Close the subscriber object. Clean up application state associated with the subscriber. Report this
advisory to an administrator.
Fields
Field
Description
name
SUBSCRIBER_FORCE_CLOSE
reason
DURABLE_SUBSCRIBER_COLLISION
endpoints
The string array value of this field contains the single endpoint that the
closed subscriber had instantiated.
subscriber_name
Subscriber name of the closed durable subscriber.
timestamp
The DateTime value of this field indicates the time that the library
generated the advisory.
Although DateTime values can represent time with nanosecond precision,
the actual resolution of the timestamp is only as fine-grained as the host
computer's operating system supports.
TIBCO FTL® Development
65
LOCK_LOST
The advisory reports that the client program no longer holds a lock.
Details
For background information, see Locks.
Diagnosis
●
Another client process has stolen the lock.
●
This client process disconnected from the persistence server. All locks are invalid.
Actions
Request the lock again.
Fields
Field
Description
name
LOCK_LOST
reason
TIB_ADVISORY_REASON_LOCK_STOLEN
TIB_ADVISORY_REASON_LOCK_LOST_ON_DISCONNECT
lock_name
The string value of this field contains the name of the lock that was stolen or
lost.
TIBCO FTL® Development
66
Notifications
In some situations, the base library must notify programs of conditions that preclude the use of event
queues as the communications medium. Instead of sending an advisory, the library notifies the
program through an out-of-band mechanism.
All application programs must define a notification handler callback to process these out-of-band
notifications, and register that callback using the set notification handler method.
Notifications Catalog
Out-of-Band Notification Catalog
Name and Reason
Description
CLIENT_DISABLED
The realm server disabled this application process.
CLIENT_DISABLED
This notification alerts the application code that the realm server administratively disabled this client
process.
Diagnoses
●
An administrator modified the realm definition, but this application process could not accept the
changes, and the administrator disabled it (along with other processes that could not accept the
changes).
●
An administrator disabled this process to solve a problem (for example, consuming too much
network bandwidth).
The administrator can supply an optional string to indicate a reason for disabling client processes.
The notification callback receives this reason string as an argument.
Actions
Your notification callback must arrange for either of these two recovery actions:
●
Create a new realm object and associated objects, and resume operation.
●
Exit and restart.
To determine the appropriate recovery action, see Recovery of a Disabled Process Restart versus
Reopen the Realm.
To do either recovery action, see Clean-Up.
TIBCO FTL® Development
67
Groups of Applications
Applications can use the group facility to coordinate fault-tolerant operation, or to distribute operating
roles among application processes.
Introduction to Groups
A set of application processes can join a group. Each member of a group receives an ordinal, that is, a
number representing its current position within the group. Application program logic uses the ordinal
to select one of several possible operating roles.
A group server tracks the group members as processes join and leave the group, and as they disconnect
from and reconnect to the server. At each of these events, the group facility revises ordinals to restore a
one-to-one mapping between n members and the positive integers [1,n].
Developers are responsible for the names of groups, and for the API calls that join groups.
Administrators are responsible for configuring group communication, and for running the group
servers.
Simple Fault Tolerance with Groups
Application programs can use the group facility to coordinate fault-tolerant operation.
For example, consider an application program that can operate in either of two roles, according to its
application logic:
●
A1 is the active role: the program subscribes to messages, processes each message, and sends
another message in response.
●
A2 is the standby role: the program subscribes to messages, but neither processes them nor sends
responses.
Simple Fault Tolerance, Role Behavior
Ordinal
Role
Description
1
A1
Actively process messages
2 or greater
A2
Standby
When a process instance of the program starts, it joins group_A, and receives its ordinal. The first
process to start (P1) receives ordinal 1, so according to its application logic, it enters role A1:
subscribing, receiving, processing, and sending messages. The second process to join the group (P2)
receives ordinal 2, so it enters the A2 standby role. (If any additional processes join the group, they
would receive ordinals 3, 4, 5, in sequence. They would also enter the A2 standby role.) In the following
Timeline table, time t1 describes this state.
Simple Fault Tolerance, Timeline
Time
Process P1
Process P2
Process P3
Process P4
Process P5
t1
Ord=1
Ord=2
Ord=3
Ord=4
Ord=5
Role=A1
Role=A2
Role=A2
Role=A2
Role=A2
TIBCO FTL® Development
68
Time
Process P1
Process P2
Process P3
Process P4
Process P5
t2
Ord=-1
Ord=1
Ord=2
Ord=3
Ord=4
Role=A2 (or
exit)
Role=A1
Role=A2
Role=A2
Role=A2
Ord=5
Ord=1
Ord=2
Ord=3
Ord=4
Role=A2
Role=A1
Role=A2
Role=A2
Role=A2
t3
If P1 exits, or becomes disconnected from the group server, as at time t2, then all group members would
receive new ordinals within the group, usually decrementing their existing ordinal. In particular,
process P2 would receive ordinal 1, enter role A1, and begin processing messages and sending
responses.
Meanwhile, if process P1 is still running while disconnected from the group server, then the group
facility assigns it ordinal -1 and attempts to reconnect to the group server. The program can either exit,
or enter the standby role A2, according to its program logic.
If P1 restarts, or reconnects to the group server, as at time t3, then it would receive the lowest
unassigned ordinal, and operate in the corresponding role. Notice that P1 does not resume with ordinal
1: instead, P2 retains ordinal 1.
Groups with More than Two Roles
You can extrapolate fault-tolerant behavior to an application with several distinct operating roles.
For example, consider an application that uses roles for graceful degradation of service. Each role
subscribes to a different subset of messages by using different content matchers, and processes
matching messages.
●
B1 is an active role: the program processes high priority messages with matcher M1, and ignores the
rest. The member with ordinal 1 operates in this role.
●
B2 is an active role: the program processes medium priority messages with matcher M2, and ignores
the rest. The member with ordinal 2 operates in this role.
●
B3 is an active role: the program processes low priority messages with matcher M3, and ignores the
rest. The member with ordinal 3 operates in this role.
●
B4 is the standby role: the program does not process any messages. Any member with ordinal 4 or
greater operates in this role.
More than Two Roles, Role Behavior
Ordinal
Role
Description
1
B1
Actively process high priority messages
2
B2
Actively process medium priority messages
3
B3
Actively process low priority messages
4 or greater
B4
Standby
TIBCO FTL® Development
69
More than Two Roles, Timeline
Processes
Running
Process P1
1
Ord=1
Process P2
Process P3
Process P4
Process P5
Role=B1
2
3
4 or more
Ord=1
Ord=2
Role=B1
Role=B2
Ord=1
Ord=2
Ord=3
Role=B1
Role=B2
Role=B3
Ord=1
Ord=2
Ord=3
Ord=4
Ord=5
Role=B1
Role=B2
Role=B3
Role=B4
standby
Role=B4
standby
When only one instance of application B is running, it has ordinal 1, role B1, and it processes messages
with the highest priority. It does not devote any time to messages with medium or low priority.
When two instances are running, one instance, with ordinal 1, role B1, processes messages with high
priority. Meanwhile the other instance, with ordinal 2, role B2, processes messages with medium
priority. Neither devotes any time to messages with low priority.
When three instances are running, each instance processes messages with a different priority, and
together they cover all the priorities. That is, one instance has ordinal 1, role B1, and processes
messages with high priority. Meanwhile, the second instance, with ordinal 2, role B2, processes
messages with medium priority. The third instance, with ordinal 3, role B3, processes messages with
medium priority.
When four or more instances are running, the instances with ordinal greater than 3 idle in standby role
B4, ready to processes messages if an instance in any of the processes in the three active roles were to
become unavailable.
Notice that when the process with ordinal k becomes unavailable, all processes with ordinals greater
than k shift their roles. When developing programs, design program logic to make this shift smoothly
and rapidly.
Groups Principles of Operation
Group Server
A single group server coordinates all the members of a group. One group server can coordinate several
different groups.
The group server runs inside of the realm server process. Administrators configure the group server
(see TIBCO FTL Administration). Programs use the group facility’s API calls to interact with the group
server, and to coordinate appropriate behavior.
Group Members
Each group has a unique group name, which identifies its members to the group server.
In each group, every member must be able to assume any role, according to its current ordinal. You can
satisfy this requirement in a natural way if all the members are process instances of one application
program, compiled from source code with identical functionality (though they may execute on different
hardware and operating system platforms).
TIBCO FTL® Development
70
Member applications and the group server are all within the same realm, and usually run on host
computers within a local area network.
The first member to join a group establishes heartbeat and timeout parameters for the entire group,
based on the activation interval property that the first member supplies in the join call. For consistent
behavior, ensure that all members of a group supply the same activation interval.
An application can join several groups. Nonetheless, an application must not join a group a second
time, that is, if it is already a member of that group.
Interactions within a Group
The join call establishes communication between a member and the group server. After the join call
returns successfully, the group library continues exchanging heartbeats with the server. (Heartbeats
and other group protocols are not visible to your program code.)
The leave call explicitly ends the stream of heartbeats from a member. The group server immediately
adjusts the ordinals of the remaining members.
Other events can implicitly interrupt the heartbeat stream. For example, the member process could
abruptly exit, or network segmentation could separate the member from the group server. In these
situations, the group server also adjusts the ordinals of the remaining members, but after a calculated
delay (see Activation Interval).
When a member’s ordinal changes, the group facility informs program code by raising an
advisory message. Programs subscribe to this advisory, and application callback code
must take appropriate action to change the member’s operating behavior.
ORDINAL_UPDATE
The group server tracks member heartbeats to determine the health of each member.
Individual members of a group do not exchange group protocol messages with one another, but only
with the group server.
Side Effects of Groups
Group protocol traffic consumes network bandwidth. With fewer than 10 members, using the default
activation interval, expect only minimal impact on message latency. More members or a smaller
activation interval can increase the impact.
Techniques for Programming with Groups
Program Structure for Groups
Programs using the group facility follow this template.
1. Determine the group name and property values.
(See also, Restrictions on Names.)
2. Subscribe to ordinal update advisories.
Content matchers can filter for these advisories by matching the string value ORDINAL_UPDATE in the
name field, and the group name in the group field.
The ordinal field contains the group member’s new ordinal.
The subscriber callback must change the operating role of the application process according to the
new ordinal.
3. Join the group, using the join API call.
4. Explicitly leave the group, using the leave API call.
Programs must leave all groups before closing the realm object.
TIBCO FTL® Development
71
Activation Interval
When a member becomes disconnected, the group facility revises the ordinals of the remaining
members, which respond by adjusting their operating roles. This process is not instantaneous: it takes
time to detect, to revise, and to adjust.
You can supply the activation interval property as a guide for the group server during the detect and
revise phases. The group server derives appropriate heartbeat and timeout intervals from this property,
aiming to complete these two phases within the activation interval you supply. That is, when a member
becomes disconnected, you can expect that all affected group members receive new ordinals in
approximately this time.
In contrast, the length of the adjust phase depends on the application, and the time it requires to switch
operating roles.
In the interim, the application processes as a group might miss some messages. You can implement
strategies to compensate for this possibility, as appropriate to application requirements.
If you omit the activation interval property, its default value is 5 seconds.
Disconnect
Ordinal -1 indicates that the group member is disconnected from the group server.
The group object automatically attempts to reconnect, and continues until the program explicitly
destroys the object. Meanwhile, the group server could reassign the member's previous ordinal to
another group member.
Appropriate program response depends on application requirements. For example, if it is not
acceptable for two members to share the role, the program should respond by entering an idle or
standby role. In contrast, if duplication of the role is acceptable, then the program could continue in
that role while waiting to reconnect. Alternatively, the program could log an error and exit.
Group Status
Group status advisories report the state of group members.
Group members and observers can subscribe to receive group status advisories.
The group library presents members and observers with group status advisories, which can have one of
three forms:
Total Status
A group status advisory that contains the group status of all existing member processes.
Change in Status
A group status advisory that contains the group status of a subset of members, including new
members that joined the group, members that left the group, or members that became disconnected.
Frequently, only one member at a time changes status, so the subset contains only that one member.
Server Unavailable
A group status advisory that indicates that the server is unavailable or unreachable. This form does
not contain the group status of any members.
When the state of the group changes, the group library presents members and observers with group
status advisories. The form of the advisory depends on both the member and state change:
●
When a new member joins a group, it receives a total status advisory, containing the status of all the
members, excluding observers. All the other members and observers receive a change in status
advisory.
When a disconnected member reconnects, this event results in the same set of status messages.
TIBCO FTL® Development
72
●
When a member leaves a group, it does not receive a status advisory. All the other members and
observers receive a change in status advisory.
●
When a member becomes disconnected from the group server, it receives a server unavailable
advisory. All the other members and observers also receive a change in status advisory.
●
When a new observer joins a group, the group state does not change. The new observer receives a
total status advisory, containing the status of all the other members, excluding any observers. Other
members and observers do not receive a status advisory.
●
When an observer leaves a group, or becomes disconnected from the group server, the group state does
not change. The affected observer does not receive a status advisory, nor do any other members or
observers.
For reference details about the group status advisory message, see GROUP_STATUS.
Group Observer
An application program can join a group as an observer. Observers can monitor the group by
subscribing to group status advisories, just as members can. However, the group server does not assign
ordinals to observers: observers do not participate in the functional roles of the group.
When an observer joins or leaves a group, or becomes disconnected from the group server, the state of
the group and its members does not change.
Programmer’s Checklist Addenda for Groups
The items in this topic supplement the checklist items in Information for Developers.
All Programming Languages
The realm administrator must configure the group server. The group server must be available to
application processes. (For details, see TIBCO FTL Administration.)
C Programmer’s Checklist
C programs must include the header file tibgroup/group.h.
On UNIX platforms, add the linker flag -ltibroup.
On Windows platforms, link the corresponding C library file tibgroup.lib, and run using
tibgroup.dll.
Java Programmer’s Checklist
Java programs must import the group package:
import com.tibco.ftl.group.*;
The CLASSPATH must include the lib directory, which must contain the archive file tibftlgroup.jar.
.NET Programmer’s Checklist
To simplify coding, programs can include this statement:
using TIBCO.FTL.GROUP;
The assembly TIBCO.FTL.GROUP.dll must be in the general assembly cache (GAC).
TIBCO FTL® Development
73
Persistence: Stores and Durables
Persistence is the potential to store a message between sending and receiving it.
The topics that follow present persistence, stores, and durables from an application developer’s
perspective. In particular, these topics focus on the modifications to programs that enable durable
subscribers and correct interaction with the persistence cluster.
For an intuitive introduction and terminology, see the chapter “Persistence (Stores and Durables)” in
TIBCO FTL Concepts.
For a more detailed explanation of store behavior and configuration, see TIBCO FTL Administration.
For advisories associated with persistence, see “Stores and Durables”.
For coordination between developers and administrators, see TIBCO FTL Durable Coordination Form.
Purposes of Persistence
The persistence infrastructure of stores and durables can serve three purposes: delivery assurance,
apportioning message streams, and last-value availability. These purposes correspond to three types of
durables: standard durables, shared durables, and last-value durables.
Delivery Assurance
An ordinary subscriber receives messages from a publisher only when a transport connects the
subscriber with that publisher. That is, an ordinary subscriber cannot receive a message through a
direct path transport unless both of these conditions hold at the time that the publisher sends the
message:
●
The subscriber object exists.
●
The transport is connected.
With persistence, subscribers can receive every message with high assurance, despite temporary lapses
in these conditions. For example, a persistence store can retain data for subscriber recovery after
application exit and restart, temporary network failure, or application host computer failure.
Stores can retain data indefinitely, until subscribers acknowledge delivery. (In contrast, even reliable
transports retain data only for a finite reliability interval.)
For delivery assurance, use standard durables. Standard durables serve one subscriber at a time, and
assure that it can receive the whole message stream.
Apportioning Message Streams
In some situations it is convenient to apportion a message stream among a set of cooperating
subscribers so that only one subscriber receives and processes each message, but acting together the
subscribers process every message in the stream.
For apportioning message streams, use shared durables.
Last-Value Availability
When new subscribers need to receive the current state immediately, but do not need to receive a
complete historical message stream, a persistence store can supply the most recent message (that is, the
last value in the message stream).
The store continues to forward subsequent messages to subscribers, discarding the previous message as
each new message arrives.
For last-value availability, use last-value durables. Last-value durables can serve many subscribers.
TIBCO FTL® Development
74
A last-value durable divides its input message stream into distinct output streams based on the value of
a distinguished key field. In this way, one last-value durable holds more than one last value: one for
each key.
Basic Definitions for Persistence
Store
A data structure that collects a stream of messages.
Durable
A data structure within a store that represents subscriber interest, holds messages for a specific
subscriber identity, and tracks acknowledgments as a subscriber object consumes those messages.
Each store can contain many durables.
A durable can exhibit one of three behavior types: standard, shared, or last-value (see the definitions that
follow).
Independent of its behavior type, a durable can exist either as static or dynamic (see the definitions that
follow).
Standard Durable
A durable that represents the interest of one subscriber object, strengthening delivery assurance for
that subscriber.
Shared Durable
A durable that represents the identical interest of two or more cooperating subscriber objects,
apportioning a message stream among those subscribers.
Last-Value Durable
A durable that represents the interest of potentially many subscriber objects. It stores only the most
recent message from one or more message streams.
Alternatively, a last-value durable can support the map API. Applications can use the map API to
store a key/value pair, or get the current value of a key.
Static Durable
A durable that the administrator defines as part of the store definition. It exists in the store and
expresses interest in its message stream even before an application subscribes to it.
Dynamic Durable
A durable that an application creates at run time. The store creates it dynamically when an application
subscribes to it. It expresses interest in a message stream only from the moment of first subscription. It
continues to express interest until a program or an administrator explicitly deletes it from the store.
Dynamic Durable Template
An administrative definition that supplies parameters for a set of dynamic durables.
Durable Subscribers
A durable subscriber is a subscriber object in an application process that maintains its identity even if the
process exits and restarts. It can receive messages from a durable in a persistence store.
A durable is a data structure within a store. Within a store, each durable has a unique name.
When a program creates a subscriber object, it can link that subscriber to a durable in either of two
ways:
Durable Name
The program supplies a durable name in the create subscriber call. This name is a request to link the
subscriber with a specific durable.
TIBCO FTL® Development
75
If a durable with that name already exists, the subscriber links to that durable.
Otherwise, the store dynamically creates a durable with that name, and the subscriber links to that
new durable. (Pre-requisite: The administrator has enabled dynamic durables.)
Subscriber Name
Within an application instance, the administrator defines a mapping from subscriber names to
durable names. The program supplies a subscriber name in the create subscriber call, and the
mapping determines the durable for the subscriber.
The durable must already exist: that is, the administrator must define it as a static durable.
For flexibility, design applications can obtain their durable names and subscriber names from an
external source, such as a command line argument or configuration file. Do not hard-code these names
into application programs..
Developers and administrators coordinate the details of durable subscribers (see TIBCO FTL Durable
Coordination Form).
Standard Durable Reference
A standard durable strengthens delivery assurance for a subscriber.
Quality of Service
A standard durable ensures that every message is received and acknowledged by its subscriber.
If the subscriber does not acknowledge a message, the store retains the message, and the subscriber
automatically recovers the message.
Message Retention
A standard durable retains each message until its subscriber acknowledges it.
Subscribers
A standard durable can serve at most one subscriber at a time. That subscriber receives the entire
message stream.
If a standard durable already serves a subscriber object in one client process, and another client process
creates a subscriber that connects to the same standard durable, then the store resolves collisions in
favor of the more recent subscriber, deactivating the older durable subscriber (see “.”
If a subscriber to a standard durable already exists within a client process, and the same client process
subsequently attempts to create another subscriber on the same standard durable, that subscriber create
call fails.
Direct Path
Administrators must configure a direct path from publisher to subscriber. A standard durable provides
a parallel path though the persistence server, which adds an intermediary hop. This durable path is
only for recovering missed messages (see “Stores for Delivery Assurance” in TIBCO FTL
Administration).
Content Matcher
A standard durable accepts, but does not require, a content matcher.
If it has a content matcher, then the subscriber must specify either an identical content matcher, or no
content matcher.
TIBCO FTL® Development
76
Acknowledgements
A standard durable tracks acknowledgements from subscribers.
Dynamic Durable
Before a program can create a dynamic standard durable, the administrator must have already enabled
standard dynamic durables on the endpoint (see “Enabling a Dynamic Durable” and “Dynamic
Durable Template Definition Reference,” both in TIBCO FTL Administration).
When a program creates a dynamic standard durable, it must supply the following information in the
subscriber create call:
●
Endpoint Name.
●
Durable Name.
●
Optional. Content Matcher.
When creating a new dynamic durable, the content matcher becomes part of the new durable. The
content matchers of subsequent subscribers to the durable must be identical.
If a durable with the specified durable name already exists, that durable forwards messages to the new
subscriber.
If a durable with the specified durable name does not yet exist, the store creates a dynamic durable
using the durable name supplied in the subscriber create call.
Static Durable
Before a program can subscribe to a static durable, the administrator must have already defined that
durable in the store associated with the endpoint (see “Defining a Static Durable” and “Durable
Definition Reference,” both in TIBCO FTL Administration).
When a program subscribes to a static standard durable, it must supply the following information in
the subscriber create call:
●
Endpoint Name
●
Durable Name or Subscriber Name
To understand this distinction, see “Durable Subscribers.”
●
Optional: Content Matcher
The content matcher must either be null, or be identical to the content matcher of the durable as
configured by the administrator. The best practice is to supply null.
Shared Durable Reference
A shared durable apportions a message stream among its subscribers.
Quality of Service
A shared durable ensures that every message is received and acknowledged by a subscriber. Each
subscriber receives a portion of the input message stream. Together, the subscribers receive the entire
message stream.
If a subscriber does not acknowledge a message, the durable can redeliver it to another subscriber.
Message Retention
A shared durable retains each message until a subscriber acknowledges it.
TIBCO FTL® Development
77
Subscribers
A shared durable can support multiple subscribers simultaneously.
Each subscriber receives a portion of the message stream.
Direct Path
Subscribers receive messages only through the store. Administrators must not configure direct paths
from publishers to subscribers.
Content Matcher
A shared durable accepts, but does not require, a content matcher.
If it has a content matcher, then every subscriber must specify either an identical content matcher, or no
content matcher.
Acknowledgements
A shared durable tracks acknowledgements from subscribers.
Dynamic Durable
Before a program can create a dynamic shared durable, the administrator must have already enabled
shared dynamic durables on the endpoint (see “Enabling a Dynamic Durable” and “Dynamic Durable
Template Definition Reference,” both in TIBCO FTL Administration).
When a program creates a dynamic shared durable, it must supply the following information in the
subscriber create call:
●
Endpoint Name.
●
Durable Name.
●
Optional. Content Matcher.
When creating a new dynamic durable, the content matcher becomes part of the new durable. The
content matchers of subsequent subscribers to the durable must be identical.
If a durable with the specified durable name already exists, that durable forwards messages to the new
subscriber.
If a durable with the specified durable name does not yet exist, the store creates a dynamic durable
using the durable name supplied in the subscriber create call.
Static Durable
Before a program can subscribe to a static durable, the administrator must have already defined that
durable in the store associated with the endpoint (see “Defining a Static Durable” and “Durable
Definition Reference,” both in TIBCO FTL Administration).
When a program subscribes to a static shared durable, it must supply the following information in the
subscriber create call:
●
Endpoint Name.
●
Durable Name or Subscriber Name.
To understand this distinction, see “Durable Subscribers.”.
●
Optional. Content Matcher.
The content matcher must either be null, or be identical to the content matcher of the durable. The
best practice is to supply null.
TIBCO FTL® Development
78
Last-Value Durable Reference
A last-value durable preserves only the most recent message for subscribers. It does not track message
acknowledgements from subscribers.
Quality of Service
A last-value durable divides its input message stream into output sub-streams based on the value of a
key field in each message. For each sub-stream, the durable stores the most recent message.
A last-value durable ensures that every new subscriber immediately receives the most recent message,
if one is stored. The subscriber continues to receive the sub-stream of subsequent messages until the
subscriber closes, but without any assurance of delivery.
Message Retention
A last-value durable retains only one message for each output sub-stream.
Subscribers
A last-value durable can support multiple subscribers simultaneously.
Each subscriber can receive exactly one output sub-stream.
Direct Path
Subscribers receive messages only through the store. Administrators must not configure direct paths
from publishers to subscribers.
Content Matcher
A last-value durable requires a content matcher.
The content matcher of the durable must include {key_field_name:true}. That is, the content
matcher ensures that messages in the input stream contain the key field. For dynamic durables, the
content matcher automatically satisfies this requirement.
The content matcher of each subscriber must include {key_field_name:key_value}. That is, each
subscriber must request exactly one output sub-stream.
Notice that the content matchers of the subscribers are independent of one another, and also
independent of the durable's matcher. Nonetheless, all these content matchers must test the same key
field.
Acknowledgements
A last-value durable does not track acknowledgements from subscribers.
Unlike standard and shared durables, a subscriber to a last-value durable subscriber does not consume
messages from the durable. Instead, new subscribers to a sub-stream continue to receive the stored
value until a publisher sends a new value, which replaces it.
Dynamic Durable
Before a program can create a dynamic last-value durable, the administrator must have already enabled
last-value dynamic durables on the endpoint (see “Enabling a Dynamic Durable” and “Dynamic
Durable Template Definition Reference,” both in TIBCO FTL Administration).
When a program creates a dynamic last-value durable, it must supply the following information in the
subscriber create call:
●
Endpoint Name
TIBCO FTL® Development
79
●
Durable Name
●
Key Field Name
When creating a new dynamic durable, the key field name becomes part of its content matcher.
●
Content Matcher
When creating a new dynamic durable, the content matcher becomes part of the new durable.
If a durable with the specified durable name and key field name already exists, that durable forwards
messages to the new subscriber.
If a durable with the specified durable name does not yet exist, the store creates a dynamic durable
using the durable name, key field name, and content matcher supplied in the subscriber create call.
For example, suppose the store does not yet contain a durable named ticker. A program then creates a
subscriber to a last-value durable named ticker, with key field name Symbol and content matcher
{"Symbol":"IBM","Exchange":"NYSE"}. In response, the store creates a new dynamic durable named
ticker, with content matcher {"Symbol":true,"Exchange":"NYSE"}. That is, the new durable
generalizes from the key field name to a content matcher clause that tests for the presence of the key
field rather than a specific value, and integrates the rest of the clauses from the subscriber’s content
matcher.
If the create subscriber call does not supply a content matcher, the new durable uses only the key field
clause as its content matcher.
Subsequent subscribers to the durable must specify compatible content matchers: that is, they must be
identical except for the key field value, which can be different. A subscriber create call with an
incompatible content matcher throws an exception.
Static Durable
Before a program can subscribe to a static durable, the administrator must have already defined that
durable in the store associated with the endpoint (see “Defining a Static Durable” and “Durable
Definition Reference,” both in TIBCO FTL Administration).
When a program subscribes to a static last-value durable, it must supply the following information in
the subscriber create call:
●
Endpoint Name
●
Durable Name or Subscriber Name
To understand this distinction, see “Durable Subscribers.”
●
Content Matcher
The content matcher must include a test for a specific value of the key field: that is, it must express
interest in a sub-stream of the last-value durable, as determined by a specific key string.
Acknowledgment of Message Delivery
A durable subscriber can acknowledge consuming a message to its durable in either of two ways.
Automatic Acknowledgment
With automatic acknowledgment, the base library automatically acknowledges the message when the
application callback returns. This choice is appropriate when an application’s callback completely
processes the inbound message and then returns.
Explicit Acknowledgment
With explicit acknowledgment, the application program must use the acknowledge call to explicitly
acknowledge each message. This choice is appropriate when an application’s callback delegates
TIBCO FTL® Development
80
processing of the inbound message to a separate thread. It could also be appropriate if the application
must verify the success of each acknowledgment.
To enable explicit acknowledgment, programs pass a property to the subscriber create call. Otherwise,
the default behavior is automatic acknowledgment.
Note that the choice between these two mechanisms for acknowledging messages is orthogonal to the
administrator’s choice of acknowledgment mode: synchronous versus asynchronous.
Acknowledgment is not relevant with last-value durables.
Message Delivery Behavior
Duplicate Delivery
While stores and durables can strengthen delivery assurance, they also introduce the possibility of
duplicate delivery. Application developers must design subscribing programs to process duplicate
messages gracefully.
Message Order
A store preserves message order within each of its publisher streams. That is, if a publisher sent
message M1 before message M2, then the store delivers M1 before M2. Every subscriber that attempts
to recover both messages receives them in the correct order.
However, a store that merges message streams from two or more publishers does not preserve global
order among its publisher streams. That is, if publisher A sent message A1 before publisher B sent
message B2, the store could deliver these messages in either order. Furthermore, two subscribers S and
T that recover these two messages could receive them in a different order: S receiving A1 first, and T
receiving B2 first.
Maximum Message Size
When an endpoint is associated with a store, limit the maximum size of messages to 10MB each.
Messages that exceed the environment’s maximum message size could disrupt the quorum of
persistence servers, and prevent them from reforming a quorum.
Persistence servers and quorums are the responsibility of administrators, so developers generally do
not need to know about them. Nonetheless, developers must understand that sending messages that
exceed this maximum size limit could disrupt executable components.
The actual maximum can vary depending on network and server hardware. To determine the actual
maximum, test empirically in each deployment environment.
Programmer’s Checklist Addenda for Stores and Durables
This topic provides a checklist for programmers using stores and durables.
The following items supplement the checklist items in Information for Developers.
All Programming Languages
●
Ensure that the library load path includes the location of the most recent TIBCO FTL libraries before
the locations of any older TIBCO FTL releases.
●
The realm administrator must configure the store cluster and its servers. The tibstore servers must
be available to application processes. (For details, see TIBCO FTL Administration.)
TIBCO FTL® Development
81
Minimum Release
For best results, use the most recent release. Nonetheless, when using an older release, ensure that it
includes the persistence features that the applications require.
Persistence Feature
Minimum Release
Dynamic Durables
4.2
Last-Value Durables
Key/Value Maps
Apportion Message Streams
4.0
Delivery Assurance
3.1
TIBCO FTL® Development
82
Key/Value Maps
Programs can use maps to store key/value pairs in a persistence store.
A map behaves like a simple database table with two columns: key and value. The key is a string, and
the value is a message.
Programs assign a name to each map. A store may contain many maps, each with a unique name.
API methods can do these operations:
●
Create a map.
●
Set a key/value pair.
●
Get a key's value.
●
Remove a key/value pair.
●
Iterate over all the key/value pairs in a map.
●
Close a map object.
●
Delete a map from the store.
In addition, most of these methods are available as locked operations. That is, you can use a lock to
ensure that map operations in different processes do not interfere with one another (see Locks).
In order for a program to use maps, administrators must enable dynamic last-value durables in a
separate persistence store. For more information, see “Enabling Maps” in TIBCO FTL Administration.
Locks
Cooperating application programs can use a lock to implement exclusive access to a map within the
persistence cluster. Locks can prevent interference among the application processes that access a map.
Lock Name
When a program creates a lock object, it assigns a lock name. The persistence cluster may contain many
locks, each with a unique name. Two lock objects with the same name represent the same lock, so two
or more application processes can use the lock to cooperate.
Programmers choose the name of a lock to indicate the purpose of the lock: for example,
ServerStatusMapLock might lock an entire map that stores the states of server hardware within an
enterprise, while BlueLock might lock the row of that map that describes the state of the server named
Blue.
Methods of Lock Objects
API methods can do these operations:
●
Create a lock.
●
Request a lock from the persistence cluster.
●
Return a lock that the process holds.
●
Steal a lock that another process holds.
●
Destroy a lock object to reclaim resources.
Methods with Locks and without Locks: Effective Use
Map operations are available in two forms: with lock and without lock. Methods that take a lock
argument respect the state of that lock: that is, if another process holds the lock, then the method
throws an exception and does not complete its map operation.
TIBCO FTL® Development
83
However, methods that do not take a lock argument do not respect the state of any lock: even if another
process holds a lock for the map or for the key row, the method does not test the lock, and completes its
map operation.
For locks to effectively prevent interference, all your application processes must access the map using
only methods with locks.
Pattern for Programming with Locks
1. Create a lock object.
2. Request the lock.
3. Call a method with that lock.
Alternatively, a program can call many methods with that lock, even within a loop, as with a map
iterator.
If the process still holds the lock at the end of an operation, the method succeeds. Otherwise it
throws an exception.
4. Return the lock.
A program can re-use a lock object, omitting step 1.
Steal: Only to Circumvent a Blocked Lock
If a program process, A, holds a lock and does not return it in a timely fashion, the corresponding map
or row remains inaccessible to other process that request that lock. To circumvent this blockage,
another program process, B, can steal the lock.
When process A subsequently uses that lock in a map method call, the method throws an exception.
TIBCO FTL® Development
84
Direct Publishers and Subscribers
Direct publishers and subscribers use direct memory access to achieve the fastest data transfer and
lowest latency.
A publishing application writes data directly into memory that is accessible to subscribing applications.
Subscribing applications read data directly from memory written by the publishing application.
The implementation minimizes or eliminates sources of latency.
The following table summarizes the differences between regular and direct publishers and subscribers.
Subsequent topics contain greater detail.
Aspect
TIBCO FTL Publishers and
Subscribers
Direct Publishers and Subscribers
Messages
Applications exchange message objects.
Applications exchange data in buffers.
Structuring
Data
Applications structure message objects
using fields that contain typed data.
Applications structure data within
buffers using an array of sizes.
Copying Data
The library copies message data as
needed.
The library eliminates copying data
wherever possible. The sending
application populates a data buffer, and
receiving applications have direct access
to that same data buffer.
Memory
Management
Applications can create and destroy
publisher and subscriber objects.
Applications create direct publisher and
subscriber objects, but cannot reclaim
their memory.
The library and application programs
can both create and destroy message
objects.
Application programs neither allocate
data buffers, nor free them.
Subscribers
and Threads
Subscribers are thread-safe.
Applications must not use a direct
subscriber in more than one thread.
Instead, applications can create a
separate direct subscriber for each
thread.
Delivery
The library distributes inbound message
through event queues.
Applications dispatch inbound data
buffers directly to callback methods.
Content
Matchers
Applications can use content matchers
to select a sub-stream of messages.
Applications receive the entire data
stream. Selectivity based on data
content is not available.
API Language
Support
The API supports multiple
programming languages.
The API supports only the C language.
Protection
The implementation protects against
many common types of programming
errors.
The implementation protects against
fewer types of errors. For example,
programmers must be careful to not
overrun the length of data buffers,
because the library does not guard
against this error.
TIBCO FTL® Development
85
TIBCO FTL Publishers and
Subscribers
Direct Publishers and Subscribers
Publishers
Many publishers can send through an
endpoint.
A direct shared memory bus supports
only one direct publisher object.
Transport
A variety of transports are available.
Only a direct shared memory transport
can implement a direct publisher or
subscriber endpoint.
Persistence
Available.
The persistence feature does not
support direct publishers and
subscribers.
Aspect
Use Cases for Direct Publishers and Subscribers
Direct publishers and subscribers are appropriate only in very specialized use cases in which a few
nanoseconds of latency can make a critical difference.
Direct publishers and subscribers are less flexible than regular TIBCO FTL communications. Direct
publishers omit several features in exchange for greater speed and lower latency:
●
The implementation has fewer protections against incorrect use of the API calls. For example, it
does not check arguments nor data types. The implementation does not protect against writing
beyond buffer boundaries.
●
Data is in buffers, rather than in messages with typed fields.
●
Event queues are not available.
●
Content matchers are not available.
●
Persistence is not available.
●
C is the only supported programming language.
Direct shared memory transports support only one direct publisher per bus. This restriction precludes
the request/reply pattern, which requires two-way communication. Nonetheless, you could use a
separate bus for replies.
Programming with Direct Publishers
Create a direct publisher object. Code a reserve-fill-send loop. Close the direct publisher and exit.
Number of Publisher Objects
A suite of application processes that communicate over a direct shared memory bus may contain only
one direct publisher object at a time. It is the shared responsibility of the application developers and the
administrators to ensure this condition.
One Reserved Buffer
A direct publisher can reserve at most one buffer at a time.
●
If direct publisher has already reserved a buffer in one thread, any subsequent reserve calls in other
threads block until the direct publisher has sent the reserved buffer.
●
Do not call reserve twice within the same thread without an intervening send call.
TIBCO FTL® Development
86
The Reserve-Fill-Send Loop
Avoid delays in the reserve-fill-send loop: as soon as the reserve call returns a buffer, fill it with data,
and send it.
Procedure
1. Create a direct publisher object.
The object will exist in memory until the process terminates.
Programs may use a direct publisher in multiple threads. However, contention to reserve a buffer
can decrease performance and increase latency.
The reserve-fill-send loop begins here.
2. Reserve a buffer.
Supply the total size of the data, and the number of data elements.
The reserve call returns a pointer to the buffer.
If the program specifies more than one data element, the reserve call also yield a size array.
One reserve call can reserve a maximum block of 64 kilobytes. The data buffer and the size
array must fit together within that maximum block.
3. Fill the buffer with data.
If another thread has already reserved a buffer with this direct publisher, this reserve call blocks
until that other thread sends its buffer.
●
One Data Element: Write the data into the buffer.
●
Multiple Data Elements: Use a loop to write each data element into the buffer, and its
corresponding size, in bytes, into the size array.
4. Send the reserved buffer.
The send reserved call makes the buffer available to direct subscribers.
After this call, the direct publisher is ready to reserve another buffer.
5. Loop to reserve the next buffer.
Clean up before the application process exits.
6. Close the direct publisher object.
Closing a direct publisher causes any blocked reserve calls to return. Closing also invalidates the
direct publisher, which disallows any subsequent method calls.
However, closing a direct publisher does not free its memory.
Programming with Direct Subscribers
Create a direct subscriber object. Code a callback method. Code a dispatch loop. Close the direct
subscriber.
Procedure
1. Code a direct callback method.
Within the callback, loop to unpack the data items.
Avoid introducing latency within the callback.
Programs can use the same callback with more than one direct subscriber object, and in more than
one thread.
TIBCO FTL® Development
87
2. Create a direct subscriber object.
The object will exist in memory until the process terminates.
Programs may use a direct subscriber in multiple threads. However, contention to dispatch a direct
subscriber object can decrease performance and increase latency.
3. Code a dispatch loop for the direct subscriber.
A dispatch loop repeatedly calls the dispatch method.
The dispatch method checks whether inbound data is available for a direct subscriber object.
●
Data - If a data buffer is available, dispatch invokes the callback method, passing the buffer and
a closure object as arguments to the callback. When the callback returns, the direct subscriber
automatically acknowledges that it has received the buffer. Then the dispatch call returns.
●
No Data - If a data buffer is not available, dispatch waits until data becomes available, or until
the timeout expires.
You can supply a closure object that is specific to the direct subscriber object, or you can supply a
global closure object common to more than one direct subscriber.
Clean up before the application process exits.
4. Close the direct subscriber object.
Closing a direct subscriber causes any executing dispatch calls to return immediately. Closing also
invalidates the direct subscriber, which disallows any subsequent method calls.
However, closing a direct subscriber does not free its memory.
Multithreading with Direct Publishers and Subscribers
On hardware with multiple processor cores, multithreading can boost performance of applications that
communicate using direct publishers and direct subscribers. You can use multithreading to implement
a variety of communicating sub-applications within a single process, and to decrease context-switching
latency as they communicate.
For best results, match the size of a multithreaded application program to the host computer hardware.
Allot one processor core for each direct publisher and its reserve-fill-send loop, and one processor core
for each direct subscriber object and its dispatch loop. Too few cores can increase latency.
A suite of application processes that communicate over a direct shared memory bus may contain only
one direct publisher object at a time. It is the shared responsibility of the application developers and the
administrators to ensure this condition.
Multiple Direct Subscribers
A program can create more than one direct subscriber on an endpoint. Each direct subscriber object
receives every buffer published on the bus.
●
You can use multiple direct subscribers to process the same inbound data stream with different
callback semantics.
●
You cannot use multiple direct subscribers to increase throughput by dividing an inbound data
stream.
In multithreaded application programs, use a separate direct subscriber object and a separate dispatch
loop in each thread.
For best results, if an application program uses more than one direct subscriber object, create them all
before starting the any of their dispatch loops.
TIBCO FTL® Development
88
Programs may use a direct subscriber in multiple threads. However, contention to dispatch a direct
subscriber object can decrease performance and increase latency.
Create only a finite number of direct subscriber objects. Re-use them as needed. Close them only when
cleaning up to prepare for the process to exit.
TIBCO FTL® Development
89
Package Contents
Directory Structure Reference
The TIBCO FTL installation directory contains the subdirectories in this table.
TIBCO FTL Directories
Directory
Description
bin
DLL files (for Windows).
Scripts to run the realm server and its administration utility.
Python scripts and library.
Transport bridge executable.
Store server executable.
Realm server .jar file.
Jetty web server .jar file.
include
C API header files (in subdirectories).
lib
UNIX library files.
Java .jar files.
samples
Sample programs. For more detail, see Sample Programs Reference.
Sample Programs Reference
Sample programs serve as models for your own programs. You can use sample programs to
experiment with TIBCO FTL software, test for correct installation, and demonstrate performance in
your network environment.
Sample Programs
These tables describe some of the sample programs, however, the list is not exhaustive. For descriptions
of other sample programs, see the readme files in each directory.
Each sample program prints a usage summary in response to the -h command line option.
Sample Programs for One-to-Many Communication
Programs
Description
tibrecv
tibrecv
creates a subscriber and outputs the messages it receives.
Start this program first.
tibsend
tibsend
publishes messages for tibrecv.
TIBCO FTL® Development
90
Sample Programs for One-to-One Communication
Programs
Description
tibreply
tibreply
creates a subscriber, and replies to request messages it receives.
Start this program first.
tibrequest
creates an inbox subscriber, sends request messages to tibreply, and
receives replies at its inbox.
tibrequest
Files
Files in Samples Directory
File
Description
readme.txt
Instructions to compile and run sample programs.
setup
Script that defines environment variables for the samples, such as PATH,
LD_LIBRARY_PATH and CLASSPATH. Start with this script.
Directories
Samples Directories
Directory
Description
bin
Executable sample programs, precompiled from C sources.
scripts
Sample scripts to start and stop the realm server. You must start the realm server
with this script before running the sample programs.
Sample configuration file for the realm server.
The file readme.txt contains instructions for using these samples.
src
Sample program source code in C, Java, and .NET. You may use these samples as
models for your application programs.
The file readme.txt contains instructions for compiling.
jaas
Files that configure JAAS authentication and authorization for the sample scripts.
To use JAAS with the samples, supply the -jaas flag to the sample scripts.
config
More sample configuration files, for use as instructional models, but not related to
the sample programs.
TIBCO FTL® Development
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement