Tibco Rendezvous 8.1 Java Reference

TIBCO Rendezvous®
Java Reference
Software Release 8.1
April 2008
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 TIBCO Rendezvous Installation) 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.
TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, Rendezvous and TIBCO
Rendezvous are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or
other countries.
EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. 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.TXT 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 © 1997–2008 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
| iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Chapter 1 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Implementations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Strings and Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Interrupting Event Dispatch Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Rendezvous Daemon and Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Java Applications and Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Security versus Efficiency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Starting rvd Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Starting rva . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Browser Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Network Overview—rvd Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Network Overview—rva Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Internet Web Site Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Rendezvous Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Home Computer and Port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
HTTP Tunneling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Isolate External from Internal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Intranet Web Site Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Rendezvous Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
JNI Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
rvd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 2 Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
TIBCO Rendezvous Java Reference

iv
| Contents
Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Archive Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Shared Library Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 3 Rendezvous Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Tibrv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Tibrv.close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Tibrv.defaultQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Tibrv.getErrorCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Tibrv.getVersion() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Tibrv.isNativeImpl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Tibrv.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Tibrv.open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Tibrv.processTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Tibrv.setErrorCallback() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
TibrvSdContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
TibrvSdContext.setDaemonCert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
TibrvSdContext.setUserCertWithKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
TibrvSdContext.setUserCertWithKeyBin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
TibrvSdContext.setUserNameWithPassword() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Chapter 4 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Field Names and Field Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Finding a Field Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
TibrvMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
TibrvMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
TibrvMsg.add(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Add Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
TibrvMsg.addField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
TibrvMsg.get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Get Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
TibrvMsg.getAsBytes(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
TibrvMsg.getByteSize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
TibrvMsg.getField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
TibrvMsg.getFieldByIndex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
TibrvMsg.getFieldInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
TibrvMsg.getNumFields(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
TibrvMsg.getReplySubject(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
TibrvMsg.getSendSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
TibrvMsg.getStringEncoding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Contents v
|
TibrvMsg.getTypeName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
TibrvMsg.removeField() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
TibrvMsg.removeFieldInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
TibrvMsg.reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
TibrvMsg.setReplySubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
TibrvMsg.setSendSubject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
TibrvMsg.setStringEncoding(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
TibrvMsg.toString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
TibrvMsg.update(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Update Scalar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TibrvMsg.updateField(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
TibrvMsgField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
TibrvMsgField(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
TibrvMsgField.toString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
TibrvDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
TibrvDate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
TibrvDate.getTimeNanoseconds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
TibrvDate.getTimeSeconds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
TibrvDate.setTime() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
TibrvIPAddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
TibrvIPAddr(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
TibrvIPAddr.getAddr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
TibrvIPAddr.getAsBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
TibrvIPAddr.getAsString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
TibrvIPPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
TibrvIPPort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
TibrvIPPort.getPort(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
TibrvIPPort.getAsBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
TibrvXml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
TibrvXml() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
TibrvXml.getBytes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Chapter 5 Events and Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

TibrvEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
TibrvEvent.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
TibrvEvent.getClosure() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
TibrvEvent.getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
TibrvEvent.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
TibrvListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
TibrvListener(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
TibrvListener.getSubject(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
TibrvListener.getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

vi
| Contents
TibrvMsgCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
TibrvMsgCallback.onMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
TibrvTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
TibrvTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
TibrvTimer.getInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
TibrvTimer.resetInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
TibrvTimerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
TibrvTimerCallback.onTimer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
TibrvDispatchable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
TibrvDispatchable.dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
TibrvDispatchable.poll() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
TibrvDispatchable.timedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
TibrvQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
TibrvQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
TibrvQueue.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
TibrvQueue.dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
TibrvQueue.getCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
TibrvQueue.getDiscardAmount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
TibrvQueue.getLimitPolicy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
TibrvQueue.getMaxEvents() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
TibrvQueue.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
TibrvQueue.getPriority(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
TibrvQueue.isDefault(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
TibrvQueue.isValid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
TibrvQueue.poll() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
TibrvQueue.setName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
TibrvQueue.setLimitPolicy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
TibrvQueue.setPriority(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
TibrvQueue.timedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
TibrvQueueGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
TibrvQueueGroup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
TibrvQueueGroup.add(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
TibrvQueueGroup.contains() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
TibrvQueueGroup.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
TibrvQueueGroup.dispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
TibrvQueueGroup.elements() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
TibrvQueueGroup.getCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
TibrvQueueGroup.isValid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
TibrvQueueGroup.poll() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
TibrvQueueGroup.remove(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
TibrvQueueGroup.timedDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
TibrvDispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
TibrvDispatcher() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Contents vii
|
Chapter 6 Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

TibrvTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
TibrvTransport.createInbox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
TibrvTransport.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
TibrvTransport.isValid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
TibrvTransport.getDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
TibrvTransport.send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
TibrvTransport.sendReply() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
TibrvTransport.sendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
TibrvTransport.setDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
TibrvProcessTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
TibrvNetTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
TibrvRvaTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
TibrvRvaTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
TibrvRvaTransport.getHostName(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
TibrvRvaTransport.getHttpReconnectDelay(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
TibrvRvaTransport.getPort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
TibrvRvaTransport.isHttpTunneling() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
TibrvRvaTransport.setHttpReconnectDelay() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
TibrvRvdTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
TibrvRvdTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
TibrvRvdTransport.getDaemon() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
TibrvRvdTransport.getNetwork(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
TibrvRvdTransport.getService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
TibrvRvdTransport.setBatchMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Chapter 7 Virtual Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

TibrvVcTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
TibrvVcTransport.createAcceptVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
TibrvVcTransport.createConnectVc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
TibrvVcTransport.getConnectSubject(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
TibrvVcTransport.waitForVcConnection(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Chapter 8 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Fault Tolerance Road Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
TibrvFtMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
TibrvFtMember() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
TibrvFtMember.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
TibrvFtMember.getActivationInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
TibrvFtMember.getActiveGoal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
TibrvFtMember.getGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
TibrvFtMember.getHeartbeatInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

viii
| Contents
TibrvFtMember.getPreparationInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
TibrvFtMember.getQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
TibrvFtMember.getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
TibrvFtMember.getWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
TibrvFtMember.isValid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
TibrvFtMember.setWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
TibrvFtMemberCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
TibrvFtMemberCallback.onFtAction() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
TibrvFtMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
TibrvFtMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
TibrvFtMonitor.destroy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
TibrvFtMonitor.getGroupName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
TibrvFtMonitor.getTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
TibrvFtMonitorCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
TibrvFtMonitorCallback.onFtMonitor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Chapter 9 Certified Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

TibrvCmListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
TibrvCmListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
TibrvCmListener.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
TibrvCmListener.confirmMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
TibrvCmListener.isExplicitConfirm() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
TibrvCmListener.setExplicitConfirm(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
TibrvCmTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
TibrvCmTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
TibrvCmTransport.addListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
TibrvCmTransport.allowListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
TibrvCmTransport.connectToRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
TibrvCmTransport.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
TibrvCmTransport.disallowListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
TibrvCmTransport.disconnectFromRelayAgent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
TibrvCmTransport.expireMessages(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
TibrvCmTransport.getDefaultTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
TibrvCmTransport.getLedgerName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
TibrvCmTransport.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
TibrvCmTransport.getRelayAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
TibrvCmTransport.getRequestOld(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
TibrvCmTransport.getSyncLedger(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
TibrvCmTransport.getTransport(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
TibrvCmTransport.removeListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
TibrvCmTransport.removeSendState() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
TibrvCmTransport.reviewLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
TibrvCmTransport.send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Contents ix
|
TibrvCmTransport.sendReply(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
TibrvCmTransport.sendRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
TibrvCmTransport.setDefaultTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
TibrvCmTransport.setPublisherInactivityDiscardInterval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
TibrvCmTransport.syncLedger() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
TibrvCmReviewCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
TibrvCmReviewCallback.onLedgerMsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
TibrvCmMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
TibrvCmMsg.getSender() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
TibrvCmMsg.getSequence(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
TibrvCmMsg.getTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
TibrvCmMsg.setTimeLimit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Chapter 10 Distributed Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

TibrvCmQueueTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
TibrvCmQueueTransport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
TibrvCmQueueTransport.destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
TibrvCmQueueTransport.getCompleteTime(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
TibrvCmQueueTransport.getUnassignedMessageCount(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
TibrvCmQueueTransport.getWorkerWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
TibrvCmQueueTransport.getWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
TibrvCmQueueTransport.setCompleteTime(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
TibrvCmQueueTransport.setTaskBacklogLimit...() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
TibrvCmQueueTransport.setWorkerWeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
TibrvCmQueueTransport.setWorkerTasks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Chapter 11 Exceptions and Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

TibrvException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
TibrvException.printStackTrace() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
TibrvStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
TibrvErrorCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
TibrvErrorCallback.onError(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Appendix A Custom Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

TibrvMsg.getDecoder() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
TibrvMsg.getEncoder() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
TibrvMsg.setHandlers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
TibrvMsgDecoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
TibrvMsgDecoder.decode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
TibrvMsgEncoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
TibrvMsgEncoder.canEncode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
TibrvMsgEncoder.encode(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

x
| Contents
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

| xi
Figures
Figure 1 Java Programs with rvd Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Figure 2 Java Programs with rva Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Figure 3 HTTP Tunneling to the Web Server Host. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Figure 4 HTTP Tunneling to a Separate rva Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Figure 5 Java to Wire Format Datatype Conversion Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Figure 6 Wire Format to Java Datatype Conversion Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Figure 7 Listener Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Figure 8 Timer Activation and Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

xii
| Figures

| xiii
Tables
Table 1 Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Table 2 Archive Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Table 3 Environment Variables for Shared Library Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 4 Datatype Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Table 5 Date and Time Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

xiv
| Tables

| xv
Preface
This manual describes the TIBCO Rendezvous® API for Java programmers. It is
part of the documentation set for Rendezvous Software Release 8.1.
Topics
• Manual Organization, page xvi

• Related Documentation, page xvii
• How to Contact TIBCO Customer Support, page xix

xvi
| Preface
Manual Organization
The organization of this book mirrors the underlying object structure of the
Rendezvous Java API. Each chapter describes a group of closely related objects
and their methods.
Within each chapter, methods are grouped with their objects.

|
Related Documentation xvii
Related Documentation
This section lists documentation resources you may find useful.
TIBCO Product Documentation

The following documents form the Rendezvous documentation set:
• TIBCO Rendezvous Concepts
Read this book first. It contains basic information about Rendezvous
components, principles of operation, programming constructs and
techniques, advisory messages, and a glossary. All other books in the
documentation set refer to concepts explained in this book.
• TIBCO Rendezvous C Reference
Detailed descriptions of each datatype and function in the Rendezvous C API.
Readers should already be familiar with the C programming language, as well
as the material in TIBCO Rendezvous Concepts.
• TIBCO Rendezvous C++ Reference
Detailed descriptions of each class and method in the Rendezvous C++ API.
The C++ API uses some datatypes and functions from the C API, so we
recommend the TIBCO Rendezvous C Reference as an additional resource.
Readers should already be familiar with the C++ programming language, as
well as the material in TIBCO Rendezvous Concepts.
• TIBCO Rendezvous Java Reference
Detailed descriptions of each class and method in the Rendezvous Java
language interface. Readers should already be familiar with the Java
programming language, as well as the material in TIBCO Rendezvous Concepts.
• TIBCO Rendezvous .NET Reference
Detailed descriptions of each class and method in the Rendezvous .NET
interface. Readers should already be familiar with either C# or Visual Basic
.NET, as well as the material in TIBCO Rendezvous Concepts.
• TIBCO Rendezvous COM Reference
Detailed descriptions of each class and method in the Rendezvous COM
component. Readers should already be familiar with the programming
environment that uses COM and OLE automation interfaces, as well as the
material in TIBCO Rendezvous Concepts.

xviii
| Preface
• TIBCO Rendezvous Administration

Begins with a checklist of action items for system and network administrators.
This book describes the mechanics of Rendezvous licensing, network details,
plus a chapter for each component of the Rendezvous software suite. Readers
should have TIBCO Rendezvous Concepts at hand for reference.
• TIBCO Rendezvous Configuration Tools
Detailed descriptions of each Java class and method in the Rendezvous
configuration API, plus a command line tool that can generate and apply
XML documents representing component configurations. Readers should
already be familiar with the Java programming language, as well as the
material in TIBCO Rendezvous Administration.
• TIBCO Rendezvous Installation
Includes step-by-step instructions for installing Rendezvous software on
various operating system platforms.
• TIBCO Rendezvous Release Notes
Lists new features, changes in functionality, deprecated features, migration
and compatibility information, closed issues and known issues.

|
How to Contact TIBCO Customer Support xix
How to Contact TIBCO Customer Support
For comments or problems with this manual or the software it addresses, please
contact TIBCO Support as follows.
• For an overview of TIBCO Support, and information about getting started
with TIBCO Product Support, visit this site:
http://www.tibco.com/services/support
• If you already have a valid maintenance or support contract, visit this site:
http://support.tibco.com
Entry to this site requires a username and password. If you do not have a
username, you can request one.

xx
| Preface

|1
Chapter 1 Concepts
This chapter presents concepts specific to the TIBCO Rendezvous® Java language
interface. For concepts that pertain to Rendezvous software in general, see the
book TIBCO Rendezvous Concepts.
Topics
• Implementations, page 2
• Strings and Character Encodings, page 3
• Interrupting Event Dispatch Threads, page 5
• Rendezvous Daemon and Agent, page 6
• Network Overview—rvd Transports, page 9
• Network Overview—rva Transports, page 11
• Internet Web Site Considerations, page 13
• Intranet Web Site Considerations, page 16

2
| Chapter 1 Concepts
Implementations
Rendezvous Java language interface offers several implementations. Table 1

summarizes and compares them. To specify an implementation, see Archive Files
on page 20, and Tibrv.open() on page 32.
Table 1 Implementations
Native (JNI) Native (JNI)

Aspect Java
Thin-Message Full-Message
Coding A thin Java layer serves as a programming interface to Implemented in Java.
an underlying C implementation.
Primary Independent application Independent application Downloadable browser

Runtime or browser applet applet
Environment
Scope of Maximal coverage of C functionality. Covers core functionality

Functionality Exception: I/O events of Rendezvous. Excludes
fault tolerance, certified
delivery, and secure
daemons.
Speed Faster for receiving Faster for receiving Generally not as fast as
applications that access a applications that access either native C
small subset of fields all fields of inbound implementation.
from inbound messages. messages.
Transport rvd and intra-process rvd, rva, and rva and intra-process
Support transports intra-process transports transports
Timer Supports fine-resolution timers (within operating Timer granularity is

Granularity system limitations) limited by JVM to 10
milliseconds.
Library Must load the Rendezvous JNI library Does not require the
Requirements Rendezvous JNI library

|
Strings and Character Encodings 3
Strings and Character Encodings
Rendezvous software uses strings in several roles:

• String data inside message fields
• Field names
• Subject names (and other associated strings that are not strictly inside the
message)
• Certified delivery (CM) correspondent names
• Group names (fault tolerance)
Encodings and Java programs represent all these strings in the Unicode 2-byte character set.
Translation
• Before sending an outbound message, Rendezvous software translates these
strings into the character encoding appropriate to the ISO locale.
• Conversely, when extracting a string from an inbound message, Rendezvous
software translates it to Unicode according to the encoding tag of the message.
If a message has no tag, Rendezvous translates its strings as if the message
used the default encoding (see Default Encoding, below). This assumption is
not always correct (see Inbound Translation, below).
Default Encoding The default encoding depends on the locale where Java is running. That is, the
locale determines the value of the Java system property file.encoding, which in
turn determines the translation scheme.
For example, the United States is locale en_US, and uses the Latin-1 character
encoding (also called ISO 8859-1); Japan is locale ja_JP, and uses the Shift-JIS
character encoding.
When the system property file.encoding is inaccessible, the default encoding is
8859-1 (Latin-1). Programs can override this system property; for details, see
TibrvMsg.setStringEncoding() on page 79.
Some browsers (for example, Microsoft Internet Explorer) do not permit

programs to access the system property file.encoding. When programs attempt
to access it, the browser throws a SecurityException. Although this is normal,
and the program continues to run, the browser may nonetheless print a stack
trace, indicating that the program cannot access that system property.

4
Outbound Translation
Outbound translation from Unicode to a specified encoding usually occurs when
adding a string to a message. However, in an rva environment (using
tibrvjweb.jar) translation occurs later—when sending the message, or when
explicitly converting the message to a byte array.
Exotic Characters A wire-format string can contain only characters that are valid in the encoding of
the surrounding message. The translation procedure detects exotic characters,
and throws an exception with TibrvStatus.INVALID_ENCODING.
Inbound Translation
Inbound translation occurs before the program receives the data.
Automatic inbound translation is correct when two programs exchange messages
within the same locale.
In contrast, the automatic translation might be incorrect when the sender and
receiver use different character encodings.
In this situation, the receiver must explicitly retranslate to the local encoding.
See Also TibrvMsg.getStringEncoding() on page 71

TibrvMsg.setStringEncoding() on page 79

|
Interrupting Event Dispatch Threads 5
Interrupting Event Dispatch Threads
The Java method Thread.interrupt() is ineffective when all of these conditions

are simultaneously true:
• Tibrv is open using the native (JNI) implementation.
• The thread dispatches an event queue or queue group.
• The queue or queue group is empty of events.
To effectively interrupt such a thread, a program can destroy the queue or queue
group. In this situation, the dispatch method throws an exception; the thread can
use that exception as an occasion to exit.

6
Rendezvous Daemon and Agent
Rendezvous Java programs can connect to the network in either of two ways:
• An rvd transport connects to a Rendezvous daemon process (rvd).
• An rva transport connects to a Rendezvous agent process (rva), which in turn
connects to a Rendezvous daemon process.
This section describes the two kinds of transports, the processes to which they
connect, and the reasons for choosing each one.
Java Applications and Applets

A Java program runs either as an independent application or as an applet.
An independent application runs as an ordinary process. It can access the usual
resources, such as file I/O and network connections.
An applet runs within a browser or an applet-viewer process. Since browsers
download untrusted applets across the Internet, they enforce security restrictions
on those applets. These restrictions protect the computer and its local network
from tampering by unauthorized applets.
Security versus Efficiency

Rendezvous daemon (rvd) processes service all network communications for
Rendezvous programs. Every Rendezvous program (in any supported language)
uses a Rendezvous daemon. When a program sends a message, rvd transmits it
across the network. When a program listens to a subject, rvd receives messages
from the network, and presents messages with matching subject names to the
listening program.
Within Rendezvous programs, each network transport object represents a
connection to an rvd process. Because rvd is an essential link in Rendezvous
communications, if the transport cannot connect to an rvd process that is already
running, it automatically starts one.
However, Java applets present a security concern for rvd. The Rendezvous agent
(rva) acts as a secure gateway between rvd on a network, and untrusted remote
Java applets. Instead of connecting directly to rvd, applets must connect to an rva
process, which in turn connects to rvd. As its name implies, rva acts as the
applet’s agent for all interactions with rvd.

Rendezvous Daemon and Agent 7
|
Figure 2 on page 12 depicts rva (center) in this intermediary role between Java
applets and rvd. On the left side of Figure 2, a user downloads a Java applet from
a remote server; the applet connects back to that home server to gain access to the
home network, so the applet can exchange data with programs on that network.
Remote Java applets cannot spawn processes on the home network. Instead of
spawning rvd on the home network, they connect to rva—which must already be
running before any applet attempts to connect. Network administrators retain
complete control over rva, along with its use of LAN, file and computational
resources on the home network.
The Rendezvous agent also protects rvd from inappropriate requests; rva checks
and filters all requests from Java applets, so rvd receives only well-formed,
legitimate requests.
Java applets using rva do not require Rendezvous shared libraries (JNI), so they
can run in browsers on computers where Rendezvous software is not installed.
However, rva does not support certified message delivery, distributed queue or
fault tolerance features. Java programs that use these features must connect
directly to rvd; these features are not available to applets that connect from
remote networks through rva.
For connections to the local network, a direct connection to rvd is more efficient
than an indirect connection through rva to rvd. In all situations we recommend
rvd transports in preference to rva transports—except for applets connecting to a
remote home network, which must use rva transports.
For information about transport objects, see TibrvTransport on page 176.
For more information about rvd, see Rendezvous Daemon (rvd) on page 35 in
TIBCO Rendezvous Administration.
For more information about rva, see Rendezvous Agent (rva) on page 253 in
Starting rvd Automatically

rvd transports attempt to connect to an rvd process—if such a process is already
running. If an appropriate process is not already running, the rvd transport starts
one on its local host computer, and then connects to it.
However, transports cannot automatically start processes on remote computers. If
the parameters of an rvd transport specify a remote daemon, then the daemon
must already be running before the transport attempts to connect.

8
Starting rva
Java programs can never start rva automatically; they must connect to an existing
rva process.
Start the Rendezvous agent using the rva command or icon. The rva command
line accepts rvd command parameters, and uses them to start rvd (when
appropriate).
When rva starts, it attempts to connect to an rvd process with identical
parameters. If an appropriate rvd process is not already running, rva starts it
automatically. If rvd terminates, rva restarts it automatically. (However, rva can
start rvd only on the same computer; it cannot automatically start a remote rvd.)
Numerous Java applets can connect to one rva process, and each applet can create
several TibrvRvaTransport objects (each representing a separate connection to
rva). An rva process instance connects to rvd only once, with a single transport,
regardless of the number of Java TibrvRvaTransport objects that connect to it.
For more information about starting rva, see Rendezvous Agent (rva) on
page 253 in TIBCO Rendezvous Administration.
For more information about starting rvd, see Rendezvous Daemon (rvd) on
Browser Security
rva
Browsers download applets from web servers, using the hypertext transport
protocol (HTTP). A web server host runs a process that services HTTP requests.
Standard browser security arrangements permit an applet to connect back across
the Internet to the web server host where it originated. Rendezvous applets that
use rva transports connect in this way, and so require this permission (for details,
see Internet Web Site Considerations on page 13).
rvd
Applets that use rvd transports connect to an rvd process. Most browsers permit
TCP connections from locally installed classes, with appropriate configuration.
For more information, see the documentation for the browser.

Network Overview—rvd Transports 9
|
Network Overview—rvd Transports
Figure 1 on page 10 shows programs that communicate using rvd transports.

In the top and bottom of Figure 1, Java applets run in two separate local networks.
Browsers download the applets from an intranet web server (center), but the
applets then communicate with other Rendezvous programs on their local
networks (that is, they do not communicate with web server host).
This configuration is well-suited to intranets within an enterprise. The applets
may run on a single network, or on several networks connected by Rendezvous
routing daemons.
The independent Java application (bottom) also uses an rvd transport, and
communicates with applets on its network.

10
Figure 1 Java Programs with rvd Transports
Physical
Software Hardware
Connections
rvd Java Applet

Internal Computer
Information Bus
Internal Network
rvd Java Applet
Internal Computer
Download
rvd Java Applet
Applet Internal Computer
http Server
Daemon
Intranet Server Host
Download
Applet
rvd Java Applet

Internal Computer
Internal Network
Information Bus
rvd Java Applet

Internal Computer
Independent
rvd
Java App
Internal Computer

Network Overview—rva Transports 11
|
Network Overview—rva Transports
Figure 2 on page 12 illustrates a typical environment for Rendezvous Java

programs that communicate using rva transports.
The top of Figure 2 depicts an Internet environment, and the bottom depicts a
local network environment; at the center (between the two firewalls) is the
internet web server host—the bridge between the internal network and the
Internet.
The bottom of Figure 2 shows a local network with Rendezvous programs, which
communicate with one another through Rendezvous daemon processes (rvd).
These programs can be Java applets, independent Java applications, and
Rendezvous programs written in other languages.
Remote browsers (like the one at the top of Figure 2) use the Internet to download
Rendezvous applets from the web server. Those remote applets connect back to a
Rendezvous agent process (rva) on the web server host. The rva process acts on
behalf of the applets, as their intermediary for communications with the internal
network (bottom).
This indirection (rva) adds a layer of security, protecting the web server host and
the internal network from unauthorized applets.

12
Figure 2 Java Programs with rva Transports
Physical
Software Hardware
Connections
Remote
Internet
Java Applet
External Computer
Download
Applet
A
Hardware Router
Outer Firewall
Outer Firewall
http Server
rva
Daemon
Internet Server Host
Inner Firewall
B
Hardware Router
Inner Firewall
rvd
Internal Computer
Internal Network
Information Bus
Local
rvd
Java Applet
Internal Computer
rvd Java App

Internal Computer

|
Internet Web Site Considerations 13
Internet Web Site Considerations
When you design Java applets that connect to an Internet web site, pay special
attention to these issues.
Rendezvous Files
For correct download and operation of your applet, Rendezvous files must be
available in the applet’s code base directory.
• Place the jar archive file in the code base directory. The jar file is named
tibrvjweb.jar.
• Embed the applet in a web page. In the HTML source file, use the <APPLET>
tag, and specify the ARCHIVE argument:
ARCHIVE=codebase_dir/tibrvjweb.jar
The ARCHIVE argument tells browsers where to find the supporting

Rendezvous package, compressed as a jar file.
Home Computer and Port

Applets connect back to an rva process on the web server host computer by
creating a TibrvRvaTransport. This code fragment illustrates a typical applet
calling sequence:
TibrvRvaTransport myTransport = new TibrvRvaTransport(
getCodeBase().getHost(),
portNum,
true);
An rva process on the home computer must be listening for client connections on
the correct TCP port. Be sure that your calls to RvTibrvRvaTransport() use a
TCP port that matches the -listen parameter of rva.
Open a Path through the Firewall

Request that the system administrator configure the server-side firewall so that
TCP connection requests or HTTP GET and POST requests can propagate from
the applet back to rva. Applets can only connect if this path is open.
See also, Rendezvous Agent (rva) on page 253 in TIBCO Rendezvous
Administration.

14
HTTP Tunneling
Direct TCP connections to rva yield the best performance. However, intervening
firewalls and proxy servers usually prevent applets from establishing direct TCP
connections to rva.
To alleviate this restriction in some situations, rva can use a technique called
HTTP tunneling, in which it communicates with its client applets through a TCP
port using the (slower) HTTP protocol.
This solution works in two situations:
• Tunnel to the Web Server Host on page 14
• Signed Applets on page 15
Tunnel to the Web Server Host

Most web servers communicate using the default HTTP port, which is port 80. If
the client-side firewall allows HTTP GET and POST requests on an HTTP port
other than 80, then rva can listen for connections on that other port, and client
applets can contact rva on that port. The server-side firewall must also allow
HTTP GET and POST requests on the same port. Figure 3 on page 14 illustrates
this situation.
Figure 3 HTTP Tunneling to the Web Server Host
Applet
HTTP 80 HTTP 7600

Client Firewall
Connection
Download
Applet
HTTP
HTTP 80 HTTP 7600

Server Firewall
http Server
rva
Daemon
Web Server Host

|
Internet Web Site Considerations 15
Signed Applets
Most browsers allow signed applets to connect to computers other than the web
server host. If rva runs on a host computer other than the web server host, then
rva can listen on HTTP port 80, and signed applet clients can contact it. Figure 4
on page 15 illustrates this situation. However, unsigned applets can connect only
to the web server host; browsers prevent unsigned applets from connecting to any
other computer.
Figure 4 HTTP Tunneling to a Separate rva Host
Signed
Applet
HTTP 80 HTTP 80
Client Firewall
Connection
Download
Applet
HTTP
HTTP 80 HTTP 80
Server Firewall
http Server
rva
Daemon
Web Server Host rva Host
Isolate External from Internal

The book TIBCO Rendezvous Administration discusses strategies for isolating
separate pathways for various application programs. These strategies are even
more important in the context of Java applets, so you can protect your internal
network and its Rendezvous programs from external applets.
Techniques include using separate UDP or PGM services and multicast
addressing. For more information, see Network Details on page 17 in TIBCO
Rendezvous Administration.

16
Intranet Web Site Considerations
When you design Java programs that run on an intranet—using rvd transports to
connect to the local network—pay special attention to these issues.
Rendezvous Files
Correct operation of programs requires the Rendezvous classes. The program
searches for the archive file that contains the Rendezvous classes; the CLASSPATH
environment variable guides the search.
JNI Shared Libraries

Correct operation of TibrvRvdTransport requires prior installation of the JNI
shared libraries.
rvd
TibrvRvdTransport objects must be able to connect to an rvd process. We
recommend that you install the rvd executable on the client host computer.

| 17
Chapter 2 Programmer’s Checklist
Consult this chapter for details of the application development cycle.
Topics
• Checklist, page 18
• Archive Files, page 20
• Shared Library Files, page 21

18
| Chapter 2 Programmer’s Checklist
Checklist
Developers of Rendezvous programs can use this checklist during the four phases
of the development cycle: installing Rendezvous software, coding your Java
program, compiling your Java program, and running your program as either an
independent application or as a browser applet.
Install
• Install the Rendezvous software release, which automatically includes the
Java archive files in the lib subdirectory.
• The CLASSPATH variable must include an archive file that contains the
Rendezvous classes.
On UNIX platforms, include the appropriate archive file from Table 2, Archive
Files, on page 20.
On other supported platforms, this step is automatic.
Code
• Import the correct Rendezvous package.
Import com.tibco.tibrv.*
Compile
• The CLASSPATH variable must include an archive file that contains the
Rendezvous classes. Include the appropriate archive file from Table 2, Archive
Files, on page 20.
Run
• Both rvd and rva require valid licensing.
See Licensing Information on page 11 in TIBCO Rendezvous Administration.
Run as Independent Application

• Rendezvous software must be properly installed, so that the application can
access shared library files. For details, see Shared Library Files on page 21.

|
Checklist 19
• The CLASSPATH variable must include the location of the Rendezvous classes.
Include the appropriate archive file from Table 2, Archive Files, on page 20.
• The application must be able to connect to a Rendezvous daemon process
(rvd).
Run as Applet Using rva Transport

• Applets running in a browser automatically download Rendezvous classes as
needed. The Rendezvous classes must be located at the applet’s code base (the
URL from which the browser obtains the applet code).
For example, if the applet code (compiled with Java 1.1) is in
http://demo/myapp.class, then that location must also contain
http://demo/com.tibco.tibrv/*.class in a series of subdirectories. For
details, see Internet Web Site Considerations on page 13.
Some browsers can download classes from archive files. For details, consult
the documentation for those browser products. Select the archive file for the
Web implementation from Table 2, Archive Files, on page 20.
• The Rendezvous agent (rva) must be properly installed at the web server host
computer (the code base specifies its host name).
The Rendezvous agent process must already be running before the applet
attempts to connect.
If the applet overrides the default values, the port parameter of its
TibrvRvaTransport must match the Listen parameter of rva. (See
TibrvRvaTransport() on page 190.)
• The Rendezvous agent must be able to connect to a Rendezvous daemon

process (rvd).
Run—Applets Using rvd Transports

• Rendezvous software must be properly installed on the computer on which
the applet is running, so that the application can access shared library files.
• Applets running in a browser gain speed when the Rendezvous package is
installed locally. To take advantage of this efficiency, the CLASSPATH variable
(as read when the browser starts) must include an appropriate archive file
from Table 2, Archive Files, on page 20.
• The applet must be able to connect to a Rendezvous daemon process (rvd). If
the browser does not permit the applet to connect to rvd, adjust the browser’s
security settings to permit TCP connections to the rvd client connection socket
(the daemon parameter of TibrvRvaTransport() specifies this socket).

20
Archive Files
Table 2 details the jar files for various implementations of Rendezvous for Java.
Place the appropriate jar file in the CLASSPATH environment variable.
Table 2 Archive Files
Edition Archive File Contents

Web tibrvjweb.jar Standard classes
TibrvRvaTransport only
Pure Java implementation
JNI Thin-Message
The following two native (JNI) implementations use thin-message technology, which performs best
with receiving applications that access only a few fields from inbound messages (ignoring the
remaining fields).
Thin-Message tibrvnative.jar Standard classes

Local Certified message delivery
Fault tolerance
TibrvRvdTransport
Thin-Message tibrvnativesd.jar Standard classes

Secure Daemon Certified message delivery
Fault tolerance
Secure daemons (TibrvSdContext)
TibrvRvdTransport
JNI Full-Message
The following two native (JNI) implementations use full-message technology, which performs best
with receiving applications that access all the fields of inbound messages.
Full-Message tibrvj.jar Standard classes

Local Certified message delivery
Fault tolerance
TibrvRvaTransport and TibrvRvdTransport
Full-Message tibrvjsd.jar Standard classes

Secure Daemon Certified message delivery
Fault tolerance
Secure daemons (TibrvSdContext)
TibrvRvaTransport and TibrvRvdTransport

|
Shared Library Files 21
Shared Library Files
Independent Java applications that use rvd transports must be able to access
Rendezvous shared library files (C libraries). Table 3 details the environment
variables that direct Java applications to the Rendezvous installation directory.
The installation directory must contain the required shared library files.
Table 3 Environment Variables for Shared Library Files
Platform Environment Variable

Windows PATH must include \install_dir\bin
The installation procedure sets this variable automatically.
UNIX LD_LIBRARY_PATH must include install_dir/lib

(Except as For 64-bit JVM, LD_LIBRARY_PATH must also include
below) install_dir/lib/64
HP/UX SHLIB_PATH must include install_dir/lib

22

| 23
Chapter 3 Rendezvous Environment
This brief chapter describes the methods that open and close the internal
machinery upon which Rendezvous software depends.
Topics
• Tibrv, page 24
• TibrvSdContext, page 36

24
| Chapter 3 Rendezvous Environment
Tibrv
Class
Declaration class com.tibco.tibrv.Tibrv.Tibrv

extends java.lang.Object
Purpose The Rendezvous environment.
Remarks Programs do not create instances of Tibrv. Instead, programs use its static
methods to open and close the Rendezvous environment. Private constants and
variables contain references to Rendezvous resources.
For a list of constants that this class defines, see Implementations on page 33.
Method Description Page

Environment Life Cycle and Properties
Tibrv.open() Start Rendezvous internal machinery. 32
Tibrv.close() Stop and destroy Rendezvous internal machinery. 26
Tibrv.getVersion() Return the version string or one of its components. 29
Tibrv.isValid() Determine whether the Rendezvous machinery is open. 31
Tibrv.isNativeImpl() Discriminate between native (JNI) implementation and 30

Java implementation.
Utility Objects
Tibrv.defaultQueue() Extract the default queue object. 27
Tibrv.processTransport() Extract the intra-process transport object. 34
Asynchronous Errors
Tibrv.getErrorCallback() Extract the callback object that processes asynchronous 28

errors.
Tibrv.setErrorCallback() Set the callback for processing asynchronous errors. 35

|
Tibrv 25
Inherited Methods
java.lang.Object.equals
java.lang.Object.getClass
java.lang.Object.hashCode
java.lang.Object.notify
java.lang.Object.notifyAll
java.lang.Object.toString
java.lang.Object.wait

26
Tibrv.close()
Method
Declaration static void close() throws TibrvException
Purpose Stop and destroy Rendezvous internal machinery.
Remarks After Tibrv.close() destroys the internal machinery, Rendezvous software

becomes inoperative:
• Events no longer arrive in queues.
• All events, queues and queue groups are unusable, so programs can no longer
dispatch events.
• All transports are unusable, so programs can no longer send outbound
messages.
After closing a Tibrv object, all events, transports, queues and queue groups
associated with that environment are invalid; it is illegal to call any methods of
these objects.
After closing a Tibrv environment, you can reopen it either with the same
implementation, or with a different implementation.
Reference Count A reference count protects against interactions between programs and third-party
packages that call Tibrv.open() and Tibrv.close(). Each call to Tibrv.open()
increments an internal counter; each call to Tibrv.close() decrements that
counter. A call to Tibrv.open() actually creates internal machinery only when
the reference counter is zero; subsequent calls merely increment the counter, but
do not duplicate the machinery. A call to Tibrv.close() actually destroys the
internal machinery only when the call decrements the counter to zero; other calls
merely decrement the counter. In each program, the number of calls to
Tibrv.open() and Tibrv.close() must match.
To ascertain the actual state of the internal machinery, use Tibrv.isValid() on

page 31.
See Also Tibrv.isValid() on page 31

Tibrv.open() on page 32

|
Tibrv.defaultQueue() 27
Tibrv.defaultQueue()
Method
Declaration static TibrvQueue defaultQueue()
Purpose Extract the default queue object.
Remarks If Rendezvous is not open, this method returns null.

Each process has exactly one default queue; the call Tibrv.open() automatically
creates it. Programs must not destroy the default queue.
See Also TibrvQueue on page 138.

28
Tibrv.getErrorCallback()
Method
Declaration static TibrvErrorCallback getErrorCallback()
Purpose Extract the callback object that processes asynchronous errors.
Remarks If the program has not set an error callback, this method returns null.
See Also Tibrv.setErrorCallback() on page 35

TibrvErrorCallback on page 327

|
Tibrv.getVersion() 29
Tibrv.getVersion()
Method
Declaration static String getVersion()

static String getCmVersion()
static String getFtVersion()
static int getMajorVersion()

static int getMinorVersion()
static int getUpdateVersion()
static String getVersionString() // This method is deprecated

//
Purpose Return the version string or one of its components.
Remarks getVersion() returns the version number of the Java package (whether using
machinery from Tibrv.IMPL_JAVA or Tibrv.IMPL_NATIVE).
getCmVersion() returns the version number of the underlying C implementation
of the certified delivery library (Tibrv.IMPL_NATIVE only).
getFtVersion() returns the version number of the underlying C implementation
of the fault tolerance library (Tibrv.IMPL_NATIVE only).
getMajorVersion(), getMinorVersion() and getUpdateVersion() return the
three segments of the complete version number that getVersion() returns (it
formats these three segments into a string).
The method getVersionString() is deprecated (though not yet obsolete),
starting with release 6.2. We encourage programmers to migrate to getVersion()
instead.

30
Tibrv.isNativeImpl()
Method
Declaration static boolean isNativeImpl()
Purpose Discriminate between native (JNI) implementation and Java implementation.
Remarks When a program opens the Rendezvous environment with Tibrv.IMPL_SELECT,

it can later use this method to determine the effective implementation.
This method returns true when Rendezvous software uses the JNI library.
Otherwise it returns false.

|
Tibrv.isValid() 31
Tibrv.isValid()
Method
Declaration static boolean isValid()
Purpose Determine whether the Rendezvous machinery is open.
Remarks This method returns true after the method Tibrv.open() has returned
successfully.
Otherwise this method returns false. The value false usually indicates one of
these situations:
• The program has not opened the Rendezvous environment.
• Attempts to open the environment failed.
• The environment was open, but the program closed it with Tibrv.close().
See Also Tibrv.open() on page 32

Tibrv.close() on page 26

32
Tibrv.open()
Method
Declaration static void open() throws TibrvException
static void open(int implementation) throws TibrvException
Purpose Start Rendezvous internal machinery.
Remarks This call creates the internal machinery that Rendezvous software requires for its
operation:
• Internal data structures.
• Default event queue.
• Intra-process transport.
• Event driver.
Until the first call to Tibrv.open() creates the internal machinery, all events,
transports, queues and queue groups are unusable. Messages and their methods
do not depend on the internal machinery.
Parameter Description
implementation Open Rendezvous using this implementation.
Choose a value from among the constants
Tibrv.IMPL_NATIVE, Tibrv.IMPL_JAVA, and
Tibrv.IMPL_SELECT. See Implementations on page 33.
Method Forms With no argument, open using Tibrv.IMPL_SELECT. To determine the actual
implementation, use Tibrv.isNativeImpl() on page 30.
With an implementation argument, open using the specified implementation.

|
Tibrv.open() 33
Implementations These constants denote the implementation choices.
Constant Description
Tibrv.IMPL_NATIVE Open Rendezvous machinery using the implementation in the JNI library,
if possible; otherwise, throw a TibrvException with one of these status
codes: TibrvStatus.VERSION_MISMATCH,
TibrvStatus.WRONG_JAVA_ARCHIVE, TibrvStatus.LIBRARY_NOT_FOUND,
TibrvStatus.LIBRARY_NOT_LOADED.
An exception could indicate an incorrect value of the CLASSPATH

environment variable.
Tibrv.IMPL_JAVA Open Rendezvous machinery using the pure Java implementation.
Tibrv.IMPL_SELECT Open Rendezvous machinery using JNI library if possible; otherwise, use
the Java implementation.
Reference Count A reference count protects against interactions between programs and third-party
packages that call Tibrv.open() and Tibrv.close(). Each call to Tibrv.open()
increments an internal counter; each call to Tibrv.close() decrements that
counter. A call to Tibrv.open() actually creates internal machinery only when
the reference counter is zero; subsequent calls merely increment the counter, but
do not duplicate the machinery. A call to Tibrv.close() actually destroys the
internal machinery only when the call decrements the counter to zero; other calls
merely decrement the counter. In each program, the number of calls to
Tibrv.open() and Tibrv.close() must match.
See Also Implementations, page 2

Tibrv.close() on page 26
Tibrv.isNativeImpl() on page 30

34
Tibrv.processTransport()
Method
Declaration static TibrvProcessTransport processTransport()
Purpose Extract the intra-process transport object.
Remarks If Rendezvous is not open, this method returns null.

Each process has exactly one intra-process transport; the call Tibrv.open()
automatically creates it. Programs must not destroy the intra-process transport.
See Also TibrvProcessTransport on page 186

|
Tibrv.setErrorCallback() 35
Tibrv.setErrorCallback()
Method
Declaration static void setErrorCallback(TibrvErrorCallback errorCallback)
Purpose Set the callback for processing asynchronous errors.
errorCallback Use this TibrvErrorCallback object to process all
asynchronous errors.
See Also Tibrv.getErrorCallback()on page 28

TibrvErrorCallbackon page 327
TibrvErrorCallback.onError() on page 328

36
TibrvSdContext
Class
Declaration final class com.tibco.tibrv.TibrvSdContext
static final String TIBRV_SECURE_DAEMON_ANY_NAME = null;

static final String TIBRV_SECURE_DAEMON_ANY_CERT = null;
Purpose This class defines static methods for interacting with secure Rendezvous
daemons.
Remarks Programs do not create instances of TibrvSdContext. Instead, programs use its
static methods to configure user names, passwords and certificates, and to
register trust in daemon certificates.
To use the methods of this class, Java programs must satisfy these two criteria:
• Programs must compile and run with the archive file tibrvjsd.jar (which
defines this class); see Archive Files on page 20.
• Programs must open the Rendezvous environment using the native
implementation; see Tibrv.open() on page 32—in particular, the constant
Tibrv.IMPL_NATIVE, which specifies the Rendezvous JNI library
implementation.

TibrvSdContext.setDaemonCert() Register trust in a secure daemon. 37
TibrvSdContext.setUserCertWithKey() Register a (PEM) certificate with 39

private key for identification to secure
daemons.
TibrvSdContext.setUserCertWithKeyBin() Register a (PKCS #12) certificate with 40

private key for identification to secure
daemons.
TibrvSdContext.setUserNameWithPassword() Register a user name with password 41

for identification to secure daemons.

TibrvSdContext.setDaemonCert() 37
|
TibrvSdContext.setDaemonCert()
Method
Declaration static void setDaemonCert(

java.lang.String daemonName,
java.lang.String daemonCert)
throws TibrvException
Purpose Register trust in a secure daemon.
Remarks When any program transport connects to a secure daemon, it verifies the
daemon’s identity using SSL protocols. Certificates registered using this method
identify trustworthy daemons. Programs divulge user names and passwords to
daemons that present registered certificates.
daemonName Register a certificate for a secure daemon with this name. For
the syntax and semantics of this parameter, see Daemon
Name, below.
daemonCert Register this public certificate. The text of this certificate must
be in PEM encoding. See also Certificate on page 38.
Daemon Name The daemon name is a three-part string of the form:

ssl:host:port_number
This string must be identical to the string you supply as the daemon argument to
the transport creation call; see TibrvRvdTransport() on page 200.
Colon characters (:) separate the three parts.
ssl indicates the protocol to use when attempting to connect to the daemon.
host indicates the host computer of the secure daemon. You can specify this host
either as a network IP address, or a hostname. Omitting this part specifies the
local host.
port_number specifies the port number where the secure daemon listens for SSL
connections.
(This syntax is similar to the syntax connecting to remote daemons, with the
addition of the prefix ssl.)

38
In place of this three-part string, you can also supply the constant
TibrvSdContext.TIBRV_SECURE_DAEMON_ANY_NAME. This form lets you register
a catch-all certificate that applies to any secure daemon for which you have not
explicitly registered another certificate. For example, you might use this form
when several secure daemons share the same certificate.
Certificate For important details, see CA-Signed Certificates on page 165 in TIBCO
Rendezvous Administration.
In place of an actual certificate, you can also supply the constant
TibrvSdContext.TIBRV_SECURE_DAEMON_ANY_CERT. The program accepts any
certificate from the named secure daemon. For example, you might use this form
when testing a secure daemon configuration, before generating any actual
certificates.
Any Name and Notice that the constants TibrvSdContext.TIBRV_SECURE_DAEMON_ANY_NAME

Any Certificate and TibrvSdContext.TIBRV_SECURE_DAEMON_ANY_CERT each eliminate one of
the two security checks before transmitting sensitive identification data to a
secure daemon. We strongly discourage using both of these constants
simultaneously, because that would eliminate all security checks, leaving the
program vulnerable to unauthorized daemons.

|
TibrvSdContext.setUserCertWithKey() 39
TibrvSdContext.setUserCertWithKey()
Method
Declaration static void setUserCertWithKey(

java.lang.String userCertWithKey,
java.lang.String password)
Purpose Register a (PEM) certificate with private key for identification to secure daemons.
Remarks When any program transport connects to a secure daemon, the daemon verifies
the program’s identity using SSL protocols.
The Rendezvous API includes two methods that achieve similar effects:
• This call accepts a certificate in PEM text format.
• TibrvSdContext.setUserCertWithKeyBin() accepts a certificate in
PKCS #12 binary format.
userCertWithKey Register this user certificate with private key. The text of
this certificate must be in PEM encoding.
password Use this password to decrypt the private key.
For important information about password security, see Security Factors on

CA-Signed You can also supply a certificate signed by a certificate authority (CA). To use a
Certificate CA-signed certificate, you must supply not only the certificate and private key,
but also the CA’s public certificate (or a chain of such certificates). Concatenate
these items in one string. For important details, see CA-Signed Certificates on
Exceptions An exception that reports status TibrvStatus.INVALID_FILE can indicate either

disk I/O failure, or invalid certificate data, or an incorrect password.
See Also TibrvSdContext.setUserCertWithKeyBin() on page 40

40
TibrvSdContext.setUserCertWithKeyBin()
Method
Declaration void setUserCertWithKeyBin(

byte[] userCertWithKey,
java.lang.String password);
Purpose Register a (PKCS #12) certificate with private key for identification to secure
daemons.
The Rendezvous API includes two methods that achieve similar effects:
• This call accepts a certificate in PKCS #12 binary format.
• TibrvSdContext.setUserCertWithKey() accepts a certificate in PEM text
format.
userCertWithKey Register this user certificate with private key. The binary data of this
certificate must be in PKCS #12 format.
password Use this password to decrypt the private key.

CA-Signed You can also supply a certificate signed by a certificate authority (CA). To use a
Certificate CA-signed certificate, you must supply not only the certificate and private key,
but also the CA’s public certificate (or a chain of such certificates). For important
details, see CA-Signed Certificates on page 165 in TIBCO Rendezvous
Administration.
Exceptions An exception that reports status TibrvStatus.INVALID_FILE can indicate either

disk I/O failure, or invalid certificate data, or an incorrect password.
See Also TibrvSdContext.setUserCertWithKey() on page 39

www.rsasecurity.com/rsalabs/pkcs

|
TibrvSdContext.setUserNameWithPassword() 41
TibrvSdContext.setUserNameWithPassword()
Method
Declaration static TibrvStatus setUserNameWithPassword(

java.lang.String userName,
java.lang.String password)
Purpose Register a user name with password for identification to secure daemons.
userName Register this user name for communicating with secure
daemons.
password Register this password for communicating with secure

daemons.


42

| 43
Chapter 4 Data
This chapter describes messages and the data they contain.
Topics
• Field Names and Field Identifiers, page 44

• TibrvMsg, page 46
• TibrvMsgField, page 87
• TibrvDate, page 92
• TibrvIPAddr, page 99
• TibrvIPPort, page 104
• TibrvXml, page 108
See Also Strings and Character Encodings, page 3

Appendix A, Custom Datatypes, on page 329

44
| Chapter 4 Data
Field Names and Field Identifiers
In Rendezvous 5 and earlier releases, programs would specify fields within a

message using a field name. In Rendezvous 6 and later releases, programs can
specify fields in two ways:
• A field name is a character string. Each field can have at most one name.
Several fields can have the same name.
• A field identifier is a 16-bit unsigned integer, which must be unique within the
message. That is, two fields in the same message cannot have the same
identifier. However, a nested submessage is considered a separate identifier
space from its enclosing parent message and any sibling submessages.
Java presents these identifiers as 32-bit integers, padding the high bytes with
zero.
Message methods specify fields using a combination of a field name and a unique
field identifier. When absent, the default field identifier is zero.
To compare the speed and space characteristics of these two options, see Search
Characteristics on page 44.
Rules and Restrictions

NULL is a legal field name only when the identifier is zero. It is illegal for a field to
have both a non-zero identifier and a NULL field name.
Note that in Java, NULL is not the same as "" (the empty string). It is legal for a
field to have a non-zero identifier and the empty string as its field name.
However, we generally recommend against using the empty string as a field
name.
Adding a New Field

When a program adds a new field to a message, it can attach a field name, a field
identifier, or both. If the program supplies an identifier, Rendezvous software
checks that it is unique within the message; if the identifier is already in use, the
operation fails with the status code TibrvStatus.ID_IN_USE.
Search Characteristics
In general, an identifier search completes in constant time. In contrast, a name
search completes in linear time proportional to the number of fields in the
message. Name search is quite fast for messages with 16 fields or fewer; for
messages with more than 16 fields, identifier search is faster.

|
Field Names and Field Identifiers 45
Space Characteristics
The smallest field name is a one-character string, which occupies three bytes in
Rendezvous wire format. That one ASCII character yields a name space of 127
possible field names; a larger range requires additional characters.
Field identifiers are 16 bits, which also occupy three bytes in Rendezvous wire
format. However, those 16 bits yield a space of 65535 possible field identifiers;
that range is fixed, and cannot be extended.
Finding a Field Instance

When a message contains several field instances with the same field name, these
methods find a specific instance by name and number (they do not use field
identifiers):
• TibrvMsg.removeFieldInstance() on page 75.
• TibrvMsg.getFieldInstance() on page 67.

46
| Chapter 4 Data
TibrvMsg
Class
Declaration class com.tibco.tibrv.TibrvMsg

Purpose Represent Rendezvous messages.
Remarks This class has no destroy() method. Instead, the Java garbage collector reclaims
storage automatically.
(Sheet 1 of 3)

Message Life Cycle and Properties
TibrvMsg() Create a message object. 50
TibrvMsg.getNumFields() Extract the number of fields in a message. 68
Fields
TibrvMsg.add() Add a field to a message. 51
Add Scalar (convenience methods) Add a field containing a scalar value. 54
TibrvMsg.addField() Add a field object to a message. 56
TibrvMsg.get() Get the value of a specified field from a 57

message.
Get Scalar (convenience methods) Get the value of a field as a scalar value. 61
TibrvMsg.getAsBytes() Extract the data from a message as a byte 63

sequence.
TibrvMsg.getField() Get a specified field from a message. 65
TibrvMsg.getFieldByIndex() Get a field from a message by an index. 66
TibrvMsg.getFieldInstance() Get a specific instance of a field from a 67

message.
TibrvMsg.removeField() Remove a field from a message. 73

|
TibrvMsg 47
(Sheet 2 of 3)

TibrvMsg.removeFieldInstance() Remove a specified instance of a field from 75
a message.
TibrvMsg.update() Update a field within a message. 81
Update Scalar (convenience methods) Update a field containing a scalar value. 84
TibrvMsg.updateField() Update a field within a message. 86
Address Information
TibrvMsg.getReplySubject() Extract the reply subject from a message. 69
TibrvMsg.getSendSubject() Extract the subject from a message. 70
TibrvMsg.setReplySubject() Set the reply subject for a message. 77
TibrvMsg.setSendSubject() Set the subject for a message. 78
String and Character Conversion
TibrvMsg.getTypeName() Convert a type designator to its 72

corresponding string name.
TibrvMsg.toString() Format a message as a string. 80
TibrvMsg.getStringEncoding() Return the character encoding for 71

converting between Java Strings and wire
format strings.
TibrvMsg.setStringEncoding() Set the character encoding for converting 79

between Java Unicode strings and wire
format strings.
Custom Datatypes
See Appendix A, Custom Datatypes, on page 329.
TibrvMsg.getDecoder() Extract the decoder interface for a custom 330

datatype.
TibrvMsg.getEncoder() Extract the encoder interface for a custom 331

datatype.

48
| Chapter 4 Data
(Sheet 3 of 3)

TibrvMsg.setHandlers() Define a custom datatype by registering its 332
encoder and decoder interfaces.
Inherited Methods
Datatype These constants are all defined with short values. To extract a human-readable
Constants name from a short value, see TibrvMsg.getTypeName() on page 72
Table 4 Datatype Constants (Sheet 1 of 2)
Constant Comment
TibrvMsg.DEFAULT Used only as a type argument to
TibrvMsg.add()
TibrvMsg.MSG
TibrvMsg.DATETIME
TibrvMsg.OPAQUE
TibrvMsg.STRING
TibrvMsg.XML Byte-array, compressed for network transmission.
TibrvMsg.BOOL
TibrvMsg.I8
TibrvMsg.U8
TibrvMsg.I16
TibrvMsg.U16
TibrvMsg.I32

|
TibrvMsg 49
Table 4 Datatype Constants (Sheet 2 of 2)
Constant Comment
TibrvMsg.U32
TibrvMsg.I64
TibrvMsg.U64
TibrvMsg.F32
TibrvMsg.F64
TibrvMsg.IPPORT16
TibrvMsg.IPADDR32
TibrvMsg.U8ARRAY
TibrvMsg.I16ARRAY
TibrvMsg.U16ARRAY
TibrvMsg.I32ARRAY
TibrvMsg.U32ARRAY
TibrvMsg.I64ARRAY
TibrvMsg.U64ARRAY
TibrvMsg.F32ARRAY
TibrvMsg.F64ARRAY
TibrvMsg.USER_FIRST Custom datatypes begin with this number.
TibrvMsg.USER_LAST

TibrvMsgField on page 87
Appendix A, Custom Datatypes, on page 329

50
| Chapter 4 Data
TibrvMsg()
Constructor
Declaration TibrvMsg()
TibrvMsg(TibrvMsg msg) throws TibrvException
TibrvMsg(byte[] bytes) throws TibrvException
Purpose Create a message object.
Remarks None of these constructors place address information on the new message object.
This class has no destroy() method. Instead, the Java garbage collector reclaims
msg Create an independent copy of this message.
bytes Create a message with fields populated from this byte array.
For example, programs can create such byte arrays from
messages using the method TibrvMsg.getAsBytes(), and store
them in files; after reading them from such files, programs can
reconstruct a message from its byte array.
Method Forms With no argument, create an empty message (with no fields).

With a TibrvMsg argument, create an independent copy of that message, copying
all its fields (field values are also independent copies).
With a byte array argument, create a message with fields populated from the byte
array.
See Also TibrvMsg.getAsBytes() on page 63

|
TibrvMsg.add() 51
TibrvMsg.add()
Method
Declaration void add(

java.lang.String fieldName,
java.lang.Object data)
void add(
java.lang.Object data,
short type)
void add(
short type,
int fieldId)
Purpose Add a field to a message.
Remarks This method copies the information into the new message field. All related
convenience methods behave similarly.
(Sheet 1 of 2)
fieldName Add a field with this name.
null is a legal name. However, if fieldId is non-zero, then
fieldName must be non-null.
data Add a field with this data value.

null is illegal.
type Add a field with this explicit type. For a list of types, see
Datatype Constants on page 48.
When absent or TibrvMsg.DEFAULT, determine the field’s type
from the type of the data. In Figure 5 on page 53, filled dots
indicate default encodings between homologous types.

52
| Chapter 4 Data
(Sheet 2 of 2)
fieldId Add a field with this identifier. All field identifiers must be
unique within each message.
When absent, add a field without an identifier.
Integers in the range [0, 65535] are valid identifiers.
Zero is a special value, indicating no identifier. It is illegal to add
a field that has both a null field name and a non-zero field
identifier.
Encoding and This method automatically tags Java data with a corresponding Rendezvous wire
Type format type; sending the message actually triggers the encoding into wire format.
Conversion Figure 5 on page 53 specifies default encodings with filled circles; for some types
you can override the default decoding by using convenience functions that force
specific types (see Add Scalar on page 54).
Encoding XML We recommend converting the XML document string to a byte sequence, using
the encoding that corresponds to your locale (file encoding system property).
Then create a TibrvXml object containing the bytes, and add that object to the
message. This practice ensures that all receivers can easily parse the resulting
XML document. For more information, see Decoding XML on page 59.
Nested Message When the data argument is a message object, this method adds only the data
portion of the nested message; it does not include any address information or
certified delivery information.
Empty Array The behavior of TibrvMsg.add differs among the various implementations when
the data argument is an empty array. The reason for the discrepancy is that Java
supports empty arrays, while C does not.
The native (JNI) thin-message implementation uses underlying C calls to
manipulate messages stored outside of the Java environment, so it cannot support
empty arrays; consequently, this method throws an exception when it receives an
empty array.
The native (JNI) full-message implementation and the pure Java implementation
both manipulate messages stored within the Java environment, so they do
support empty arrays; consequently, this method correctly adds an empty array
to a message field.

|
TibrvMsg.add() 53
Figure 5 Java to Wire Format Datatype Conversion Matrix

Java Source Type
Add
InetAddress (4-byte only)

TibrvIPAddr
TibrvIPPort
TibrvMsg[]
TibrvDate
TibrvMsg
TibrvXml
double[]
String[]
Double
Integer
short[]
String
float[]
byte[]
long[]
Short
Float
Long
Date
Bool
Byte
int[]
TibrvMsg.BOOL N N N N
TibrvMsg.F32 S N S S N N
TibrvMsg.F64 S S S S N N
TibrvMsg.I8 S N N N
TibrvMsg.I16 S S N N N
TibrvMsg.I32 S S S N N S
TibrvMsg.I64 S S S S S S
TibrvMsg.U8 S N N N N
TibrvMsg.U16 S S N N N S
TibrvMsg.U32 S S S N N S S
tibrvMsg Destination Type
TibrvMsg.U64 S S S S N S S
TibrvMsg.IPADDR32 S S
TibrvMsg.IPPORT16 S S
TibrvMsg.DATETIME
TibrvMsg.F32ARRAY N S S N N
TibrvMsg.F64ARRAY S S S N N
TibrvMsg.I8ARRAY S N N N
TibrvMsg.I16ARRAY S N N
TibrvMsg.I32ARRAY S S N
TibrvMsg.I64ARRAY S S S
TibrvMsg.U8ARRAY S N N N
TibrvMsg.U16ARRAY S N N N
TibrvMsg.U32ARRAY S S N N
TibrvMsg.U64ARRAY S S S N
TibrvMsg.MSG
TibrvMsg.OPAQUE N N N
TibrvMsg.STRING
TibrvMsg.XML
TibrvMsg.MSGARRAY
TibrvMsg.STRINGARRAY
Key
Homologous types; conversion always supported; no loss of information
S Supported conversion; always supported
N Numeric conversion; loss of information is possible (without warning)
Unsupported conversion
See Also TibrvMsg.addField() on page 56

Add Scalar, page 54

54
| Chapter 4 Data
Add Scalar
Convenience Methods
Declaration void add(

scalar_type data)
void add(
scalar_type data,
int fieldId)
void addUbits(
scalar_type data)
void addUbits(
scalar_type data,
int fieldId)
Purpose Add a field containing a scalar value.
Method Forms The convenience methods named add() determine the field type from the
numeric type of the data.
The convenience methods named addUnn() add unsigned integer fields, discarding
the sign bit of a Java integer data value.
(Sheet 1 of 2)
Method Name Java Data Type Field Type Type Description

add boolean TibrvMsg.BOOL boolean
add float TibrvMsg.F32 32-bit floating point
add double TibrvMsg.F64 64-bit floating point
add byte TibrvMsg.I8 8-bit integer
add short TibrvMsg.I16 16-bit integer
add int TibrvMsg.I32 32-bit integer
add long TibrvMsg.I64 64-bit integer

Add Scalar 55
|
(Sheet 2 of 2)

addU8 byte TibrvMsg.U8 8-bit unsigned integer
addU16 short TibrvMsg.U16 16-bit unsigned integer
addU32 int TibrvMsg.U32 32-bit unsigned integer
addU64 long TibrvMsg.U64 64-bit unsigned integer
fieldName Add a field with this name.
null is a legal name. However, if fieldId is non-zero, then
fieldName must be non-null.
data Add a field with this data value.

null is illegal.
fieldId Add a field with this identifier. All field identifiers must be
When absent, add a field without an identifier.
Zero is a special value, indicating no identifier. It is illegal to add
a field that has both a null field name, and a non-zero field
identifier.

56
| Chapter 4 Data
TibrvMsg.addField()
Method
Declaration void addField(TibrvMsgField field)

Purpose Add a field object to a message.
Remarks This method copies the information into the new message field. All related
methods behave similarly.
It is illegal to add a field that has both a null field name, and a non-zero field
identifier.
Field Name The the longest possible field name is 127 bytes.
Length
field Add this field to the message.
See Also TibrvMsg.add() on page 51

Add Scalar, page 54

|
TibrvMsg.get() 57
TibrvMsg.get()
Method
Declaration java.lang.Object get(

java.lang.String fieldName)
java.lang.Object get(
int fieldId)
java.lang.Object get(
int fieldId)
Purpose Get the value of a specified field from a message.
Remarks Programs specify the field to retrieve using the fieldName and fieldId
parameters.
The method returns a snapshot of the field value.
When a program gets fields with the datatypes listed here, this method (and
convenience methods) return a reference to the actual value in the message—not a
copy. Use caution when modifying values of these types: TibrvMsg.MSG,
TibrvMsg.DATETIME, TibrvMsg.IPPORT16, TibrvMsg.IPADDR32,
TibrvMsg.OPAQUE (extracted as a byte array), TibrvMsg.XML (extracted as a byte
array), and all array types.
Programs can use a related method to loop through all the fields of a message; to
retrieve each field by its integer index number, see
TibrvMsg.getFieldByIndex() on page 66.
fieldName Get a field with this name.
fieldId Get the field with this identifier.
Field Search Algorithm

This method, and related methods that get message fields, all use this algorithm to
find a field within a message, as specified by a field identifier and a field name.
1. If the program supplied zero as the identifier, or omitted any identifier, then
begin at step 3.

58
| Chapter 4 Data
If the program supplied a non-zero field identifier, then search for the field
with that identifier.
If the search succeeds, return the field.
On failure, continue to step 2.
2. If the identifier search (in step 1) fails, and the program supplied a non-null
field name, then search for a field with that name.
If the name search succeeds, and the identifier in the field is null, return the
field.
If the name search succeeds, but the actual identifier in the field is non-null
(so it does not match the identifier supplied) then throw an exception with the
status code TibrvStatus.ID_CONFLICT.
On failure, or if the program supplied null as the field name, return null.
3. When the program supplied zero as the identifier, or omitted any identifier,
then begin here.
Search for a field with the specified name—even if that name is null.
If the search succeeds, return the field.
On failure, return null.
If a message contains several fields with the same name, searching by name finds
the first instance of the field with that name.
Extracting Earlier releases of Rendezvous software allowed programs to get fields from a
Fields from a nested submessage by concatenating field names. Starting with release 6,
Nested Message Rendezvous software no longer supports this special case convenience. Instead,
programs must separately extract the nested submessage using TibrvMsg.get()
(or a related method), and then get the desired fields from the submessage.
Method Forms With only a field name, find the field by name. If the field name is not present in
the message, return null. If several fields with that name are present in the
message, this method returns the first one that it finds.
With only a field identifier, find the field with that identifier (since identifiers are
unique, the message can contain at most one such field). If the identifier is not
present in the message, return null.
With both a field name and a field identifier, search first by identifier, and then by
field name. If neither are present in the message, return null. If identifier search
succeeds, return the field value. If the name search succeeds, but the actual
identifier in the field is non-zero (so it does not match the identifier supplied) then
throw a TibrvException with status code TibrvStatus.ID_CONFLICT.

|
TibrvMsg.get() 59
Decoding and This method automatically decodes the extracted field data from its Rendezvous
Type wire format type to a corresponding Java type. In Figure 6 on page 60, filled
Conversion circles (as well as + and - symbols) specify default decodings between
homologous types; for some types you can override the default decoding by
using convenience functions that force specific types (see Get Scalar on page 61).
Java does not admit unsigned integers. When extracting an unsigned integer from
an inbound message field, this method automatically promotes the value to the
corresponding Java type that is large enough to contain it (Figure 6 indicates this
with +). When extracting an unsigned 64-bit integer, Java does not have a type
that can contain a number that uses all 64 bits; this method decodes it to a Java
long, interpreting the high bit as a sign bit (Figure 6 indicates this with -).
Decoding XML After extracting the XML document into a byte array, explicitly convert it to a
string using the encoding that corresponds to your locale (file encoding system
property). For more information, see Encoding XML on page 52.

60
| Chapter 4 Data
Figure 6 Wire Format to Java Datatype Conversion Matrix

Java Destination Type
Get
TibrvIPAddr
TibrvIPPort
TibrvMsg[]
TibrvDate
TibrvMsg
TibrvXml
double[]
Double
String[]
Integer
short[]
String
byte[]
long[]
float[]
Short
Long
Float
Byte
Bool
int[]
TibrvMsg.BOOL N N N N N N
TibrvMsg.F32 N S N N N N
TibrvMsg.F64 N N N N N N
TibrvMsg.I8 N N N S S S
TibrvMsg.I16 N N N N S S
TibrvMsg.I32 N N N N N S
TibrvMsg.I64 N N N N N N
TibrvMsg.U8 N N N N + S S
TibrvMsg.U16 N N N N N + S
TibrvMsg.U32 N N N N N N +
TibrvMsg.U64 N N N N N N -
tibrvMsg Source Type
TibrvMsg.IPADDR32
TibrvMsg.IPPORT16
TibrvMsg.DATETIME
TibrvMsg.F32ARRAY
TibrvMsg.F64ARRAY
TibrvMsg.I8ARRAY
TibrvMsg.I16ARRAY
TibrvMsg.I32ARRAY
TibrvMsg.I64ARRAY
TibrvMsg.U8ARRAY
TibrvMsg.U16ARRAY
TibrvMsg.U32ARRAY
TibrvMsg.U64ARRAY
TibrvMsg.MSG
TibrvMsg.OPAQUE
TibrvMsg.STRING
TibrvMsg.XML
TibrvMsg.MSGARRAY
TibrvMsg.STRINGARRAY
Key
Homologous types; conversion always supported; no loss of information
S Supported conversion; always supported
N Numeric conversion; loss of information is possible (without warning)
+ Unsigned converted to signed integer with double bit precision; no loss of information
- Unsigned 64-bit integer interpreted as signed 64-bits; high bit interpreted as sign bit
Unsupported conversion

|
Get Scalar 61
Get Scalar
Convenience Methods
Declaration scalar_type getScalar_type(

int fieldId)
scalar_type getAsScalar_type(
int fieldId)
Purpose Get the value of a field as a scalar value.
Remarks Each convenience method in this family retrieves a field and extracts its data. If
the field’s type (as it exists) does not match the type of the convenience method,
then the gettype method throws an exception; in contrast, the getAstype method
attempts to convert the data (see Decoding and Type Conversion on page 59, and
Wire Format to Java Datatype Conversion Matrix on page 60). If conversion is not
possible, the method throws an exception with status code
TibrvStatus.CONVERSION_FAILED.
(Sheet 1 of 2)
Method Name Field Type Java Type Type Description

getBoolean TibrvMsg.BOOL boolean boolean
getAsBoolean
getFloat TibrvMsg.F32 float 32-bit floating point

getAsFloat
getDouble TibrvMsg.F64 double 64-bit floating point

getAsDouble

62
| Chapter 4 Data
(Sheet 2 of 2)
Method Name Field Type Java Type Type Description

getByte TibrvMsg.I8 byte 8-bit integer
getAsByte
getShort TibrvMsg.I16 short 16-bit integer

getAsShort
getInt TibrvMsg.I32 int 32-bit integer

getAsInt
getLong TibrvMsg.I64 long 64-bit integer

getAsLong

|
TibrvMsg.getAsBytes() 63
TibrvMsg.getAsBytes()
Method
Declaration byte[] getAsBytes() throws TibrvException
Purpose Extract the data from a message as a byte sequence.
Remarks Return a copy of the message data as a byte sequence, suitable for archiving in a
file. To reconstruct the message from bytes, see TibrvMsg() on page 50.
The byte data includes the message header and all message fields in Rendezvous
wire format. It does not include address information, such as the subject and reply
subject, nor certified delivery information.
The byte sequence can contain interior null bytes.
See Also TibrvMsg() on page 50

64
| Chapter 4 Data
TibrvMsg.getByteSize()
Method
Declaration int getByteSize()

Purpose Return the size of a message (in bytes).
Remarks This measurement accounts for the actual space that the message occupies (in
wire format), including its header and its fields. It does not include address
information, such as the subject or reply subject.
Programs can use this function as part of these tasks:
• Assess throughput rates.
• Limit output rates (also called throttling).

|
TibrvMsg.getField() 65
TibrvMsg.getField()
Method
Declaration TibrvMsgField getField(

TibrvMsgField getField(
int fieldId)
TibrvMsgField getField(
int fieldId)
Purpose Get a specified field from a message.
Remarks Programs specify the field to retrieve using the fieldName and fieldId
parameters.
The method takes a snapshot of the field, and returns that information as a field
object.
Programs can use a related method to loop through all the fields of a message; to
retrieve each field by its integer index number, see
TibrvMsg.getFieldByIndex() on page 66.
Method Forms With only a field name, find the field by name. If the field name is not present in
the message, return null. If several fields with that name are present in the
message, this method returns the first one that it finds.
With only a field identifier, find the field with that identifier (since identifiers are
unique, the message can contain at most one such field). If the identifier is not
present in the message, return null.
With both a field name and a field identifier, search first by identifier, and then by
field name. If neither are present in the message, return null.
See Also TibrvMsg.get() on page 57

66
| Chapter 4 Data
TibrvMsg.getFieldByIndex()
Method
Declaration TibrvMsgField getFieldByIndex(int fieldIndex)

throws ArrayIndexOutOfBoundsException TibrvException
Purpose Get a field from a message by an index.
Remarks Programs can loop through all the fields of a message, to retrieve each field in
turn using an integer index.
object.
Add, remove and update calls can perturb the order of fields (which, in turn, affects
the results when a program gets a field by index).
fieldIndex Get the field with this index. Zero specifies the first field.

|
TibrvMsg.getFieldInstance() 67
TibrvMsg.getFieldInstance()
Method
Declaration TibrvMsgField getFieldInstance(

int instance)
Purpose Get a specific instance of a field from a message.
Remarks When a message contains several field instances with the same field name,
retrieve a specific instance by number (for example, get the ith field named foo).
Programs can use this method in a loop that examines every field with a specified
name.
The argument 1 denotes the first instance of the named field.
object.
The method copies scalar data into the field object. Non-scalar data extracted
from the field remain valid until the message is destroyed; that is, even removing
the field or updating the field’s value does not invalidate non-scalar data (such as
arrays, strings, submessages, XML data, or opaque byte sequences).
When the instance argument is greater than the actual number of instances of
the field in the message, this method returns null.
Release 5 Rendezvous 5 (and earlier) did not support array datatypes. Some older
Interaction programs circumvented this limitation by using several fields with the same
name to simulate arrays. This work-around is no longer necessary, since release 6
(and later) supports array datatypes within message fields. The method
TibrvMsg.getFieldInstance() ensures backward compatibility, so new
programs can still receive and manipulate messages sent from older programs.
Nonetheless, we encourage programmers to use array types as appropriate, and
we discourage storing several fields with the same name in a message.
fieldName Get an instance of the field with this name.
null specifies the empty string as the field name.
instance Get this instance of the specified field name. The argument 1
denotes the first instance of the named field.
See Also TibrvMsgField on page 87

68
| Chapter 4 Data
TibrvMsg.getNumFields()
Method
Declaration int getNumFields()
Purpose Extract the number of fields in a message.
Remarks This method counts the immediate fields of the message; it does not descend into
submessages to count their fields recursively.

|
TibrvMsg.getReplySubject() 69
TibrvMsg.getReplySubject()
Method
Declaration java.lang.String getReplySubject()
Purpose Extract the reply subject from a message.
Remarks The reply subject string is part of a message’s address information—it is not part
of the message itself.
If the reply subject is not set, this method returns null.
See Also TibrvMsg.setReplySubject() on page 77

Supplementary Information for Messages on page 41 in TIBCO Rendezvous
Concepts

70
| Chapter 4 Data
TibrvMsg.getSendSubject()
Method
Declaration java.lang.String getSendSubject()
Purpose Extract the subject from a message.
Remarks The subject string is part of a message’s address information—it is not part of the
message itself.
If the destination subject is not set, this method returns null.
See Also TibrvMsg.setSendSubject() on page 78

Concepts

|
TibrvMsg.getStringEncoding() 71
TibrvMsg.getStringEncoding()
Method
Declaration static java.lang.String getStringEncoding()
Purpose Return the character encoding for converting between Java Strings and wire
format strings.

TibrvMsg.setStringEncoding() on page 79

72
| Chapter 4 Data
TibrvMsg.getTypeName()
Method
Declaration static java.lang.String getTypeName(short type)
Purpose Convert a type designator to its corresponding string name.
Remarks This static method returns string representations of the TibrvMsg datatype
constants. For example, it converts the type constant TibrvMsg.I8ARRAY to the
string "I8ARRAY".
For custom datatypes, this method returns a string of the form "USER_FIRST+3"
(for example).
If the type is invalid, this method returns the string INVALID.
type Convert this type constant to a string name.
See Also Datatype Constants, page 48

TibrvMsg.setHandlers() on page 332

|
TibrvMsg.removeField() 73
TibrvMsg.removeField()
Method
Declaration boolean removeField(

boolean removeField(
int fieldId)
boolean removeField(
int fieldId)
Purpose Remove a field from a message.
fieldName Remove the field with this name.
fieldId Remove the field with this identifier.
Method Forms This method uses this algorithm to find and remove a field within a message, as
and the Field specified by a field identifier and a field name.
Search
Algorithm
begin at step 3.
with that identifier. If the search succeeds, remove the field and return true.
On the search does not find a field, continue to step 2.
On the search does not find a field, or if the program supplied null as the
field name, return false.
If the name search succeeds, but the actual identifier in the field is non-zero
If the search succeeds, remove the field and return true.
then begin here.
If the search succeeds, remove the field and return true.

74
| Chapter 4 Data
If the search does not find a field, return false.
If a message contains several fields with the same name, searching by name
removes the first instance of the field with that name.

|
TibrvMsg.removeFieldInstance() 75
TibrvMsg.removeFieldInstance()
Method
Declaration boolean removeFieldInstance(

int instance)
Purpose Remove a specified instance of a field from a message.
Remarks When a message contains several field instances with the same field name,
remove a specific instance by number (for example, remove the ith field named
foo). Programs can use this method in a loop that examines every field with a
specified name.
The argument 1 denotes the first instance of the named field.
If the specified instance does not exist, the method returns false.
fieldName Remove the field with this name.
instance Remove this instance of the field. The argument 1 specifies the
first instance of the named field.

76
| Chapter 4 Data
TibrvMsg.reset()
Method
Declaration void reset()

Purpose Clear a message, preparing it for re-use.
Remarks This method is the equivalent of creating a new message—except that the
unmanaged storage is re-used.
When this method returns, the message has no fields; it is like a newly created
message. The message’s address information is also reset.
See Also TibrvMsg() on page 50

|
TibrvMsg.setReplySubject() 77
TibrvMsg.setReplySubject()
Method
Declaration void setReplySubject(java.lang.String replySubject)

Purpose Set the reply subject for a message.
Remarks A receiver can reply to an inbound message using its reply subject.
Rendezvous routing daemons modify subjects and reply subjects to enable
transparent point-to-point communication across network boundaries. This
modification does not apply to subject names stored in message data fields; we
discourage storing point-to-point subject names in data fields.
replySubject Use this string as the new reply subject, replacing any
existing reply subject.
The reply subject null removes the previous reply subject.
See Also TibrvMsg.getReplySubject() on page 69

Concepts

78
| Chapter 4 Data
TibrvMsg.setSendSubject()
Method
Declaration void setSendSubject(java.lang.String subject)

Purpose Set the subject for a message.
Remarks The subject of a message can describe its content, as well as its destination set.
Rendezvous routing daemons modify subjects and reply subjects to enable
transparent point-to-point communication across network boundaries. This
modification does not apply to subject names stored in message data fields; we
discourage storing point-to-point subject names in data fields.
subject Use this string as the new subject, replacing any existing
subject.
The subject null removes the previous subject, leaving the
message unsendable.
See Also TibrvMsg.getSendSubject() on page 70

Concepts

|
TibrvMsg.setStringEncoding() 79
TibrvMsg.setStringEncoding()
Method
Declaration static void setStringEncoding(

java.lang.String encoding)
throws java.io.UnsupportedEncodingException
Purpose Set the character encoding for converting between Java Unicode strings and wire
format strings.
Remarks This method overrides the default string encoding for all strings in all messages.
null indicates the ISO 8859-1 (Latin-1) encoding:

• To translate Unicode strings to Latin-1 strings, disregard the null high byte of
each character. Unicode characters with non-null high bytes are out of the
Latin-1 range.
• To translate Latin-1 strings to Unicode strings, pad each character with a null
high byte.
Do not call this method while any listener events are valid. We recommend setting
it at program start, before creating any listeners.
Encoding changes are not retroactive; that is, changing the encoding affects only
future string translations. For further details, see Strings and Character Encodings
on page 3.
encoding Use this encoding.

TibrvMsg.getStringEncoding() on page 71
www.unicode.org

80
| Chapter 4 Data
TibrvMsg.toString()
Method
Declaration java.lang.String toString()
Purpose Format a message as a string.
Remarks Programs can use this method to obtain a string representation of the message for
printing.
For most datatypes, this method formats the full value of the field to the output
string; these types are exceptions:
TibrvMsg.OPAQUE This method abbreviates the value of an opaque field; for
example, [472 opaque bytes].
TibrvMsg.XML This method abbreviates the value of an XML field; for
example, [XML document: 472 bytes].
The size measures uncompressed data.
This method formats TibrvMsg.IPADDR32 fields as four dot-separated decimal

integers.
This method formats TibrvMsg.IPPORT16 fields as one decimal integer.

|
TibrvMsg.update() 81
TibrvMsg.update()
Method
Declaration void update(

void update(
short type)
void update(
short type,
int fieldId)
Purpose Update a field within a message.
Remarks This method copies the new data into the message field. All related convenience
methods behave similarly.
This method locates a field within the message by matching the fieldName and
fieldId arguments. Then it updates the message field using the data argument.
(Notice that only the value and count of the message field can change.)
If no existing field matches the specifications in the fieldName and fieldId
arguments, then this method adds a new field to the message. Update
convenience methods also add a field if it is not present.
The type of the existing message field and the type of the updating field
argument must be identical; otherwise, the method throws an exception with the
error status code TibrvStatus.INVALID_TYPE. However, when updating array
or vector fields, the count (number of elements) can change.
(Sheet 1 of 2)
fieldName Update a field with this name.
When absent, locate the field by identifier only.

82
| Chapter 4 Data
(Sheet 2 of 2)
data Update a field using this data value.
It is illegal to add or update a field with null data. To remove
a field, use TibrvMsg.removeField() on page 73.
type Update a field with this type.

When absent, determine the field’s type from the type of the
data.
Default encodings and possible conversions are identical to
methods that add fields; see Figure 5 on page 53.
fieldId Update a field with this identifier. All field identifiers must be
Zero is a special value, indicating no identifier. It is illegal to
add a field that has both a null field name, and a non-zero
field identifier.
Field Search Algorithm

This method, and related methods that update message fields, all use this
algorithm to find and update a field within a message, as specified by a field
identifier and a field name.
begin at step 3.
with that identifier.
If the search succeeds, then update that field.
On failure, continue to step 2.
If the search succeeds, then update that field.
If the name search succeeds, but the actual identifier in the field is non-null
If the search fails, add the field as specified (with name and identifier).

|
TibrvMsg.update() 83
However, if the program supplied null as the field name, then do not search
for the field name; instead, throw an exception with the status code
TibrvStatus.NOT_FOUND.
then begin here.
If the search fails, add the field as specified (with name and identifier).
If a message contains several fields with the same name, searching by name finds
the first instance of the field with that name.
Nested Message When the new value is a message object, this method uses only the data portion of
the nested message (data); it does not include any address information or
certified delivery information.

84
| Chapter 4 Data
Update Scalar
Convenience Methods
Declaration void update(

scalar_type data)
void update(
scalar_type data,
int fieldId)
void updateUbits(
scalar_type data)
void updateUbits(
scalar_type data,
int fieldId)
Purpose Update a field containing a scalar value.
Method Forms The convenience methods named update() determine the field type from the
numeric type of the data.
The convenience methods named updateUnn() update unsigned integer fields,
discarding the sign bit of a Java integer data value.

update boolean TibrvMsg.BOOL boolean
update float TibrvMsg.F32 32-bit floating point
update double TibrvMsg.F64 64-bit floating point
update byte TibrvMsg.I8 8-bit integer
update short TibrvMsg.I16 16-bit integer
update int TibrvMsg.I32 32-bit integer
update long TibrvMsg.I64 64-bit integer
updateU8 byte TibrvMsg.U8 8-bit unsigned integer

|
Update Scalar 85

updateU16 short TibrvMsg.U16 16-bit unsigned integer
updateU32 int TibrvMsg.U32 32-bit unsigned integer
updateU64 long TibrvMsg.U64 64-bit unsigned integer
data Update a field with this data value.
It is illegal to add or update a field with null data.
fieldName Update a field with this name.

When absent, locate the field by identifier only.
fieldId Update a field with this identifier. All field identifiers must be
Zero is a special value, indicating no identifier. It is illegal to
add a field that has both a null field name, and a non-zero
field identifier.

86
| Chapter 4 Data
TibrvMsg.updateField()
Method
Declaration void updateField(TibrvMsgField field)

Purpose Update a field within a message.
Remarks This method copies the new data into the existing message field. All related
convenience methods behave similarly.
This method locates a field within the message by matching the name and
identifier of field. Then it updates the message field using the field argument.
(Notice that the program may not supply a field object with a different field name,
field identifier, or datatype.)
If no existing field matches the specifications in the field argument, then this
method adds the field to the message. Update convenience methods also add the
field if it is not present. It is illegal to add a field that has both a null field name,
and a non-zero field identifier.
The type of the existing message field and the type of the updating field
argument must be identical; otherwise, the method returns the error status code
TibrvStatus.INVALID_TYPE. However, when updating array or vector fields, the
count (number of elements) can change.
field Update the existing message field using this field.

|
TibrvMsgField 87
TibrvMsgField
Class
Declaration class com.tibco.tibrv.TibrvMsgField

Purpose Represent a message field.
Field Description
name Field name, of type java.lang.String.
Names must be strings; null is a special value that indicates no name.
Field names use the character encoding appropriate to the ISO locale; see Strings and
Character Encodings on page 3.
id Field identifier, of type int.

Identifiers must be in the range [0-65535]; zero is a special value that indicates no
identifier.
data Data content of the field, a java.lang.Object.

When storing data in this field, Rendezvous software does not verify that the data and
type of the field are consistent. Methods that add the field object into a message verify
consistency (for example TibrvMsg.addField() and TibrvMsg.updateField()).
type Type designator for the data, a short.

For a list of types, see Datatype Constants on page 48. To interpret a type designator as
a string, see TibrvMsg.getTypeName() on page 72.
When storing a type designator in this field, Rendezvous software does not verify that
the data and type of the field are consistent. Methods that add the field object into a
message verify consistency (for example TibrvMsg.addField() and
TibrvMsg.updateField()).
If absent, the default type is TibrvMsg.DEFAULT, which instructs

TibrvMsg.addField() and TibrvMsg.updateField() to use the default type
corresponding to the data value.

88
| Chapter 4 Data

TibrvMsgField() Create a message field object. 89
TibrvMsgField.toString() Format a field as a string. 91
Inherited Methods
See Also TibrvMsg.addField()on page 56

TibrvMsg.getField()on page 65
TibrvMsg.updateField() on page 86

|
TibrvMsgField() 89
TibrvMsgField()
Constructor
Declaration TibrvMsgField()
TibrvMsgField(TibrvMsgField field)
TibrvMsgField(
java.lang.String name,
short type,
int id)
TibrvMsgField(
short type)
TibrvMsgField(
Purpose Create a message field object.
Method Forms With no arguments, create an empty field (no name, no identifier, no data, no
type).
With a field argument, create an independent copy of the field.
Name, identifier, data and type arguments contribute to the contents of the field
object.
Remarks This constructor does not verify that the data and type of the field are consistent.
Methods that add the field object into a message verify consistency (for example
TibrvMsg.addField() and TibrvMsg.updateField()).
(Sheet 1 of 2)
field Create an independent copy of this field.
name Create a field with this name.

To create a field with no name, supply null.
id Create a field with this identifier.

Identifiers must be in the range [0-65535]; zero is a special value
that indicates no identifier.

90
| Chapter 4 Data
(Sheet 2 of 2)
data Create a field with this data value.
The data value must be non-null.
type Create a field with this type.

For a list of types, see Datatype Constants on page 48.
If absent, the default type is TibrvMsg.DEFAULT, which instructs
the methods TibrvMsg.addField() and
TibrvMsg.updateField() to use the default type
corresponding to the data value.
See Also TibrvMsg.addField() on page 56

TibrvMsg.updateField() on page 86

|
TibrvMsgField.toString() 91
TibrvMsgField.toString()
Method
Declaration java.lang.String toString()
Purpose Format a field as a string.
Remarks Programs can use this method to obtain a string representation of the field for
printing.

92
| Chapter 4 Data
TibrvDate
Class
Declaration class com.tibco.tibrv.TibrvDate

extends java.util.Date
Purpose Represent date and time.

This object relies on the method java.util.Date.toString() to convert a value
to a string.
TibrvDate.MAX_SECONDS Maximum date (in seconds) that this class can represent.
The value is 549,755,813,887 (the maximum value of a 40-bit signed
integer), which is approximately 17,432 years after the year 1970.
TibrvDate.MIN_SECONDS Minimum date (in seconds) that this class can represent.
The value is -549,755,813,888 (the minimum value of a 40-bit signed
integer), which is approximately 17,432 years before the year 1970.

TibrvDate() Create a Rendezvous date object. 95
TibrvDate.getTimeNanoseconds() Extract the modifying value (in nanoseconds) of a 96

date object.
TibrvDate.getTimeSeconds() Extract the partial value (in whole seconds) of a 97

date object.
TibrvDate.setTime() Change the value of a date object. 98

|
TibrvDate 93
Inherited Methods
java.util.Date.after
java.util.Date.before
java.util.Date.clone
java.util.Date.compareTo
java.util.Date.getDate
java.util.Date.getDay
java.util.Date.getHours
java.util.Date.getMinutes
java.util.Date.getMonth
java.util.Date.getSeconds
java.util.Date.getTime
java.util.Date.getTimezoneOffset
java.util.Date.getYear
java.util.Date.hashCode
java.util.Date.parse
java.util.Date.setDate
java.util.Date.setHours
java.util.Date.setMinutes
java.util.Date.setMonth
java.util.Date.setSeconds
java.util.Date.setYear
java.util.Date.toGMTString
java.util.Date.toLocaleString
java.util.Date.toString
java.util.Date.UTC
Representations In all three representations, zero denotes the epoch, 12:00 midnight, January 1st,
1970. Range limits in this table denote the extreme value on either side of that
center. Bold type indicates the primary unit of measurement for each
representation.
Table 5 Date and Time Representations (Sheet 1 of 2)
Representation Details
java.util.Date Milliseconds as a 64-bit signed integer.
range in years 292,471,208
range in seconds 9,223,372,036,854,775
range in milliseconds 9,223,372,036,854,775,807

94
| Chapter 4 Data
Table 5 Date and Time Representations (Sheet 2 of 2)
Representation Details
TibrvDate Seconds as a 64-bit signed integer, plus nanoseconds as a 32-bit unsigned
integer.
However, values are restricted to the range and granularity supported by
Rendezvous wire format. Forcing larger or finer values into this representation
causes an exception.
range in years 292,471,208,677
range in seconds 9,223,372,036,854,775,807
restricted range in seconds 549,755,813,887
restricted range in milliseconds 549,755,813,887,000
Rendezvous wire Seconds as a 40-bit signed integer, plus microseconds as a 24-bit unsigned
format integer.
range in years 17,432
range in seconds 549,755,813,887
range in milliseconds 549,755,813,887,000

|
TibrvDate() 95
TibrvDate()
Constructor
Declaration TibrvDate()
TibrvDate(java.util.Date date)
TibrvDate(long milliseconds)
TibrvDate(
long seconds,
int nanoseconds)
Purpose Create a Rendezvous date object.
Remarks If the time value specified is out of range, this constructor throws an
IllegalArgumentException.
date Copy the value of this Java date or Rendezvous date object
into an independent copy object.
milliseconds Create a date from this value (in milliseconds, centered on

12:00am, January 1, 1970).
seconds Create a date from this value (in seconds, centered on

12:00am, January 1, 1970).
nanoseconds Add this value (in nanoseconds) to the time specified by

the seconds parameter. This argument must be
non-negative.
Method Forms With no arguments, create a date object representing the current time.
With an argument of class java.util.Date (or a subclass), create a TibrvDate
object representing the same date value.
With one argument, interpret that long as the date in milliseconds. For example,
specify the time 1/2 second before midnight of December 31, 1969 as -500
milliseconds.
With two arguments, interpret them as seconds and (non-negative) nanoseconds.
For example, specify the time 1/2 second before midnight of December 31, 1969
as -1 seconds plus 500,000,000 nanoseconds.
See Also TibrvDate on page 92

Representations, page 93

96
| Chapter 4 Data
TibrvDate.getTimeNanoseconds()
Method
Declaration int getTimeSeconds()
Purpose Extract the modifying value (in nanoseconds) of a date object.
Remarks This value is always non-negative, between zero and 999999999.

It modifies the date in whole seconds (as returned by
TibrvDate.getTimeSeconds() on page 97), by specifying the number of
nanoseconds after that date. For example, the time 1/2 second before midnight of
December 31, 1969 is -1 seconds plus 500,000,000 nanoseconds.
See Also TibrvDate.getTimeSeconds() on page 97

|
TibrvDate.getTimeSeconds() 97
TibrvDate.getTimeSeconds()
Method
Declaration long getTimeSeconds()
Purpose Extract the partial value (in whole seconds) of a date object.
Remarks The value is the date in seconds, centered on 12:00am, January 1, 1970.
To get the modifying nanosecond value, use TibrvDate.getTimeNanoseconds()
on page 96.
See Also TibrvDate.getTimeNanoseconds() on page 96

98
| Chapter 4 Data
TibrvDate.setTime()
Method
Declaration void setTime(long milliseconds)
void setTime(
long seconds,
int nanoseconds)
Purpose Change the value of a date object.
Remarks If the time value specified is out of range, this constructor throws an
IllegalArgumentException.
milliseconds Set the date from this value (in milliseconds, centered on
12:00am, January 1, 1970).
seconds Set the a date from this value (in seconds, centered on
12:00am, January 1, 1970). This argument must be in the
range
[TibrvDate.MIN_SECONDS;TibrvDate.MAX_SECONDS].
nanoseconds Add this value (in nanoseconds) to the time specified by

the seconds parameter. This argument must be
non-negative, in the range [0;999999999].
Method Forms With one argument, interpret it as the date in milliseconds. For example, specify
the time 1/2 second before midnight of December 31, 1969 as -500 milliseconds.
With two arguments, interpret them as seconds and (non-negative) nanoseconds.
For example, specify the time 1/2 second before midnight of December 31, 1969
as -1 seconds plus 500,000,000 nanoseconds.
See Also Representations, page 93

TibrvIPAddr 99
|
TibrvIPAddr
Class
Declaration class com.tibco.tibrv.TibrvIPAddr

Purpose Represent an IP address.
Remarks In general, an IP address consists of four 8-bit unsigned integers, in network byte
order.

TibrvIPAddr() Create an IP address object. 100
TibrvIPAddr.getAddr() Get an IP address as a 32-bit integer. 101
TibrvIPAddr.getAsBytes() Get an IP address as a 4-byte array. 102
TibrvIPAddr.getAsString() Get an IP address as a String. 103
Inherited Methods
java.lang.Object.toString (override)

100
| Chapter 4 Data
TibrvIPAddr()
Constructor
Declaration TibrvIPAddr(byte[] bytes)
TibrvIPAddr(
java.net.InetAddress inetAddr)
TibrvIPAddr(
byte b1,
byte b2,
byte b3,
byte b4)
TibrvIPAddr(
java.lang.String ipString)
throws java.lang.NumberFormatException
TibrvIPAddr(int address)
TibrvIPAddr(TibrvIPAddr ipAddr)
Purpose Create an IP address object.
bytes Create an IP address from an array of 4 bytes. For
aaa.bbb.ccc.ddd, let bytes[0] be the high byte aaa, and
bytes[3] be the low byte ddd.
b1, b2, b3, b4 Create an IP address from these 4 bytes. For

aaa.bbb.ccc.ddd, let b1 be the high byte aaa, and b4 be
the low byte ddd.
address Create an IP address from a 32-bit integer, interpreted as 4

bytes in network byte order.
ipString Create an IP address from a string representation (for

example, "aaa.bbb.ccc.ddd").
inetAddr Copy this Java 4-byte internet address into a TibrvIPAddr

object with an equivalent value. (TibrvIPAddr supports
only 4-byte IP addresses.)
ipAddr Make an independent copy of this TibrvIPAddr object.
Remarks If the ipString argument does not represent a valid IP address, this constructor
throws a java.lang.NumberFormatException.

|
TibrvIPAddr.getAddr() 101
TibrvIPAddr.getAddr()
Method
Declaration final int getAddr()
Purpose Get an IP address as a 32-bit integer.

102
| Chapter 4 Data
TibrvIPAddr.getAsBytes()
Method
Declaration final byte[] getAsBytes()
Purpose Get an IP address as a 4-byte array.
Remarks The zeroth element is the high byte.

|
TibrvIPAddr.getAsString() 103
TibrvIPAddr.getAsString()
Method
Declaration final java.lang.String getAsString()
Purpose Get an IP address as a String.
Remarks This method returns a string composed of four decimal integers (in the form
"aaa.bbb.ccc.ddd").

104
| Chapter 4 Data
TibrvIPPort
Class
Declaration class com.tibco.tibrv.TibrvIPPort

Purpose Represent an IP port number.
Remarks In general, an IP Port number is an unsigned 16-bit integer [0;65535], in network

byte order. This class represents a port number as a 32-bit integer, because Java
does not support unsigned numbers.
TibrvIPPort.MAX_PORT Maximum port number that this class can
represent (65535).
TibrvIPPort.MIN_PORT Minimum port number that this class can

represent (zero).

TibrvIPPort() Create an IP port object. 105
TibrvIPPort.getPort() Get an IP port as a 32-bit integer. 106
TibrvIPPort.getAsBytes() Get an IP port as a 2-byte array. 107
Inherited Methods

|
TibrvIPPort() 105
TibrvIPPort()
Constructor
Declaration TibrvIPPort(
byte highByte,
byte lowByte)
TibrvIPPort(int port)
TibrvIPPort(TibrvIPPort ipPort)
Purpose Create an IP port object.
highByte, lowByte Create an IP port from these 2 bytes.
port Create an IP port from the 2 low bytes of this 32-bit

integer, which must be in the range [0;65535].
ipPort Make an independent copy of this TibrvIPPort

object.

106
| Chapter 4 Data
TibrvIPPort.getPort()
Method
Declaration int getPort()
Purpose Get an IP port as a 32-bit integer.
Remarks The value is always in the range [0;65535].

|
TibrvIPPort.getAsBytes() 107
TibrvIPPort.getAsBytes()
Method
Declaration byte[] getAsBytes()
Purpose Get an IP port as a 2-byte array.
Remarks The high byte is the zeroth element.

108
| Chapter 4 Data
TibrvXml
Class
Declaration class com.tibco.tibrv.TibrvXml

Purpose Represent an XML byte array.
Remarks Within programs, XML data is represented as a byte array. Within message fields,
Rendezvous software compresses the bytes for efficient network transmission.

TibrvXml() Create an XML data object. 109
TibrvXml.getBytes() Get the data bytes from an XML data object. 110
Inherited Methods

|
TibrvXml() 109
TibrvXml()
Constructor
Declaration TibrvXml (byte[] xmlBytes)
Purpose Create an XML data object.
xmlBytes Create an XML data object from this byte array.

110
| Chapter 4 Data
TibrvXml.getBytes()
Method
Declaration byte[] getBytes()
Purpose Get the data bytes from an XML data object.

| 111
Chapter 5 Events and Queues
Programs can express interest in events of two kinds—inbound messages and

timers. When an event occurs, it triggers a program callback method to process
the event. Events wait in queues until programs dispatch them. Dispatching an
event runs its callback method to process the event.
Event queues organize events awaiting dispatch. Programs dispatch events to run
callback methods.
Queue groups add flexibility and fine-grained control to the event queue dispatch
mechanism. Programs can create groups of queues and dispatch them according
to their queue priorities.
This chapter presents classes, methods, interfaces and types associated with event
interest and event processing.
Topics
• TibrvEvent, page 112

• TibrvListener, page 118
• TibrvMsgCallback, page 124
• TibrvTimer, page 126
• TibrvTimerCallback, page 132
• TibrvDispatchable, page 134
• TibrvQueue, page 138
• TibrvQueueGroup, page 157

112
| Chapter 5 Events and Queues
TibrvEvent
Class
Declaration class com.tibco.tibrv.TibrvEvent

Purpose Event objects represent program interest in events, and event occurrences.
Remarks Programs create instances of event subclasses of TibrvEvent, but not of this
superclass.
Each call to a Rendezvous event constructor results in a new event object, which
represents your program’s interest in a set of events. Rendezvous software uses
the same event object to signal each occurrence of such an event.
Destroying an event object cancels the program’s interest in that event.
Destroying the queue or transport of an event automatically destroys the event as
well.
Although the fault tolerance classes are technically events, they are sufficiently
different from listeners and timers that they require separate description. See
Chapter 8, Fault Tolerance, on page 217.

TibrvEvent.destroy() Destroy an event, canceling interest. 114
TibrvEvent.getClosure() Extract the closure data of an event object. 115
TibrvEvent.getQueue() Extract the queue of an event object. 116
TibrvEvent.isValid() Test whether an event has been destroyed. 117
Inherited Methods
Descendants TibrvListener on page 118

TibrvCmListener on page 250
TibrvTimer on page 126

|
TibrvEvent 113
TibrvFtMember on page 219

TibrvFtMonitor on page 239

114
TibrvEvent.destroy()
Method
Declaration void destroy()
Purpose Destroy an event, canceling interest.
Remarks Destroying an event object cancels interest in it. Upon return from
TibrvEvent.destroy(), the destroyed event is no longer dispatched. However,
all active callback methods of this event continue to run and return normally, even
though the event is invalid.
It is legal for an event callback method to destroy its own event argument.
Destroying event interest invalidates the event object; subsequent API calls
involving the invalid event throw exceptions, unless explicitly documented to the
contrary.
See Also TibrvEvent.isValid() on page 117

|
TibrvEvent.getClosure() 115
TibrvEvent.getClosure()
Method
Declaration java.lang.Object getClosure()
Purpose Extract the closure data of an event object.
Remarks This method can extract the closure data even from invalid events.

116
TibrvEvent.getQueue()
Method
Declaration TibrvQueue getQueue()
Purpose Extract the queue of an event object.
Remarks If the event is invalid, this method returns null.

|
TibrvEvent.isValid() 117
TibrvEvent.isValid()
Method
Declaration boolean isValid()
Purpose Test whether an event has been destroyed.
Remarks This method returns true if the event is valid, and false if it has been destroyed.
Notice that TibrvEvent.destroy() invalidates the event immediately, even
though active callback methods may continue to run.
See Also TibrvEvent.destroy() on page 114

118
TibrvListener
Class
Declaration class com.tibco.tibrv.TibrvListener

extends TibrvEvent
Purpose Listen for inbound messages.
Remarks A listener object continues listening for messages until the program destroys it.
Programs must destroy instances of this class. Rendezvous software keeps
internal references to these objects, so the Java garbage collector does not delete
them automatically.
Destroying the queue or transport of an event automatically destroys the listener
as well.

TibrvListener() Create a listener object to listen for inbound 121
messages.
TibrvListener.getSubject() Extract the subject from a listener event object. 122
TibrvListener.getTransport() Extract the transport from a listener event object. 123
Inherited Methods
Activation and Dispatch

Inbound messages on the transport that match the subject trigger the event.

|
TibrvListener 119
This constructor creates a listener event object, and activates the event—that is, it
begins listening for all inbound messages with matching subjects. When a
message arrives, Rendezvous software places the event object and message on its
event queue. Dispatch removes the event object from the queue, and runs the
callback method to process the message. (To stop receiving inbound messages on
the subject, destroy the event object; this action cancels all messages already
queued for the listener event; see also TibrvEvent.destroy() on page 114.)
Figure 7 illustrates that messages can continue to accumulate in the queue, even
while the callback method is processing.
Figure 7 Listener Activation and Dispatch
5. Destroy listener event.

1. Create and activate listener event.
Messages stop arriving.
Listener Event Active
2. Message arrives. Event enters queue.
3. Dispatch event.
4. Callback function returns.

Event Callback
Waiting in Function Dispatch next event.
Queue Running
Callback
Event Waiting in
Function
Queue
Running
Callback
Event Waiting in Queue Function
Running
Callback
Event Waiting in Queue Function
Running
6. Destroying listener
Event Waiting in
More messages arrive. cancels messages in
Queue
the queue.

120
When the callback method is I/O-bound, messages can arrive faster than the
callback method can process them, and the queue can grow unacceptably long. In
programs where a delay in processing messages is unacceptable, consider
dispatching from several threads to process messages concurrently.
Descendants TibrvCmListener on page 250

|
TibrvListener() 121
TibrvListener()
Constructor
Declaration TibrvListener(
TibrvQueue queue,
TibrvMsgCallback callback,
TibrvTransport transport,
java.lang.String subject,
java.lang.Object closure)
Purpose Create a listener object to listen for inbound messages.
Remarks For each inbound message, place this event on the event queue.
queue For each inbound message, place the event on this event
queue.
callback On dispatch, process the event with this interface

implementation.
transport Listen for inbound messages on this transport.
subject Listen for inbound messages with subjects that match this
specification. Wildcard subjects are permitted. The empty
string is not a legal subject name.
closure Store this closure data in the event object.
Inbox Listener To receive unicast (point-to-point) messages, listen to a unique inbox subject
name. First call TibrvTransport.createInbox() to create the unique inbox
name; then call TibrvListener() to begin listening. Remember that other
programs have no information about an inbox until the listening program uses it
as a reply subject in an outbound message.
See Also TibrvEvent.destroy()on page 114

TibrvMsgCallbackon page 124
TibrvMsgCallback.onMsg() on page 125

122
TibrvListener.getSubject()
Method
Declaration java.lang.String getSubject()
Purpose Extract the subject from a listener event object.

|
TibrvListener.getTransport() 123
TibrvListener.getTransport()
Method
Declaration TibrvTransport getTransport()
Purpose Extract the transport from a listener event object.
Remarks If the listener is invalid (destroyed), return null.

124
TibrvMsgCallback
Interface
Declaration interface com.tibco.tibrv.TibrvMsgCallback
Purpose Process inbound messages (listener events).
Remarks Implement this interface to process inbound messages.

TibrvMsgCallback.onMsg() Process inbound messages (listener 125
events).
See Also TibrvListener() on page 121

TibrvMsgCallback.onMsg() 125
|
TibrvMsgCallback.onMsg()
Method
Declaration void onMsg(

TibrvListener listener,
TibrvMsg msg)
Purpose Process inbound messages (listener events).
Remarks Implement this method to process inbound messages.
listener This parameter receives the listener event.
msg This parameter receives the inbound message.
CM Label The callback method for certified delivery messages can use certified delivery
Information (CM) label information to discriminate these situations:
• If TibrvCmMsg.getSender() returns null, then the message uses the reliable
protocol (that is, it was sent from an ordinary transport).
• If TibrvCmMsg.getSender() returns a valid sender name, then the message
uses the certified delivery protocol (that is, it is a labeled message, sent from a
CM transport).
See Also TibrvCmListener()on page 252

TibrvCmMsg.getSender()on page 295
TibrvCmMsg.getSequence() on page 296
TibrvCmMsg.getTimeLimit() on page 298

126
TibrvTimer
Class
Declaration class com.tibco.tibrv.TibrvTimer

extends TibrvEvent
Purpose Timer event.
Remarks All timers are repeating timers. To simulate a once-only timer, code the callback
method to destroy the timer.
them automatically.
Destroying the queue of a timer automatically destroys the timer as well.
Activation and The constructor creates a timer event object, and activates the timer event—that is,
Dispatch it requests notification from the operating system when the timer’s interval
elapses. When the interval elapses, Rendezvous software places the event object
on its event queue. Dispatch removes the event object from the queue, and runs
the callback method to process the timer event. When the callback method begins,
Rendezvous software automatically reactivates the event, using the same interval.
On dispatch Rendezvous software also determines whether the next interval has
already elapsed, and requeues the timer event if appropriate. (To stop the cycle,
destroy the event object; see TibrvEvent.destroy() on page 114.)
Notice that time waiting in the event queue until dispatch can increase the
effective interval of the timer. It is the programmer’s responsibility to ensure
timely dispatch of events.
Figure 8 illustrates a sequence of timer intervals. The number of elapsed timer
intervals directly determines the number of event callbacks.
At any moment the timer object appears on the event queue at most once—not
several times as multiple copies. Nonetheless, Rendezvous software arranges for
the appropriate number of timer event callbacks based the number of intervals
that have elapsed since the timer became active or reset its interval.
Destroying or invalidating the timer object immediately halts the sequence of timer
events. The timer object ceases to queue new events, and an event already in the
queue does not result in a callback. (However, callback methods that are already
running in other threads continue to completion.)
Resetting the timer interval immediately interrupts the sequence of timer events
and begins a new sequence, counting the new interval from that moment. The
reset operation is equivalent to destroying the timer and creating a new object in
its place.

|
TibrvTimer 127
Figure 8 Timer Activation and Dispatch
1. Activate timer.
Timer Timer Timer

Interval Interval Interval
2. Interval elapses. Event

Callback Function
Enter queue. Waiting in
Running
Queue
Event
3. Dispatch the event Callback Function
Waiting in
to its callback function. Running
Queue
4. Interval elapses. Event

Enter queue. Waiting in
Queue
5. Dispatch the event
to its callback function.
Timer Express the timer interval (in seconds) as a 64-bit floating point number. This
Granularity representation allows microsecond granularity for intervals for over 100 years.
The actual granularity of intervals depends on hardware, Java and operating
system constraints. Most releases of the JVM limit timer granularity to 10
milliseconds.
Zero as Interval Many programmers traditionally implement user events as timers with interval
zero. Instead, we recommend implementing user events as messages on the
intra-process transport. For more information, see Intra-Process Transport and
User Events on page 114 in TIBCO Rendezvous Concepts.

TibrvTimer() Start a timer. 129
TibrvTimer.getInterval() Extract the interval from a timer 130

event object.
TibrvTimer.resetInterval() Reset the interval of a timer event 131

object.

128
Inherited Methods
Descendants TibrvEvent on page 112

|
TibrvTimer() 129
TibrvTimer()
Constructor
Declaration TibrvTimer(
TibrvQueue queue,
TibrvTimerCallback callback,
double interval,
Purpose Start a timer.
Remarks All timers are repeating timers. To simulate a once-only timer, code the callback
method to destroy the timer.
queue At each time interval, place the event on this event queue.
callback On dispatch, process the event with this interface

implementation.
interval The timer triggers its callback method at this repeating interval
(in seconds).
Timer Express the timer interval (in seconds) as a double (64-bit floating point number).
Granularity This representation allows microsecond granularity for intervals for over 100
years. The actual granularity of intervals depends on Java implementation
constraints, as well as hardware and operating system constraints.
The JNI implementation supports fine-resolution timers through the underlying
C layer. Most releases of the JVM limit the Java implementation to 10 millisecond
resolution.
See Also TibrvEvent.destroy()on page 114

TibrvTimerCallbackon page 132
TibrvTimerCallback.onTimer() on page 133

130
TibrvTimer.getInterval()
Method
Declaration double getInterval()
Purpose Extract the interval from a timer event object.

|
TibrvTimer.resetInterval() 131
TibrvTimer.resetInterval()
Method
Declaration void resetInterval(double newInterval)

Purpose Reset the interval of a timer event object.
Remarks The timer begins counting the new interval immediately.
newInterval The timer triggers its callback method at this new repeating
interval (in seconds).
Timer Express the timer interval (in seconds) as a 64-bit floating point number. This
Granularity representation allows microsecond granularity for intervals up to approximately
146 years. The actual granularity of intervals depends on hardware and operating
system constraints.
Limit of This method can affect a timer only before or during its interval—but not after its
Effectiveness interval has elapsed.
This method neither examines, changes nor removes an event that is already
waiting in a queue for dispatch. If the next event for the timer object is already in
the queue, then that event remains in the queue, representing the old interval. The
change takes effect with the subsequent interval. (To circumvent this limitation, a
program can destroy the old timer object and replace it with a new one.)

132
TibrvTimerCallback
Interface
Declaration interface com.tibco.tibrv.TibrvTimerCallback
Purpose Process timer events.
Remarks Implement this interface to process timer events.

TibrvTimerCallback.onTimer() Process timer events. 133
See Also TibrvTimer() on page 129

|
TibrvTimerCallback.onTimer() 133
TibrvTimerCallback.onTimer()
Method
Declaration void onTimer(TibrvTimer timer)
Purpose Process timer events.
Remarks Implement this method to process timer events.
timer This parameter receives the timer event.

134
TibrvDispatchable
Interface
Declaration interface com.tibco.tibrv.TibrvDispatchable
Purpose Common interface for queues and queue groups.
Remarks Both TibrvQueue and TibrvQueueGroup implement this interface, so programs

can call the common methods on objects of either class. For example, consider a
dispatcher routine that receives an object of type TibrvDispatchable; it can call
the dispatch() method, without needing to determine whether the object is
queue or a queue group.

TibrvDispatchable.dispatch() Dispatch an event; if no event is ready, block. 135
TibrvDispatchable.poll() Dispatch an event, if possible. 136
TibrvDispatchable.timedDispatch() Dispatch an event, but if no event is ready to 137

dispatch, limit the time that this call blocks
while waiting for an event.
See Also Interrupting Event Dispatch Threads, page 5

TibrvQueue on page 138
TibrvQueueGroup on page 157

|
TibrvDispatchable.dispatch() 135
TibrvDispatchable.dispatch()
Method
Declaration void dispatch()

throws TibrvException, java.lang.InterruptedException
Purpose Dispatch an event; if no event is ready, block.
Remarks If an event is ready to dispatch, then this call dispatches it, and then returns. If no
events are waiting, then this call blocks indefinitely while waiting for the object to
receive an event.
Both TibrvQueue and TibrvQueueGroup implement this method.

TibrvDispatchable on page 134
TibrvQueue.dispatch() on page 143
Interrupting a Dispatch Call, page 143
TibrvQueueGroup.dispatch() on page 163

136
TibrvDispatchable.poll()
Method
Declaration boolean poll()

Purpose Dispatch an event, if possible.
events are waiting, then this call returns immediately.
When the call dispatches an event, it returns true. When the call does not
dispatch an event, it returns false.
This call is equivalent to timedDispatch(0).

TibrvQueue.poll() on page 152
TibrvQueueGroup.poll() on page 167

|
TibrvDispatchable.timedDispatch() 137
TibrvDispatchable.timedDispatch()
Method
Declaration boolean timedDispatch(double timeout)

Purpose Dispatch an event, but if no event is ready to dispatch, limit the time that this call
blocks while waiting for an event.
events are waiting, this call waits for an event to arrive. If an event arrives before
the waiting time elapses, then it dispatches the event and returns. If the waiting
time elapses first, then the call returns without dispatching an event.
timeout Maximum time (in seconds) that this call can block while
waiting for an event to arrive.
Zero indicates no blocking (immediate timeout).
-1 indicates no timeout.

TibrvQueue.timedDispatch() on page 156
TibrvQueueGroup.timedDispatch() on page 169

138
TibrvQueue
Class
Declaration class com.tibco.tibrv.TibrvQueue

implements TibrvDispatchable
Purpose Event queue.
Remarks Each event is associated with a TibrvQueue object; when the event occurs,
Rendezvous software places the event object in its queue. Programs dispatch
queues to process events.
Programs must explicitly destroy instances of this class. Rendezvous software
keeps internal references to these objects, so the Java garbage collector does not
delete them automatically.
Default Queue The method Tibrv.defaultQueue() returns a pre-defined queue. Programs that
need only one event queue can use this default queue (instead of using
TibrvQueue() to create one). The default queue has priority 1, can hold an
unlimited number of events, and never discards an event (since it never exceeds
an event limit).
Rendezvous software places all advisories pertaining to queue overflow on the
default queue.
Programs cannot destroy the default queue, except as a side effect of
Tibrv.close(). Programs cannot change the parameters of the default queue.
Limit Policy These constants specify the possible strategies for resolving overflow of queue
limit.
TibrvQueue.DISCARD_NONE Never discard events; use this policy when a queue has no limit on
then number of events it can contain.
TibrvQueue.DISCARD_FIRST Discard the first event in the queue (that is, the oldest event in the
queue, which would otherwise be the next event to dispatch).
TibrvQueue.DISCARD_LAST Discard the last event in the queue (that is, the youngest event in
the queue).
TibrvQueue.DISCARD_NEW Discard the new event (which would otherwise cause the queue to
overflow its maximum events limit).

|
TibrvQueue 139

Life Cycle
TibrvQueue() Create an event queue. 141
TibrvQueue.destroy() Destroy an event queue. 142
TibrvQueue.isDefault() Test whether a queue is the default queue. 150
TibrvQueue.isValid() Test validity of a queue. 151
Dispatch
TibrvQueue.dispatch() Dispatch an event; if no event is ready, block. 143
TibrvQueue.poll() Dispatch an event, if possible. 152
TibrvQueue.timedDispatch() Dispatch an event, but if no event is ready to 156

dispatch, limit the time that this call blocks while
waiting for an event.
Properties
TibrvQueue.getCount() Extract the number of events in a queue. 144
TibrvQueue.getDiscardAmount() Extract the discard amount of a queue. 145
TibrvQueue.getLimitPolicy() Extract the limit policy of a queue. 146
TibrvQueue.getMaxEvents() Extract the maximum event limit of a queue. 147
TibrvQueue.getName() Extract the name of a queue. 148
TibrvQueue.getPriority() Extract the priority of a queue. 149
TibrvQueue.setName() Set the name of a queue. 153
TibrvQueue.setLimitPolicy() Set the limit properties of a queue. 154
TibrvQueue.setPriority() Set the priority of a queue. 155

140
Inherited Methods

|
TibrvQueue() 141
TibrvQueue()
Constructor
Declaration TibrvQueue()
Purpose Create an event queue.
Remarks Upon creation, new queues use these default values.
Property Default Value Set Method

limitPolicy TibrvQueue.DISCA TibrvQueue.setLimitPolicy() on page 154
RD_NONE
maxEvents zero (unlimited)
discardAmount zero
name tibrvQueue TibrvQueue.setName() on page 153
priority 1 TibrvQueue.setPriority() on page 155

142
TibrvQueue.destroy()
Method
Purpose Destroy an event queue.
Remarks When a queue is destroyed, events that remain in the queue are discarded.
Destroying a queue explicitly destroys all events associated with the queue; that
is, this method calls TibrvEvent.destroy() for each associated event.
A program must not call TibrvQueue.destroy() on the default queue. Closing
Tibrv destroys the default queue; see Tibrv.close() on page 26.

|
TibrvQueue.dispatch() 143
TibrvQueue.dispatch()
Method

Purpose Dispatch an event; if no event is ready, block.
Remarks If the queue is not empty, then this call dispatches the event at the head of the
queue, and then returns. If the queue is empty, then this call blocks indefinitely
while waiting for the queue to receive an event.
Interrupting a To interrupt an event dispatch thread in the Java implementation (see

Dispatch Call Tibrv.open() on page 32), use the Java method Thread.interrupt().
In the JNI (native) implementation, this call does not throw

InterruptedException; instead, programs must explicitly check for
interruptions by calling Thread.interrupted() before or after
TibrvQueue.dispatch().
The more reliable way to interrupt a JNI event dispatch thread is to destroy the
TibrvDispatchable object that the thread dispatches. When the dispatch call
encounters the invalid queue or queue group, it throws a TibrvException in the
event dispatch thread.

TibrvDispatchable.dispatch() on page 135
TibrvDispatcher on page 170

144
TibrvQueue.getCount()
Method
Declaration int getCount()

Purpose Extract the number of events in a queue.

|
TibrvQueue.getDiscardAmount() 145
TibrvQueue.getDiscardAmount()
Method
Declaration int getDiscardAmount()

Purpose Extract the discard amount of a queue.
Remarks When the queue exceeds its maximum event limit, discard a block of events. This
property specifies the number of events to discard.
See Also TibrvQueue.setLimitPolicy() on page 154

146
TibrvQueue.getLimitPolicy()
Method
Declaration int getLimitPolicy()

Purpose Extract the limit policy of a queue.
Remarks Each queue has a policy for discarding events when a new event would cause the
queue to exceed its maxEvents limit. For an explanation of the policy values, see
Limit Policy on page 138.

|
TibrvQueue.getMaxEvents() 147
TibrvQueue.getMaxEvents()
Method
Declaration int getMaxEvents()

Purpose Extract the maximum event limit of a queue.
Remarks Programs can limit the number of events that a queue can hold—either to curb
queue growth, or implement a specialized dispatch semantics.
Zero specifies an unlimited number of events.

148
TibrvQueue.getName()
Method
Declaration java.lang.String getName()
Purpose Extract the name of a queue.
Remarks Queue names assist programmers and administrators in troubleshooting queues.

When Rendezvous software delivers an advisory message pertaining to a queue,
it includes the queue’s name; administrators can use queue names to identify
specific queues within a program.
The default name of every queue is tibrvQueue. We strongly recommend that
you relabel each queue with a distinct and informative name, for use in
debugging.
This method returns the queue’s name, even when the queue is invalid.
See Also TibrvQueue.setName() on page 153

|
TibrvQueue.getPriority() 149
TibrvQueue.getPriority()
Method
Declaration int getPriority()

Purpose Extract the priority of a queue.
Remarks Each queue has a single priority value, which controls its dispatch precedence
within queue groups. Higher values dispatch before lower values; queues with
equal priority values dispatch in round-robin fashion.
When the queue is invalid, this method throws an exception.
See Also TibrvQueue.setPriority() on page 155

150
TibrvQueue.isDefault()
Method
Declaration final boolean isDefault()
Purpose Test whether a queue is the default queue.
Remarks Returns true if the queue is the default queue; false otherwise.
See Also Tibrv.defaultQueue() on page 27

|
TibrvQueue.isValid() 151
TibrvQueue.isValid()
Method
Declaration final boolean isValid()
Purpose Test validity of a queue.
Remarks Returns true if the queue is valid; false if the queue has been destroyed.
See Also Tibrv.close() on page 26

TibrvQueue.destroy() on page 142

152
TibrvQueue.poll()
Method

Purpose Dispatch an event, if possible.
Remarks If the queue is not empty, then this call dispatches the event at the head of the
queue, and then returns. If the queue is empty, then this call returns immediately.

TibrvDispatchable.poll() on page 136

|
TibrvQueue.setName() 153
TibrvQueue.setName()
Method
Declaration void setName(java.lang.String queueName)

Purpose Set the name of a queue.
Remarks Queue names assist programmers and administrators in troubleshooting queues.

When Rendezvous software delivers an advisory message pertaining to a queue,
it includes the queue’s name; administrators can use queue names to identify
specific queues within a program.
The default name of every queue is tibrvQueue. We strongly recommend that
you relabel each queue with a distinct and informative name, for use in
debugging.
queueName Replace the name of the queue with this new name.
It is illegal to supply null as the new queue name.
See Also TibrvQueue.getName() on page 148

154
TibrvQueue.setLimitPolicy()
Method
Declaration void setLimitPolicy(

int limitPolicy,
int maxEvents,
int discardAmount)
Purpose Set the limit properties of a queue.
Remarks This method simultaneously sets three related properties, which together describe
the behavior of a queue in overflow situations. Each call must explicitly specify all
three properties.
limitPolicy Each queue has a policy for discarding events when a new
event would cause the queue to exceed its maxEvents
limit. Choose from the values of Limit Policy on page 138.
When maxEvents is zero (unlimited), the policy must be
TibrvQueue.DISCARD_NONE.
maxEvents Programs can limit the number of events that a queue can
hold—either to curb queue growth, or implement a
specialized dispatch semantics.
Zero specifies an unlimited number of events; in this case,
the policy must be TibrvQueue.DISCARD_NONE.
discardAmount When the queue exceeds its maximum event limit, discard
a block of events. This property specifies the number of
events to discard.
When discardAmount is zero, the policy must be
TibrvQueue.DISCARD_NONE.
See Also TibrvQueue.getDiscardAmount() on page 145

TibrvQueue.getLimitPolicy() on page 146
TibrvQueue.getMaxEvents() on page 147

|
TibrvQueue.setPriority() 155
TibrvQueue.setPriority()
Method
Declaration void setPriority(int priority)

Purpose Set the priority of a queue.
Remarks Each queue has a single priority value, which controls its dispatch precedence
within queue groups. Higher values dispatch before lower values; queues with
equal priority values dispatch in round-robin fashion.
Changing the priority of a queue affects its position in all the queue groups that
contain it.
priority Replace the priority of the queue with this new value.
The priority must be a non-negative integer. Priority zero
signifies the last queue to dispatch.
See Also TibrvQueue.getPriority() on page 149

156
TibrvQueue.timedDispatch()
Method

Remarks If an event is already in the queue, this call dispatches it, and returns immediately.
If the queue is empty, this call waits for an event to arrive. If an event arrives
before the waiting time elapses, then it dispatches the event and returns. If the
waiting time elapses first, then the call returns without dispatching an event.
waiting for an event to arrive in the queue.

TibrvDispatchable.timedDispatch() on page 137

|
TibrvQueueGroup 157
TibrvQueueGroup
Class
Declaration class com.tibco.tibrv.TibrvQueueGroup

implements TibrvDispatchable
Purpose Prioritized dispatch of several queues with one call.
Remarks Queue groups add flexibility and fine-grained control to the event queue dispatch
mechanism. Programs can create groups of queues and dispatch them according
to their queue priorities.
(Sheet 1 of 2)

Life Cycle
TibrvQueueGroup() Create an event queue group. 159
TibrvQueueGroup.destroy() Destroy an event queue group. 162
TibrvQueueGroup.isValid() Test validity of a queue group. 166
Dispatch
TibrvQueueGroup.dispatch() Dispatch an event from a queue group; if no event 163

is ready, block.
TibrvQueueGroup.poll() Dispatch an event, but if no event is ready to 167

dispatch, return immediately (without blocking).
TibrvQueueGroup.timedDispatch() Dispatch an event, but if no event is ready to 169

dispatch, limit the time that this call blocks while
waiting for an event.
Queues
TibrvQueueGroup.add() Add an event queue to a queue group. 160
TibrvQueueGroup.contains() Test whether a queue is in a queue group. 161

158
(Sheet 2 of 2)

TibrvQueueGroup.elements() Extract an enumeration of the queues in a queue 164
group.
TibrvQueueGroup.getCount() Extract the number of queues in a queue group. 165
TibrvQueueGroup.remove() Remove an event queue from a queue group. 168
Inherited Methods

|
TibrvQueueGroup() 159
TibrvQueueGroup()
Constructor
Declaration TibrvQueueGroup()
Purpose Create an event queue group.
Remarks The new queue group is empty.

The queue group remains valid until the program explicitly destroys it.
See Also TibrvQueueGroup.add() on page 160

TibrvQueueGroup.destroy() on page 162

160
TibrvQueueGroup.add()
Method
Declaration void add(TibrvQueue eventQueue)

Purpose Add an event queue to a queue group.
Remarks If the queue is already in the group, adding it again has no effect.
If either the queue or the group is invalid, this method throws a TibrvException.
eventQueue Add this event queue to a queue group.
See Also TibrvQueue on page 138

|
TibrvQueueGroup.contains() 161
TibrvQueueGroup.contains()
Method
Declaration boolean contains(TibrvQueue eventQueue)

Purpose Test whether a queue is in a queue group.
Remarks If the queue is in the group, return true; otherwise false.

If the group is invalid, return false.
eventQueue Test the membership of this event queue in the queue group.

162
TibrvQueueGroup.destroy()
Method
Purpose Destroy an event queue group.
Remarks The individual queues in the group continue to exist, even though the group has
been destroyed.
See Also TibrvQueueGroup() on page 159

|
TibrvQueueGroup.dispatch() 163
TibrvQueueGroup.dispatch()
Method

Purpose Dispatch an event from a queue group; if no event is ready, block.
Remarks If any queue in the group contains an event, then this call searches the queues in
priority order, dispatches an event from the first non-empty queue that it finds,
and then returns. If all the queues are empty, then this call blocks indefinitely
while waiting for any queue in the group to receive an event.
When searching the group for a non-empty queue, this call searches according to
the priority values of the queues. If two or more queues have identical priorities,
subsequent dispatch and poll calls rotate through them in round-robin fashion.

TibrvDispatchable.dispatch() on page 135
Interrupting a Dispatch Call, page 143

164
TibrvQueueGroup.elements()
Method
Declaration java.util.Enumeration elements()
Purpose Extract an enumeration of the queues in a queue group.
Remarks If the group is invalid, return null.

|
TibrvQueueGroup.getCount() 165
TibrvQueueGroup.getCount()
Method
Declaration int getCount()
Purpose Extract the number of queues in a queue group.
Remarks If the group is invalid, return zero.

166
TibrvQueueGroup.isValid()
Method
Purpose Test validity of a queue group.
Remarks Returns true if the queue group is valid; false if the queue group has been
destroyed.

TibrvQueueGroup.destroy() on page 162

|
TibrvQueueGroup.poll() 167
TibrvQueueGroup.poll()
Method

Purpose Dispatch an event, but if no event is ready to dispatch, return immediately

(without blocking).
and then returns. If all the queues are empty, then this call returns immediately.
subsequent dispatch and poll calls rotate through them in round-robin fashion.

TibrvDispatchable.poll() on page 136

168
TibrvQueueGroup.remove()
Method
Declaration void remove(TibrvQueue eventQueue)

Purpose Remove an event queue from a queue group.
Remarks If the queue is not in the group, or if the group is invalid, this call throws an
exception with the status code TibrvStatus.INVALID_QUEUE.
eventQueue Remove this event queue from a queue group.

TibrvQueueGroup.timedDispatch() 169
|
TibrvQueueGroup.timedDispatch()
Method

and then returns. If the queue is empty, this call waits for an event to arrive in any
queue. If an event arrives before the waiting time elapses, then the call searches
the queues, dispatches the event, and returns. If the waiting time elapses first,
then the call returns without dispatching an event.
subsequent dispatch calls rotate through them in round-robin fashion.
waiting for an event to arrive in the queue group.

TibrvDispatchable.timedDispatch() on page 137

170
TibrvDispatcher
Class
Declaration class com.tibco.tibrv.TibrvDispatcher

extends java.lang.Thread
Purpose Dispatch events from a queue or queue group.
Remarks Upon creation, this thread class loops indefinitely, repeatedly dispatching a queue
or queue group.
This class is a programming convenience. Programs can implement specialized
dispatcher threads, and use them instead of this class.
Exceptions If the thread catches a TibrvException, it presents the

DISPATCHER.THREAD_EXITED advisory on the process transport, and exits. (The
program destroyed the queue or queue group object, so this thread can no longer
dispatch it.)
If the thread catches an interruption (java.lang.InterruptedException), it
presents the DISPATCHER.THREAD_EXITED advisory on the process transport, and
exits.
Interrupting a To interrupt a dispatcher thread in the Java implementation (see Tibrv.open()

Dispatcher on page 32), use either the Java method Thread.interrupt() or
Thread TibrvDispatcher.destroy().
In either the JNI (native) implementation or the Java implementation, you can
interrupt a dispatcher thread by calling its TibrvDispatcher.destroy()
method. Destroying the thread insures prompt thread exit—at the latest, after the
return of a program callback method (if one is in progress).

TibrvDispatcher() Create a dispatcher thread. 172
TibrvDispatcher.DEFAULT_NAME When the constructor does not receive a thread name, it
gives the new dispatcher thread this default name.

|
TibrvDispatcher 171
Inherited Methods
java.lang.Thread.activeCount
java.lang.Thread.checkAccess
java.lang.Thread.countStackFrames
java.lang.Thread.currentThread
java.lang.Thread.destroy (override)
java.lang.Thread.dumpStack
java.lang.Thread.enumerate
java.lang.Thread.getContextClassLoader
java.lang.Thread.getName
java.lang.Thread.getPriority
java.lang.Thread.getThreadGroup
java.lang.Thread.interrupt
java.lang.Thread.interrupted
java.lang.Thread.isAlive
java.lang.Thread.isDaemon
java.lang.Thread.isInterrupted
java.lang.Thread.join
java.lang.Thread.resume
java.lang.Thread.run (override)
java.lang.Thread.setContextClassLoader
java.lang.Thread.setDaemon
java.lang.Thread.setName
java.lang.Thread.setPriority
java.lang.Thread.sleep
java.lang.Thread.start
java.lang.Thread.stop
java.lang.Thread.suspend
java.lang.Thread.toString
java.lang.Thread.yield
See Also Tibrv.isNativeImpl() on page 30

Tibrv.open()on page 32

172
TibrvDispatcher()
Constructor
Declaration TibrvDispatcher(
java.lang.ThreadGroup group,
TibrvDispatchable dispatchable)
TibrvDispatcher(
TibrvDispatcher(
TibrvDispatcher(
java.lang.ThreadGroup group,
TibrvDispatchable dispatchable,
double timeout)
TibrvDispatcher(
double timeout)
TibrvDispatcher(
double timeout)
Purpose Create a dispatcher thread.
Remarks This constructor immediately starts the thread.
(Sheet 1 of 2)
group Create a dispatcher thread in this Java thread group.
When absent, use the main thread group.
name Create a dispatcher thread with this name.

When absent, use the default thread name.
dispatchable Create a thread that dispatches this TibrvQueue or

TibrvQueueGroup.

|
TibrvDispatcher() 173
(Sheet 2 of 2)
timeout When this time period (in seconds) elapses without
dispatching an event, the thread exits.
When absent, the default is to run indefinitely (with no
timeout).
See Also TibrvDispatcher on page 170

DISPATCHER.THREAD_EXITED on page 254 in TIBCO Rendezvous Concepts

174

| 175
Chapter 6 Transports
Transports manage network connections and send outbound messages.

This chapter presents the various transport classes and their methods.
Topics
• TibrvTransport, page 176

• TibrvProcessTransport, page 186
• TibrvNetTransport, page 187
• TibrvRvaTransport, page 188
• TibrvRvdTransport, page 198
See Also
TibrvCmTransport on page 257
TibrvCmQueueTransport on page 302

176
| Chapter 6 Transports
TibrvTransport
Class
Declaration abstract class com.tibco.tibrv.TibrvTransport

Purpose A transport object represents a delivery mechanism for messages.
Remarks A transport describes a carrier for messages—whether across a network, among

processes on a single computer, or within a process. Transports manage network
connections, and send outbound messages.
A transport also defines the delivery scope of a message—that is, the set of possible
destinations for the messages it sends.
Destroying a transport object invalidates subsequent send calls on that transport,
and invalidates any listeners using that transport.
Programs must explicitly destroy instances of these classes. Rendezvous software
This abstract class is the superclass of all other transport classes. Methods defined
by this class are implemented by all transport subclasses (except
TibrvCmQueueTransport, for which some methods do not apply).
Intra-Process Each process has exactly one intra-process transport; the call Tibrv.open()
Transport automatically creates it, and the call Tibrv.processTransport() extracts it.
Programs must not destroy the intra-process transport.
(Sheet 1 of 2)

TibrvTransport.createInbox() Create a unique inbox subject name. 178
TibrvTransport.destroy() Destroy a transport. 179
TibrvTransport.isValid() Test validity of a transport. 180
TibrvTransport.getDescription() Extract the program description parameter from a 181

transport.
TibrvTransport.send() Send a message. 182
TibrvTransport.sendReply() Send a reply message. 183
TibrvTransport.sendRequest() Send a request message and wait for a reply. 184

|
TibrvTransport 177
(Sheet 2 of 2)

TibrvTransport.setDescription() Set the program description parameter of a 185
transport.
Inherited Methods
Descendants TibrvProcessTransport on page 186

TibrvNetTransport on page 187
TibrvRvaTransport on page 188
TibrvRvdTransport on page 198
See Also Transport on page 99 in TIBCO Rendezvous Concepts

178
TibrvTransport.createInbox()
Method
Declaration java.lang.String createInbox()

Purpose Create a unique inbox subject name.
Remarks This method creates inbox names that are unique throughout the transport scope.
• For network transports, inbox subject names are unique across all processes
within the local router domain—that is, anywhere that direct multicast contact
is possible. The inbox name is not necessarily unique outside of the local
router domain.
• For the intra-process transport, inbox names are unique across all threads of
the process.
This method creates only the unique name for an inbox; it does not begin listening
for messages on that subject name. To begin listening, pass the inbox name as the
subject argument to TibrvListener(). The inbox name is only valid for use
with the same transport that created it. When calling TibrvListener(), you must
pass the same transport object that created the inbox subject name.
Remember that other programs have no information about an inbox subject name
until the listening program uses it as a reply subject in an outbound message.
Use inbox subject names for delivery to a specific destination. In the context of a
network transport, an inbox destination specifies unicast (point-to-point)
delivery.
Rendezvous routing daemons (rvrd) translate inbox subject names that appear as
the send subject or reply subject of a message. They do not translate inbox subject
names within the data fields of a message.
This inherited method is disabled for TibrvCmQueueTransport objects.
This method is the only legal way for programs to create inbox subject names.
See Also TibrvMsg.setReplySubject() on page 77

|
TibrvTransport.destroy() 179
TibrvTransport.destroy()
Method
Purpose Destroy a transport.
Remarks Programs must explicitly destroy each transport object.

Destroying a transport achieves these effects:
• The transport flushes all outbound data to the Rendezvous daemon.
This effect is especially important, and neither exiting the program nor calling
Tibrv.close() is sufficient to flush outbound data.
• The transport explicitly destroys all events associated with the transport; that
is, this method calls TibrvEvent.destroy() for each associated event.
• Subsequent calls that use the destroyed transport return false (as an error
indicator).
It is illegal to destroy the intra-process transport (see

Tibrv.processTransport() on page 34).
See Also TibrvTransport.isValid() on page 180

180
TibrvTransport.isValid()
Method
Purpose Test validity of a transport.
Remarks Returns true if the transport is valid; false if the transport has been destroyed.

TibrvTransport.destroy()on page 179
TibrvCmTransport.destroy()on page 269
TibrvCmQueueTransport.destroy() on page 309

|
TibrvTransport.getDescription() 181
TibrvTransport.getDescription()
Method
Declaration String getDescription()
Purpose Extract the program description parameter from a transport.
Remarks The description identifies your program to Rendezvous components. Browser

administration interfaces display the description string.
See Also TibrvTransport on page 176

TibrvTransport.setDescription() on page 185

182
TibrvTransport.send()
Method
Declaration void send(TibrvMsg message)

Purpose Send a message.
Remarks The message must have a valid destination subject; see

TibrvMsg.setSendSubject() on page 78.
message Send this message.
See Also TibrvMsg.setSendSubject() on page 78

|
TibrvTransport.sendReply() 183
TibrvTransport.sendReply()
Method
Declaration void sendReply(

TibrvMsg replyMsg,
TibrvMsg requestMsg)
Purpose Send a reply message.
Remarks This convenience call extracts the reply subject of an inbound request message,
and sends an outbound reply message to that subject. In addition to the
convenience, this call is marginally faster than using separate calls to extract the
subject and send the reply.
This method overwrites any existing send subject of the reply message with the
reply subject of the request message.
replyMessage Send this outbound reply message.
requestMessage Send a reply to this inbound request message; extract its

reply subject to use as the subject of the outbound reply
message.
Give special attention to the order of the arguments to this method. Reversing the
inbound and outbound messages can cause an infinite loop, in which the program
repeatedly resends the inbound message to itself (and all other recipients).
See Also TibrvMsg.getReplySubject() on page 69

184
TibrvTransport.sendRequest()
Method
Declaration TibrvMsg sendRequest(

TibrvMsg message,
double timeout)
Purpose Send a request message and wait for a reply.
Blocking can Stall Event Dispatch
This call blocks all other activity on its program thread. If appropriate,
programmers must ensure that other threads continue dispatching events on its
queues.
message Send this message.
waiting for a reply.
-1 indicates no timeout (wait without limit for a reply).
Remarks When the method receives a reply, it returns the reply. When the call does not
receive a reply, it returns null, indicating timeout.
Programs that receive and process the request message cannot determine that the
sender has blocked until a reply arrives.
The request message must have a valid destination subject; see
Operation This method operates in several synchronous steps:

1. Create an inbox name, and an event that listens to it. Overwrite any existing
reply subject of message with the inbox name.
2. Send the outbound message.
3. Block until the listener receives a reply; if the time limit expires before a reply
arrives, then return null. (The reply circumvents the event queue mechanism,
so it is not necessary to explicitly call dispatch methods in the program.)
4. Return the reply as the value of this method.

|
TibrvTransport.setDescription() 185
TibrvTransport.setDescription()
Method
Declaration void setDescription(

String description)
Purpose Set the program description parameter of a transport.
Remarks The description identifies your program to Rendezvous components. Browser

administration interfaces display the description string of ordinary transport
objects (however they do not display the description string of TibrvCmTransport
or TibrvCmQueueTransport objects.
As a debugging aid, we recommend setting a unique description string for each
transport. Use a string that distinguishes both the application and the role of the
transport within it.
description Use this string as the new program description.

TibrvTransport.getDescription() on page 181

186
TibrvProcessTransport
Class
Declaration final class com.tibco.tibrv.TibrvProcessTransport

extends TibrvTransport
Purpose The intra-process transport delivers messages among the threads of a program.
Remarks The intra-process transport does not access the network.

The call Tibrv.open() automatically creates the intra-process transport;
Tibrv.close() automatically destroys it; Tibrv.processTransport() extracts
it from the Rendezvous environment. Programs cannot create additional
instances of this class, and cannot destroy the intra-process transport.
Inherited Methods
Related Classes TibrvTransport on page 176

See Also Tibrv.processTransport() on page 34

|
TibrvNetTransport 187
TibrvNetTransport
Class
Declaration abstract class com.tibco.tibrv.TibrvNetTransport

Purpose Deliver messages across a network.
Remarks This abstract class is the superclass of all network transport classes.
Inherited Methods
Related Classes TibrvTransporton page 176

TibrvProcessTransport on page 186
TibrvRvaTransport on page 188

188
TibrvRvaTransport
Class
Declaration class com.tibco.tibrv.TibrvRvaTransport

extends TibrvNetTransport
Purpose Deliver network messages through a Rendezvous agent (rva).
Remarks For most Java applets running in a secure browser environment,

TibrvRvaTransport is the only way to connect to a network.
TibrvRvaTransport in turn connects to an rva process running on the web
server where the applet originates.
TibrvRvaTransport can operate through a firewall using the HTTP protocol.
TibrvRvaTransport can operate in either an Tibrv.IMPL_NATIVE environment,
or an Tibrv.IMPL_JAVA environment (that is, it does not require the JNI library).
A TibrvRvaTransport can connect to the Rendezvous agent through either of
two ports:
• The rva TCP port. Use this technique for programs running on intranets.
• The HTTP port, using HTTP tunneling. Use this technique for remote access,
when it is not possible to open the rva port through a firewall. For more
information, see HTTP Tunneling on page 14.
Programs must explicitly destroy instances of this class using

TibrvTransport.destroy(). Rendezvous software keeps internal references to
these objects, so the Java garbage collector does not delete them automatically.
(Sheet 1 of 2)

TibrvRvaTransport() Create a transport that connects 190
through the Rendezvous agent.
TibrvRvaTransport.getHostName() Return the host name of the 193

computer where this transport
connects to the Rendezvous agent.
TibrvRvaTransport.getHttpReconnectDelay() Return the delay time (in seconds) 194

before the transport reopens a
connection to the Rendezvous
agent.

|
TibrvRvaTransport 189
(Sheet 2 of 2)

TibrvRvaTransport.getPort() Return the port number through 195
which this transport connects to the
Rendezvous agent.
TibrvRvaTransport.isHttpTunneling() Determine whether this transport 196

connects to the Rendezvous agent
using HTTP protocol.
TibrvRvaTransport.setHttpReconnectDelay() Set the delay time (in seconds) 197

before the transport reopens a
connection to the Rendezvous
agent.
Inherited Methods

See Also Rendezvous Agent (rva), page 253 in TIBCO Rendezvous Administration

190
TibrvRvaTransport()
Constructor
Declaration TibrvRvaTransport()
TibrvRvaTransport(
java.lang.String hostName)
TibrvRvaTransport()
java.lang.String hostName,
int port)
TibrvRvaTransport(
int port,
int tunnelMode)
TibrvRvaTransport( // This method is deprecated //

int port,
boolean enableHttp)
Purpose Create a transport that connects through the Rendezvous agent.
hostName Connect to rva on this computer.
To connect to rva on the local computer, supply null.
port Connect to rva through this port.

To use the default rva port, supply zero. (TibrvRvaTransport
defines the constant DEFAULT_RVA_PORT as 7600.)
tunnelMode The method interprets this parameter as a bit vector. For a list of
bit constants, see Constant on page 191.
enableHttp The method that uses this parameter is deprecated, starting in

release 6.2. Instead, use the parameter tunnelMode.
When true, first try to connect to rva through the specified
port; if that attempt fails, then try tunneling through the HTTP
port.
When false (the default if absent), do not try HTTP tunneling.

|
TibrvRvaTransport() 191
TibrvRvaTransport.HTTP_TUNNEL_ENABLE When the flag HTTP_TUNNEL_ENABLE is set, first
try to connect directly to rva through the
specified port; if that attempt fails, then try
tunneling through the HTTP port.
TibrvRvaTransport.HTTP_TUNNEL_ENFORCE When the flag HTTP_TUNNEL_ENFORCE is set,

only try tunneling through the HTTP port; do
not attempt to connect directly to rva.
TibrvRvaTransport.HTTP_TUNNEL_DISABLE When the flag HTTP_TUNNEL_DISABLE is set (the

default if the parameter is entirely absent), do
not try HTTP tunneling.
TibrvRvaTransport.USE_NETSCAPE_SECURITY The flag USE_NETSCAPE_SECURITY affects the

behavior of the TibrvRvaTransport when it
attempts to connect to rva using HTTP
tunneling. When this flag is set, the
TibrvRvaTransport requests the
UniversalConnect privilege from the object
netscape.security.PrivilegeManager.
An applet that obtains this privilege, and uses a

signed Rendezvous jar file, can connect to rva
on any computer.
Programs can set this bit in conjunction with
either
TibrvRvaTransport.HTTP_TUNNEL_ENABLE or
TibrvRvaTransport.HTTP_TUNNEL_ENFORCE
(using addition or the bitwise or operator).
Method Forms With no arguments, connect to rva on the local computer (where the program is
running).
All arguments specify options for connecting to rva.
Description As a debugging aid, we recommend setting a unique description string for each
String transport. Use a string that distinguishes both the application and the role of the
transport within it. See TibrvTransport.setDescription() on page 185.
See Also Signed Applets, page 15

Archive Files, page 20

192
Netscape Java Security Introduction, and Java Capabilities API,

http://developer.netscape.com/docs/manuals/signedobj/capsapi.html (URLs
can change without notice)

|
TibrvRvaTransport.getHostName() 193
TibrvRvaTransport.getHostName()
Method
Declaration java.lang.String getHostName()
Purpose Return the host name of the computer where this transport connects to the
Rendezvous agent.

194
TibrvRvaTransport.getHttpReconnectDelay()
Method
Declaration double getHttpReconnectDelay()
Purpose Return the delay time (in seconds) before the transport reopens a connection to
the Rendezvous agent.
Remarks The default value is 0.2 seconds.

|
TibrvRvaTransport.getPort() 195
TibrvRvaTransport.getPort()
Method
Declaration int getPort()
Purpose Return the port number through which this transport connects to the Rendezvous
agent.
Remarks This method returns the actual port (for example, if the program specified the
default by supplying zero, this method returns the default TCP port number,
which is 7600).

196
TibrvRvaTransport.isHttpTunneling()
Method
Declaration boolean isHttpTunneling()
Purpose Determine whether this transport connects to the Rendezvous agent using HTTP
protocol.
Remarks This method indicates whether the transport actually connects using HTTP
protocol (for example, the program might specify HTTP, but reality might differ).

|
TibrvRvaTransport.setHttpReconnectDelay() 197
TibrvRvaTransport.setHttpReconnectDelay()
Method
Declaration void setHttpReconnectDelay(double seconds)
Purpose Set the delay time (in seconds) before the transport reopens a connection to the
Rendezvous agent.
seconds Set this delay time.
Remarks This value is relevant only when the transport uses HTTP tunneling.
Unless a program has changed the value using this method, the default value is
0.2 seconds.

198
TibrvRvdTransport
Class
Declaration class com.tibco.tibrv.TibrvRvdTransport

extends TibrvNetTransport
Purpose Deliver network messages through a Rendezvous daemon.
Remarks TibrvRvdTransport is the most direct way to connect to a network. For most
independent applications and servers, use TibrvRvdTransport (rather than
TibrvRvaTransport).
TibrvRvdTransport must operate in an Tibrv.IMPL_NATIVE environment (that

is, it requires the JNI library). To determine the implementation, see
Tibrv.isNativeImpl() on page 30.

TibrvRvdTransport.DEFAULT_RVD_PORT Unless you specify another port when creating the
transport, TibrvRvdTransport connects to the
Rendezvous daemon through this default TCP port
(7500).
TibrvRvdTransport.DEFAULT_BATCH Default batch behavior. The transport transmits

outbound messages to rvd as soon as possible.
This value is the initial default for all transports.
TibrvRvdTransport.TIMER_BATCH Timer batch behavior. The transport accumulates

outbound messages, and transmits them to rvd in
batches—either when its buffer is full, or when a timer
interval expires. (Programs cannot adjust the timer
interval.)

TibrvRvdTransport() Create a transport that connects to a 200
Rendezvous daemon.
TibrvRvdTransport.getDaemon() Return the socket where this transport connects 203

to the Rendezvous daemon.

|
TibrvRvdTransport 199

TibrvRvdTransport.getNetwork() Return the network interface that this transport 204
uses for communication.
TibrvRvdTransport.getService() Return the effective service that this transport 205

uses for communication.
TibrvRvdTransport.setBatchMode() Set the batch mode parameter of a transport. 206
Inherited Methods


200
TibrvRvdTransport()
Constructor
Declaration TibrvRvdTransport()
TibrvRvdTransport(
java.lang.String service,
java.lang.String network,
java.lang.String daemon)
TibrvRvdTransport(
java.lang.String service,
java.lang.String network,
java.lang.String daemon,
java.lang.String licenseTicket)
Purpose Create a transport that connects to a Rendezvous daemon.
Method Forms With no arguments, connect to rvd on the local computer using default values the
service, network, and daemon parameters.
All arguments specify options for connecting to rvd.
Connecting to Rendezvous daemon processes do the work of moving messages across a

the Rendezvous network. Every TibrvRvdTransport must connect to a Rendezvous daemon.
Daemon
If a Rendezvous daemon process with a corresponding daemon parameter is
already running, the transport connects to it.
If an appropriate Rendezvous local daemon is not running, the transport tries to
start it. However, the transport does not attempt to start a remote daemon when
none is running.
If the transport cannot connect to the Rendezvous daemon, the constructor
throws an exception with the status code TibrvStatus.DAEMON_NOT_FOUND.
The first time a program successfully connects to the Rendezvous daemon
process, rvd starts the clock ticking for temporary license tickets. (See Licensing
Information, page 11 in TIBCO Rendezvous Administration.)
Description As a debugging aid, we recommend setting a unique description string for each
String transport. Use a string that distinguishes both the application and the role of the
transport within it. See TibrvTransport.setDescription() on page 185.

|
TibrvRvdTransport() 201
service The Rendezvous daemon divides the network into logical partitions. Each
TibrvRvdTransport communicates on a single service; a transport can
communicate only with other transports on the same service.
To communicate on more than one service, a program must create more than
one transport—one transport for each service.
You can specify the service in several ways. For details, see Service Parameter
on page 103 in TIBCO Rendezvous Concepts.
null specifies the default rendezvous service.
network Every network transport communicates with other transports over a single
network interface. On computers with more than one network interface, the
network parameter instructs the Rendezvous daemon to use a particular
network for all outbound messages from this transport.
To communicate over more than one network, programs must create more than
one transport.
You can specify the network in several ways. For details, see Network
Parameter on page 107 in TIBCO Rendezvous Concepts.
null specifies the primary network interface for the host computer.
daemon The daemon parameter instructs the transport object about how and where to
find the Rendezvous daemon and establish communication.
For details, see Daemon Parameter on page 110 in TIBCO Rendezvous Concepts.
You can specify a daemon on a remote computer. For details, see Remote
Daemon on page 111 in TIBCO Rendezvous Concepts.
If you specify a secure daemon, this string must be identical to as the
daemonName argument of TibrvSdContext.setDaemonCert() on page 37. See
also, Secure Daemon on page 111 in TIBCO Rendezvous Concepts.
null specifies the default—find the local daemon on TCP socket 7500. (This
default is not valid when the local daemon is a secure daemon.)
licenseTicket Embed this special license ticket in the transport object. When a licensed
transport connects to rvd, it presents this special ticket to validate its
connection (rvd uses the longest-running ticket available, which can be either
this special ticket, or a ticket from the ticket file, tibrv.tkt).
Ordinary license tickets are not valid for this parameter; see also, Embedded
License on page 202.

202
Embedded Specially-licensed third-party developers can use the third form of this method.
License To use this alternate form, a developer must first purchase a special license ticket.
This call embeds the special ticket in the program, so that end-users do not need
to purchase Rendezvous to use the program.
To purchase an embedded license, contact TIBCO Software Inc.
See Also TibrvRvdTransport.getDaemon()on page 203

TibrvRvdTransport.getNetwork() on page 204
TibrvRvdTransport.getService() on page 205

|
TibrvRvdTransport.getDaemon() 203
TibrvRvdTransport.getDaemon()
Method
Declaration java.lang.String getDaemon()
Purpose Return the socket where this transport connects to the Rendezvous daemon.
See Also TibrvRvaTransport() on page 190

204
TibrvRvdTransport.getNetwork()
Method
Declaration java.lang.String getNetwork()
Purpose Return the network interface that this transport uses for communication.

|
TibrvRvdTransport.getService() 205
TibrvRvdTransport.getService()
Method
Declaration java.lang.String getService()
Purpose Return the effective service that this transport uses for communication.

206
TibrvRvdTransport.setBatchMode()
Method
Declaration void setBatchMode(

int mode)
static final int DEFAULT_BATCH = 0;

static final int TIMER_BATCH = 1;
Purpose Set the batch mode parameter of a transport.
Remarks The batch mode determines when the transport transmits outbound message data
to rvd:
• As soon as possible (the initial default for all transports)
• Either when its buffer is full, or when a timer interval expires—either event
triggers transmission to the daemon
mode Use this value as the new batch mode.
DEFAULT_BATCH Default batch behavior. The transport transmits outbound
messages to rvd as soon as possible.
This value is the initial default for all transports.
TIMER_BATCH Timer batch behavior. The transport accumulates

outbound messages, and transmits them to rvd in
batches—either when its buffer is full, or when a timer
interval expires. (Programs cannot adjust the timer
interval.)
See Also Batch Modes for Transports on page 118 in TIBCO Rendezvous Concepts

| 207
Chapter 7 Virtual Circuits
Virtual circuits feature Rendezvous communication between two terminals over

an exclusive, continuous, monitored connection.
See Also Virtual Circuits on page 119 in TIBCO Rendezvous Concepts
Topics
• TibrvVcTransport, page 208

208
| Chapter 7 Virtual Circuits
TibrvVcTransport
Class
Declaration class com.tibco.tibrv.TibrvVcTransport

Purpose A virtual circuit transport object represents a terminal in a potential circuit.
Remarks A virtual circuit transport can fill the same roles as an ordinary transport.
Programs can use them to create inbox names, send messages, create listeners and
other events.
Instead of a constructor, this class has two create methods. These two methods
also determine the protocol role of the transport object—one method creates a
terminal that accepts connections, and another method creates a terminal that
attempts to connect.
The two terminals play complementary roles as they attempt to establish a
connection. However, this difference soon evaporates. After the connection is
complete, the two terminals behave identically.

TibrvVcTransport.createAcceptVc() Create a virtual circuit accept object. 210
TibrvVcTransport.createConnectVc() Create a virtual circuit connect object 211
TibrvVcTransport.getConnectSubject() Return the connect subject of an accept 213

terminal.
TibrvVcTransport.waitForVcConnection() Test the connection status of a virtual 214

circuit.
Broken The following conditions can close a virtual circuit connection:

Connection
• Contact is broken between the object and its terminal.
• The virtual circuit loses data in either direction (see DATALOSS on page 252 in
TIBCO Rendezvous Concepts).
• The partner program destroys its terminal object (or that terminal becomes
invalid).
• The program destroys the object.

|
TibrvVcTransport 209
• The program destroys the object’s ordinary transport.
Direct Because virtual circuits rely on point-to-point messages between the two
Communication terminals, they can use direct communication to good advantage. To do so, both
terminals must use network transports that enable direct communication.
For an overview, see Direct Communication on page 116 in TIBCO Rendezvous
Concepts.
For programming details, see Specifying Direct Communication on page 105 in
TIBCO Rendezvous Concepts.
Inherited Methods
Disabled Methods inherited from TibrvTransport

TibrvTransport.getDescription()
TibrvTransport.setDescription()

See Also Virtual Circuits on page 119 in TIBCO Rendezvous Concepts

210
TibrvVcTransport.createAcceptVc()
Method
Declaration TibrvVcTransport CreateAcceptVc(

TibrvTransport transport)
Purpose Create a virtual circuit accept object.
Remarks After this call returns, the program must extract the object’s connect subject, and
send it in a message to another program, inviting it to establish a virtual circuit.
Furthermore, the reply subject of that invitation message must be this connect
subject. To complete the virtual circuit, the second program must extract this
subject from the invitation, and supply it to
TibrvVcTransport.createConnectVc().
transport The virtual circuit terminal uses this ordinary transport for communications.
Programs may use this transport for other purposes.
It is illegal to supply a virtual circuit transport object for this parameter (that is,
you cannot nest a virtual circuit within another virtual circuit).
Test Before Either of two conditions indicate that the connection is ready to use:
Using
• The transport presents the VC.CONNECTED advisory.
• TibrvVcTransport.waitForVcConnection() returns without error.
Immediately after this call, test both conditions with these two steps (in this
order):
1. Listen on the virtual circuit transport object for the VC.CONNECTED advisory.
2. Call TibrvVcTransport.waitForVcConnection() with zero as the timeout
parameter.
For an explanation, see Testing the New Connection on page 123 in TIBCO
Rendezvous Concepts.
See Also TibrvVcTransport.createConnectVc() on page 211

TibrvVcTransport.getConnectSubject() on page 213
TibrvVcTransport.waitForVcConnection() on page 214
VC.CONNECTED on page 267 in TIBCO Rendezvous Concepts
VC.DISCONNECTED on page 268 in TIBCO Rendezvous Concepts

|
TibrvVcTransport.createConnectVc() 211
TibrvVcTransport.createConnectVc()
Method
Declaration TibrvVcTransport CreateConnectVc(

java.lang.String connectSubject,
TibrvTransport transport)
Purpose Create a virtual circuit connect object
connectSubject The terminal uses this connect subject to establish a virtual circuit with an
accept transport in another program.
The program must receive this connect subject from the accepting program.
The call to TibrvVcTransport.createAcceptVc() creates and returns this
subject.
transport The virtual circuit terminal uses this ordinary transport for communications.
Programs may use this transport for other purposes.
It is illegal to supply a virtual circuit transport object for this parameter (that is,
you cannot nest a virtual circuit within another virtual circuit).
Test Before Either of two conditions indicate that the connection is ready to use:
Using
• The transport presents the VC.CONNECTED advisory.
• TibrvVcTransport.waitForVcConnection() returns without error.
Immediately after this call, test both conditions with these two steps (in this
order):
1. Listen on the virtual circuit transport object for the VC.CONNECTED advisory.
2. Call TibrvVcTransport.waitForVcConnection() with zero as the timeout
parameter.
For an explanation, see Testing the New Connection on page 123 in TIBCO
See Also TibrvVcTransport.createAcceptVc() on page 210

TibrvVcTransport.getConnectSubject() on page 213
TibrvVcTransport.waitForVcConnection() on page 214

212

|
TibrvVcTransport.getConnectSubject() 213
TibrvVcTransport.getConnectSubject()
Method
Declaration java.lang.String getConnectSubject()

Purpose Return the connect subject of an accept terminal.
Remarks After creating an accept terminal, the program must use this method to extract its
connect subject, and send it in a message to another program, inviting it to
establish a virtual circuit. Furthermore, the reply subject of that invitation message
must be this connect subject. To complete the virtual circuit, the second program
must extract this subject from the invitation, and supply it to
TibrvVcTransport.createConnectVc().

TibrvVcTransport.createConnectVc() on page 211

214
TibrvVcTransport.waitForVcConnection()
Method
Declaration void waitForVcConnection(

java.lang.double timeout)
Purpose Test the connection status of a virtual circuit.
Remarks This method tests (and can block) until this virtual circuit transport object has
established a connection with its opposite terminal. You may call this method for
either an accept terminal or a connect terminal.
This method produces the same information as the virtual circuit advisory
messages—but it produces it synchronously (while advisories are asynchronous).
Programs can use this method not only to test the connection, but also to block
until the connection is ready to use.
For example, a program can create a terminal object, then call this method to wait
until the connection completes.
timeout This parameter determines the behavior of the call:
• For a quick test of current connection status, supply zero. The call returns
immediately, without blocking.
• To wait for a new terminal to establish a connection, supply a reasonable
positive value. The call returns either when the connection is complete, or
when this time limit elapses.
• To wait indefinitely for a usable connection, supply -1. The call returns
when the connection is complete. If the connection was already complete
and is now broken, the call returns immediately.
Results When the connection is complete (ready to use), this method returns normally.
Otherwise it throws an exception; the status value in the exception yields
additional information about the unusable connection.
(Sheet 1 of 2)
Status Description
TibrvStatus.TIMEOUT The connection is not yet complete, but the
non-negative time limit for waiting has expired.

|
TibrvVcTransport.waitForVcConnection() 215
(Sheet 2 of 2)
Status Description
TibrvStatus.TIBRV_VC_NOT_CONNECTED The connection was formerly complete, but is now
irreparably broken.

TibrvVcTransport.createConnectVc() on page 211
Testing the New Connection on page 123 in TIBCO Rendezvous Concepts

216

| 217
Chapter 8 Fault Tolerance
Rendezvous fault tolerance software coordinates a group of redundant processes

into a fault-tolerant distributed program. Some processes actively fulfill the tasks
of the program, while other processes wait in readiness. When one of the active
processes fails, another process rapidly assumes active duty.
Topics
• Fault Tolerance Road Map, page 218

• TibrvFtMember, page 219
• TibrvFtMemberCallback, page 236
• TibrvFtMonitor, page 239
• TibrvFtMonitorCallback, page 246

218
| Chapter 8 Fault Tolerance
Fault Tolerance Road Map
For a complete discussion of concepts and operating principles, see Fault

Tolerance Concepts on page 195 in TIBCO Rendezvous Concepts.
For suggestions to help you design programs using fault tolerance features, see
Fault Tolerance Programming on page 213 in TIBCO Rendezvous Concepts.
For step-by-step hints for implementing fault-tolerant systems, see Developing
Fault-Tolerant Programs on page 227 in TIBCO Rendezvous Concepts.
Fault tolerance software uses advisory messages to inform programs of status
changes. For details, see Fault Tolerance (RVFT) Advisory Messages on page 293
in TIBCO Rendezvous Concepts.
If your application distributes fault-tolerant processes across network boundaries,
you must configure the Rendezvous routing daemons to exchange _RVFT
administrative messages. For details, see Fault Tolerance on page 375 in TIBCO
Rendezvous Administration, and discuss with your network administrator.

|
TibrvFtMember 219
TibrvFtMember
Class
Declaration class com.tibco.tibrv.TibrvFtMember

extends TibrvEvent
Purpose Represent membership in a fault tolerance group.
Remarks Upon creating this object, the program joins a fault tolerance group.
By destroying a member object, the program withdraws its membership in the
fault tolerance group.
them automatically.
Destroying the queue or transport of a member object automatically destroys the
member object as well.
Constants Each of these constant fields is a token designating a command to a fault tolerance
callback method. The program’s callback method receives one of these tokens in a
parameter, and interprets it as an instruction from the Rendezvous fault tolerance
software as described in this table (see also, Fault Tolerance Callback Actions on
page 214 in TIBCO Rendezvous Concepts).
(Sheet 1 of 2)
TibrvFtMember.PREPARE_TO_ACTIVATE Prepare to activate (hint).
Rendezvous fault tolerance software passes this token
to the callback method to instruct the program to
make itself ready to activate on short notice—so that if
the callback method subsequently receives the
instruction to activate, it can do so without delay.
This token is a hint, indicating that the program might
soon receive an instruction to activate. It does not
guarantee that an activate instruction will follow, nor
that any minimum time will elapse before an activate
instruction follows.

220
(Sheet 2 of 2)
TibrvFtMember.ACTIVATE Activate immediately.
activate.
TibrvFtMember.DEACTIVATE Deactivate immediately.

deactivate.

TibrvFtMember() Create a member of a fault tolerance 222
group.
TibrvFtMember.destroy() Destroy a member of a fault tolerance 225

group.
TibrvFtMember.getActivationInterval() Extract the activation interval of a fault 226

tolerance member.
TibrvFtMember.getActiveGoal() Extract the active goal of a fault 227

tolerance member.
TibrvFtMember.getGroupName() Extract the group name of a fault 228

tolerance member.
TibrvFtMember.getHeartbeatInterval() Extract the heartbeat interval of a fault 229

tolerance member.
TibrvFtMember.getPreparationInterval() Extract the preparation interval of a 230

fault tolerance member.
TibrvFtMember.getQueue() Extract the event queue of a fault 231

tolerance member.
TibrvFtMember.getTransport() Extract the transport of a fault tolerance 232

member.

|
TibrvFtMember 221

TibrvFtMember.getWeight() Extract the weight of a fault tolerance 233
member.
TibrvFtMember.setWeight() Change the weight of a fault tolerance 235

member within its group.
Inherited Methods
Related Classes TibrvEvent on page 112

TibrvFtMonitor on page 239
See Also TibrvFtMemberCallback on page 236

222
TibrvFtMember()
Constructor
Declaration TibrvFtMember(
TibrvQueue queue,
TibrvFtMemberCallback callback,
java.lang.String groupName,
int weight,
int activeGoal,
double heartbeatInterval,
double preparationInterval,
double activationInterval,
Purpose Create a member of a fault tolerance group.
Remarks Upon creating a member object, the program becomes a member of the group.
A program may hold simultaneous memberships in several distinct fault
tolerance groups. For examples, see Multiple Groups on page 217 in TIBCO
Avoid joining the same group twice. It is illegal for a program to maintain more
than one membership in any one fault tolerance group. The constructor does not
guard against this illegal situation, and results are unpredictable.
All arguments are required except for preparationInterval (which may be
zero) and closure (which may be null).
Intervals The heartbeat interval must be less than the activation interval. If the preparation
interval is non-zero, it must be greater than the heartbeat interval and less than
the activation interval. It is an error to violate these rules.
In addition, intervals must be reasonable for the hardware and network
conditions. For information and examples, see Step 4: Choose the Intervals on
page 235 in TIBCO Rendezvous Concepts.
Group Name The group name must be a legal Rendezvous subject name (see Subject Names on
page 61 in TIBCO Rendezvous Concepts). You may use names with several
elements; for examples, see Multiple Groups on page 217 in TIBCO Rendezvous
Concepts.

|
TibrvFtMember() 223
(Sheet 1 of 2)
queue Place fault tolerance events for this member on this event queue.
callback On dispatch, process the event with this callback object.
transport Use this transport for fault tolerance internal protocol messages (such as
heartbeat messages).
groupName Join the fault tolerant group with this name.

The group name must conform to the syntax required for Rendezvous
subject names. For details, see Subject Names on page 61 in TIBCO
weight Weight represents the ability of this member to fulfill its purpose, relative
to other members of the same fault tolerance group. Rendezvous fault
tolerance software uses relative weight values to select which members
to activate; members with higher weight take precedence over members
with lower weight.
Acceptable values range from 1 to 65535. Zero is a special, reserved
value; Rendezvous fault tolerance software assigns zero weight to
processes with resource errors, so they only activate when no other
members are available.
For more information, see Rank and Weight on page 204 in TIBCO
activeGoal Rendezvous fault tolerance software sends callback instructions to

maintain this number of active members.
Acceptable values range from 1 to 65535.
heartbeatInterval When this member is active, it sends heartbeat messages at this interval
(in seconds).
The interval must be positive. To determine the correct value, see Step 4:
Choose the Intervals on page 235 in TIBCO Rendezvous Concepts.

224
(Sheet 2 of 2)
preparationInterval When the heartbeat signal from one or more active members has been
silent for this interval (in seconds), Rendezvous fault tolerance software
issues an early warning hint (TibrvFtMember.PREPARE_TO_ACTIVATE)
to the ranking inactive member. This warning lets the inactive member
prepare to activate, for example, by connecting to a database server, or
allocating memory.
The interval must be non-negative. Zero is a special value, indicating
that the member does not need advance warning to activate;
Rendezvous fault tolerance software never issues a
TibrvFtMember.PREPARE_TO_ACTIVATE hint when this value is zero. To
determine the correct value, see Step 4: Choose the Intervals on page 235
activationInterval When the heartbeat signal from one or more active members has been
silent for this interval (in seconds), Rendezvous fault tolerance software
considers the silent member to be lost, and issues the instruction to
activate (TibrvFtMember.ACTIVATE) to the ranking inactive member.
When a new member joins a group, Rendezvous fault tolerance software
identifies the new member to existing members (if any), and then waits
for this interval to receive identification from them in return. If, at the
end of this interval, it determines that too few members are active, it
issues the activate instruction (TibrvFtMember.ACTIVATE) to the new
member.
Then interval must be positive. To determine the correct value, see Step
4: Choose the Intervals on page 235 in TIBCO Rendezvous Concepts.
closure Store this closure data in the member object.
See Also TibrvFtMember on page 219.

TibrvFtMemberCallback on page 236.
TibrvFtMember.destroy() on page 225.
Step 1: Choose a Group Name, page 228 in TIBCO Rendezvous Concepts
Step 2: Choose the Active Goal, page 230 in TIBCO Rendezvous Concepts
Step 4: Choose the Intervals, page 235 in TIBCO Rendezvous Concepts
Step 5: Program Start Sequence, page 239 in TIBCO Rendezvous Concepts

|
TibrvFtMember.destroy() 225
TibrvFtMember.destroy()
Method
Purpose Destroy a member of a fault tolerance group.
Remarks By destroying a member object, the program cancels or withdraws its

membership in the group.
This method has two effects:
• If this member is active, stop sending the heartbeat signal.
• Reclaim the program storage associated with this member.
Once a program withdraws from a group, it no longer receives fault tolerance

events. One direct consequence is that an active program that withdraws can
never receive an instruction to deactivate.
See Also TibrvFtMember() on page 222

TibrvFtMember.isValid() on page 234

226
TibrvFtMember.getActivationInterval()
Method
Declaration double getActivationInterval()
Purpose Extract the activation interval of a fault tolerance member.

|
TibrvFtMember.getActiveGoal() 227
TibrvFtMember.getActiveGoal()
Method
Declaration int getActiveGoal()
Purpose Extract the active goal of a fault tolerance member.

228
TibrvFtMember.getGroupName()
Method
Declaration java.lang.String getGroupName()
Purpose Extract the group name of a fault tolerance member.

|
TibrvFtMember.getHeartbeatInterval() 229
TibrvFtMember.getHeartbeatInterval()
Method
Declaration double getHeartbeatInterval()
Purpose Extract the heartbeat interval of a fault tolerance member.
Remarks If the member is invalid, this method returns null.

230
TibrvFtMember.getPreparationInterval()
Method
Declaration double getPreparationInterval()
Purpose Extract the preparation interval of a fault tolerance member.

|
TibrvFtMember.getQueue() 231
TibrvFtMember.getQueue()
Method
Declaration TibrvQueue getQueue()
Purpose Extract the event queue of a fault tolerance member.

TibrvFtMember() on page 222

232
TibrvFtMember.getTransport()
Method
Purpose Extract the transport of a fault tolerance member.

TibrvFtMember() on page 222

|
TibrvFtMember.getWeight() 233
TibrvFtMember.getWeight()
Method
Declaration int getWeight()
Purpose Extract the weight of a fault tolerance member.

234
TibrvFtMember.isValid()
Method
Purpose Test validity of a fault tolerance member object.
Remarks Returns true if the member is valid; false if the member has been destroyed or is
otherwise invalid.
See Also TibrvFtMember.destroy() on page 225

|
TibrvFtMember.setWeight() 235
TibrvFtMember.setWeight()
Method
Declaration void setWeight(int weight)

Purpose Change the weight of a fault tolerance member within its group.
Remarks Weight summarizes the relative suitability of a member for its task, relative to
other members of the same fault tolerance group. That suitability is a combination
of computer speed and load factors, network bandwidth, computer and network
reliability, and other factors. Programs may reset their weight when any of these
factors change, overriding the previous assigned weight.
You can use relative weights to indicate priority among group members.
Zero is a special value; Rendezvous fault tolerance software assigns zero weight
to processes with resource errors, so they only activate when no other members
are available. Programs must always assign weights greater than zero.
When Rendezvous fault tolerance software requests a resource but receives an
error (for example, the member process cannot allocate memory, or start a timer),
it attempts to send the member process a DISABLING_MEMBER advisory message,
and sets the member’s weight to zero, effectively disabling the member. Weight
zero implies that this member is active only as a last resort—when no other
members outrank it. (However, if the disabled member process does become
active, it might not operate correctly.)
weight The new weight value. See weight on page 223.
See Also Adjusting Member Weights on page 225 in TIBCO Rendezvous Concepts.

236
TibrvFtMemberCallback
Interface
Declaration interface com.tibco.tibrv.TibrvFtMemberCallback
Purpose Process fault tolerance events for a group member.
Remarks Implement this interface to process fault tolerance events.

TibrvFtMemberCallback.onFtAction() Process fault tolerance events for a group 237
member.

|
TibrvFtMemberCallback.onFtAction() 237
TibrvFtMemberCallback.onFtAction()
Method
Declaration void onFtAction(

TibrvFtMember member,
int action)
Purpose Process fault tolerance events for a group member.
Remarks Each member program of a fault tolerance group must implement this method.
Programs register a member callback object (and this method) with each call to
TibrvFtMember().
Rendezvous fault tolerance software queues a member action event in three

situations. In each case, it passes a different action argument, instructing the
callback method to activate, deactivate, or prepare to activate the program.
• When the number of active members drops below the active goal, the fault
tolerance callback method (in the ranking inactive member process) receives
the token TibrvFtMember.ACTIVATE; the callback method must respond by
assuming the duties of an active member.
• When the number of active members exceeds the active goal, the fault
tolerance callback method (in any active member that is outranked by another
active member) receives the action token TibrvFtMember.DEACTIVATE; the
callback method must respond by switching the program to its inactive state.
• When the number of active members equals the active goal, and Rendezvous
fault tolerance software detects that it might soon decrease below the active
goal, the fault tolerance callback method (in the ranking inactive member)
receives the action token TibrvFtMember.PREPARE_TO_ACTIVATE; the
callback method must respond by making the program ready to activate
immediately. For example, preparatory steps might include time-consuming
tasks such as connecting to a database. If the callback method subsequently
receives the TibrvFtMember.ACTIVATE token, it will be ready to activate
without delay.
For additional information see Fault Tolerance Callback Actions on page 214 in
TIBCO Rendezvous Concepts.
(Sheet 1 of 2)
member This parameter receives the member object.

238
(Sheet 2 of 2)
groupName This parameter receives a string denoting the name of the fault
tolerance group.
action This parameter receives a token that instructs the callback

method to activate, deactivate or prepare to activate. See
Constants on page 219.
See Also TibrvFtMember() on page 222.

|
TibrvFtMonitor 239
TibrvFtMonitor
Class
Declaration class com.tibco.tibrv.TibrvFtMonitor

extends TibrvEvent
Purpose Monitor a fault tolerance group.
Remarks Upon creating this object, the program monitors a fault tolerance group.
Monitors are passive—they do not affect the group members in any way.
Rendezvous fault tolerance software queues a monitor event whenever the
number of active members in the group changes—either it detects a new
heartbeat, or it detects that the heartbeat from a previously active member is now
silent, or it receives a message from the fault tolerance component of an active
member indicating deactivation or termination.
The monitor callback method receives the number of active members as an
argument.
By destroying a monitor object, the program stops monitoring the fault tolerance
group.
them automatically.
Destroying the queue or transport of a monitor automatically destroys the
monitor as well.

TibrvFtMonitor() Monitor a fault tolerance group. 241
TibrvFtMonitor.destroy() Stop monitoring a fault tolerance group, and free 243

associated resources.
TibrvFtMonitor.getGroupName() Extract the group name of a fault tolerance monitor. 244
TibrvFtMonitor.getTransport() Extract the transport of a fault tolerance monitor. 245

240
Inherited Methods

TibrvFtMember on page 219
See Also TibrvFtMonitorCallback on page 246

|
TibrvFtMonitor() 241
TibrvFtMonitor()
Constructor
Declaration TibrvFtMonitor(
TibrvQueue queue,
TibrvFtMonitorCallback callback,
double lostInterval,
Purpose Monitor a fault tolerance group.
Remarks The monitor callback method receives the number of active members as an
argument.
The group need not have any members at the time of this constructor call.
queue Place events for this monitor on this event queue.
callback On dispatch, process the event with this callback method.
transport Listen on this transport for fault tolerance internal protocol

messages (such as heartbeat messages).
groupName Monitor the fault tolerant group with this name.

The group name must conform to the syntax required for
Rendezvous subject names. For details, see Subject Names
on page 61 in TIBCO Rendezvous Concepts.
See also, Group Name on page 242.
lostInterval When the heartbeat signal from an active member has been
silent for this interval (in seconds), Rendezvous fault
tolerance software considers that member lost, and queues a
monitor event.
The interval must be positive. To determine the correct
value, see Step 4: Choose the Intervals on page 235 in TIBCO
See also, Lost Interval on page 242.
closure Store this closure data in the monitor object.

242
Lost Interval The monitor uses the lostInterval to determine whether a member is still
active. When the heartbeat signal from an active member has been silent for this
interval (in seconds), the monitor considers that member lost, and queues a
monitor event.
We recommend setting the lostInterval identical to the group’s
activationInterval, so the monitor accurately reflects the behavior of the
group members.
Group Name The group name must be a legal Rendezvous subject name (see Subject Names on
page 61 in TIBCO Rendezvous Concepts). You may use names with several
elements; for examples, see Multiple Groups on page 217 in TIBCO Rendezvous
Concepts.
See Also TibrvFtMonitorCallback on page 246.

TibrvFtMonitor.destroy() on page 243.

|
TibrvFtMonitor.destroy() 243
TibrvFtMonitor.destroy()
Method
Purpose Stop monitoring a fault tolerance group, and free associated resources.
Remarks This method throws an exception when the monitor object is already invalid, or
when its queue or transport are invalid.
See Also TibrvFtMonitor() on page 241

244
TibrvFtMonitor.getGroupName()
Method
Declaration java.lang.String getGroupName()
Purpose Extract the group name of a fault tolerance monitor.
Remarks If the monitor is invalid, this method returns null.

|
TibrvFtMonitor.getTransport() 245
TibrvFtMonitor.getTransport()
Method
Purpose Extract the transport of a fault tolerance monitor.
Remarks If the monitor is invalid, this method returns null.

TibrvFtMonitor() on page 241

246
TibrvFtMonitorCallback
Interface
Declaration interface com.tibco.tibrv.TibrvFtMonitorCallback
Purpose Process fault tolerance events for a monitor.
Remarks Implement this interface to process fault tolerance monitor events.

TibrvFtMonitorCallback.onFtMonitor() Process fault tolerance events for a 247
monitor.

|
TibrvFtMonitorCallback.onFtMonitor() 247
TibrvFtMonitorCallback.onFtMonitor()
Declaration void onFtMonitor(

TibrvFtMonitor Monitor,
int numActiveMembers)
Purpose Process fault tolerance events for a monitor.
Remarks A program must define a method of this type as a prerequisite to monitor a fault
tolerance group. Programs register a monitor callback method with each call to
TibrvFtMonitor() on page 241.
Rendezvous fault tolerance software queues a monitor event whenever the

number of active members in the group changes.
A program need not be a member of a group in order to monitor that group.
Programs that do not monitor need not define a monitor callback method.
monitor This parameter receives the monitor object.
groupName This parameter receives a string denoting the name of

the fault tolerance group.
numActiveMembers This parameter receives the number of group members

now active.
See Also TibrvFtMonitor() on page 241.

248

| 249
Chapter 9 Certified Message Delivery
Although Rendezvous communications are highly reliable, some applications

require even stronger assurances of delivery. Certified delivery features offers
greater certainty of delivery—even in situations where processes and their
network connections are unstable.
See Also
This API implements Rendezvous certified delivery features. For a complete
discussion, see Certified Message Delivery on page 139 in TIBCO Rendezvous
Concepts.
Certified delivery software uses advisory messages extensively. For example,
advisories inform sending and receiving programs of the delivery status of each
message. For complete details, see Certified Message Delivery (RVCM) Advisory
Messages on page 269 in TIBCO Rendezvous Concepts.
If your application sends or receives certified messages across network
boundaries, you must configure the Rendezvous routing daemons to exchange
_RVCM administrative messages. For details, see Certified Message Delivery on
Some programs require certified delivery to one of n worker processes. See
Distributed Queue on page 181 in TIBCO Rendezvous Concepts.
Topics
• TibrvCmListener, page 250

• TibrvCmTransport, page 257
• TibrvCmReviewCallback, page 291
• TibrvCmMsg, page 294

250
| Chapter 9 Certified Message Delivery
TibrvCmListener
Class
Declaration class com.tibco.tibrv.TibrvCmListener

extends TibrvListener
Purpose A certified delivery listener object listens for labeled messages and certified
messages.
Remarks Each call to the constructor TibrvCmListener() results in a new certified

delivery listener, which represents your program’s listening interest in a stream of
labeled messages and certified messages. Rendezvous software uses the same
listener object to signal each occurrence of such an event.
We recommend that programs explicitly destroy each certified delivery listener
object using TibrvCmListener.destroy(). Destroying a certified listener object
cancels the program’s immediate interest in that event, and frees its storage;
nonetheless, a parameter to the destroy call determines whether certified delivery
agreements continue to persist beyond the destroy call.
them automatically.
Destroying the queue or the certified delivery transport of a listener object
automatically destroys the listener as well (but certified delivery agreements
continue to persist).

TibrvCmListener() Listen for messages that match the 252
subject, and request certified delivery
when available.
TibrvCmListener.destroy() Destroy a certified delivery listener. 253
TibrvCmListener.confirmMsg() Explicitly confirm delivery of a certified 254

message.
TibrvCmListener.isExplicitConfirm() Test whether this listener expects explicit 255

confirmation of delivery.
TibrvCmListener.setExplicitConfirm() Override automatic confirmation of 256

delivery for this listener.

|
TibrvCmListener 251
Inherited Methods
TibrvListener.getSubject()
TibrvListener.getTransport()

TibrvListener on page 118

252
TibrvCmListener()
Constructor
Declaration TibrvCmListener(
TibrvQueue queue,
TibrvMsgCallback callback,
TibrvCmTransport cmTransport,
Purpose Listen for messages that match the subject, and request certified delivery when
available.
queue For each inbound message, place the listener event on this
event queue.
callback On dispatch, process the event with this callback object.
cmTransport Listen for inbound messages on this certified delivery

transport.
subject Listen for inbound messages with subjects that match this
specification. Wildcard subjects are permitted. The empty
string is not a legal subject name.
Activation and Details of listener event semantics are identical to those for ordinary listeners; see
Dispatch Activation and Dispatch on page 118.
Inbox Listener To receive unicast (point-to-point) messages, listen to a unique inbox subject
name. First call TibrvTransport.createInbox() to create the unique inbox
name; then call TibrvCmListener() to begin listening. Remember that other
programs have no information about an inbox until the listening program uses it
as a reply subject in an outbound message.
See Also TibrvCmListener on page 250

TibrvCmTransport.destroy()on page 269
TibrvListener.getSubject()on page 122
TibrvTransport.createInbox() on page 178

|
TibrvCmListener.destroy() 253
TibrvCmListener.destroy()
Method
void destroy(
boolean cancelAgreements)
Purpose Destroy a certified delivery listener.
cancelAgreements true cancels all certified delivery agreements of this
listener; certified senders delete from their ledgers all
messages sent to this listener.
false leaves all certified delivery agreements in effect,
so certified senders continue to store messages.
Canceling When destroying a certified delivery listener, a program can either cancel its
Agreements certified delivery agreements with senders, or let those agreements persist (so a
successor listener can receive the messages covered by those agreements).
When canceling agreements, each (previously) certified sender transport receives
a REGISTRATION.CLOSED advisory. Successor listeners cannot receive old
messages.

254
TibrvCmListener.confirmMsg()
Method
Declaration void confirmMsg(

TibrvMsg message)
Purpose Explicitly confirm delivery of a certified message.
Remarks Use this method only in programs that override automatic confirmation (see
TibrvCmListener.setExplicitConfirm() on page 256). The default behavior
of certified listeners is to automatically confirm delivery when the callback
method returns.
message Confirm receipt of this message.
Unregistered When a CM listener receives a labeled message, its behavior depends on context:
Message
• If a CM listener is registered for certified delivery, it presents the
supplementary information to the callback method. If the sequence number is
present, then the receiving program can confirm delivery.
• If a CM listener is not registered for certified delivery with the sender, it
presents the sender’s name to the callback method, but omits the sequence
number. In this case, the receiving program cannot confirm delivery;
TibrvCmListener.confirmMsg() throws an exception with the status code
TibrvStatus.NOT_PERMITTED.
Notice that the first labeled message that a program receives on a subject
might not be certified; that is, the sender has not registered a certified delivery
agreement with the listener. If appropriate, the certified delivery library
automatically requests that the sender register the listener for certified
delivery. (See Discovery and Registration for Certified Delivery on page 154 in
TIBCO Rendezvous Concepts.)
A labeled but uncertified message can also result when the sender explicitly
disallows or removes the listener.

TibrvCmListener.setExplicitConfirm() on page 256

|
TibrvCmListener.isExplicitConfirm() 255
TibrvCmListener.isExplicitConfirm()
Method
Declaration boolean isExplicitConfirm()
Purpose Test whether this listener expects explicit confirmation of delivery.
Remarks The default behavior of certified listeners is to automatically confirm delivery

when the callback method returns (see TibrvMsgCallback.onMsg() on
page 125). TibrvCmListener.setExplicitConfirm() on page 256 selectively
overrides this behavior for this specific listener (without affecting other listeners).
See Also TibrvCmListeneron page 250

TibrvCmListener.confirmMsg() on page 254
TibrvCmListener.setExplicitConfirm() on page 256

256
TibrvCmListener.setExplicitConfirm()
Method
Declaration void setExplicitConfirm()

Purpose Override automatic confirmation of delivery for this listener.
Remarks The default behavior of certified listeners is to automatically confirm delivery

when the callback method returns (see TibrvMsgCallback.onMsg() on
page 125). This call selectively overrides this behavior for this specific listener
(without affecting other listeners).
By overriding automatic confirmation, the listener assumes responsibility to
explicitly confirm each inbound certified message by calling
TibrvCmListener.confirmMsg().
Consider overriding automatic confirmation when the processing of inbound

messages involves activity that is asynchronous with respect to the message
callback method; for example, computations in other threads or additional
network communications.
No method exists to restore the default behavior—that is, to reverse the effect of
this method.
See Also TibrvCmListeneron page 250

TibrvCmListener.confirmMsg() on page 254
TibrvCmListener.isExplicitConfirm() on page 255

|
TibrvCmTransport 257
TibrvCmTransport
Class
Declaration class com.tibco.tibrv.TibrvCmTransport

Purpose A certified delivery transport object implements the CM delivery protocol for
messages.
Remarks Each certified delivery transport employs a TibrvTransport for network

communications. The TibrvCmTransport adds the accounting mechanisms
needed for delivery tracking and certified delivery.
Several TibrvCmTransport objects can employ a TibrvTransport, which also
remains available for its own ordinary listeners and for sending ordinary
messages. Destroying this TibrvTransport causes the TibrvCmTransport to
destroy itself as well (along with all its listeners, while preserving their certified
delivery agreements).
Destroying a certified delivery transport object invalidates subsequent certified
send calls on that object, invalidates any certified listeners using that transport
(while preserving the certified delivery agreements of those listeners).
Programs must explicitly destroy each certified delivery transport object.
Rendezvous software keeps internal references to these objects, so the Java
garbage collector does not delete them automatically.
(Sheet 1 of 3)

TibrvCmTransport() Create a transport for certified 261
delivery.
TibrvCmTransport.addListener() Pre-register an anticipated listener. 265
TibrvCmTransport.allowListener() Invite the named receiver to 266

reinstate certified delivery for its
listeners, superseding the effect of
any previous disallow calls.
TibrvCmTransport.connectToRelayAgent() Connect a certified delivery 267

transport to its designated relay
agent.
TibrvCmTransport.destroy() Destroy a certified delivery 269

transport.
TibrvCmTransport.destroyEx()

258
(Sheet 2 of 3)

TibrvCmTransport.disallowListener() Cancel certified delivery to all 270
listeners at a specific
correspondent. Deny subsequent
certified delivery registration
requests from those listeners.
TibrvCmTransport.disconnectFromRelayAgent() Disconnect a certified delivery 271

transport from its relay agent.
TibrvCmTransport.expireMessages() Mark specified outbound CM 272

messages as expired.
TibrvCmTransport.getDefaultTimeLimit() Get the default message time limit 273

for all outbound certified messages
from a transport.
TibrvCmTransport.getLedgerName() Extract the ledger name of a 274

certified delivery transport.
TibrvCmTransport.getName() Extract the correspondent name of 275

a certified delivery transport or
distributed queue member.
TibrvCmTransport.getRelayAgent() Extract the name of the relay agent 276

used by a certified delivery
transport.
TibrvCmTransport.getRequestOld() Extract the request old messages 277

flag of a certified delivery
transport.
TibrvCmTransport.getSyncLedger() Extract the sync ledger flag of a 278

certified delivery transport.
TibrvCmTransport.getTransport() Extract the transport employed by 279

a certified delivery transport or a
TibrvCmTransport.removeListener() Unregister a specific listener at a 280

specific correspondent, and free
associated storage in the sender’s
ledger.

|
TibrvCmTransport 259
(Sheet 3 of 3)

TibrvCmTransport.removeSendState() Reclaim ledger space from obsolete 282
subjects.
TibrvCmTransport.reviewLedger() Query the ledger for stored items 283

related to a subject name.
TibrvCmTransport.send() Send a labeled message. 284
TibrvCmTransport.sendReply() Send a labeled reply message. 285
TibrvCmTransport.sendRequest() Send a labeled request message 286

and wait for a reply.
TibrvCmTransport.setDefaultTimeLimit() Set the default message time limit 288

for all outbound certified messages
from a transport.
TibrvCmTransport.setPublisherInactivityDisc Set a time limit after which a 289

ardInterval() listening CM transport can discard
state for inactive CM senders.
TibrvCmTransport.syncLedger() Synchronize the ledger to its 290

storage medium.
Inherited Methods

260
Field Description
DEFAULT_TIME_LIMIT The default time limit (in seconds) for certified
messages sent on this transport.
The initial value is zero, a special value indicating
that messages do not expire.
Programs can change this value using
TibrvCmTransport.setDefaultTimeLimit().


|
TibrvCmTransport() 261
TibrvCmTransport()
Method
Declaration TibrvCmTransport(
TibrvRvdTransport transport)
TibrvCmTransport(
TibrvRvdTransport transport,
java.lang.String cmName,
boolean requestOld)
TibrvCmTransport(
boolean requestOld,
java.lang.String ledgerName,
boolean syncLedger)
TibrvCmTransport(
boolean requestOld,
java.lang.String ledgerName,
boolean syncLedger,
java.lang.String relayAgent)
Purpose Create a transport for certified delivery.
Remarks The new certified delivery transport must employ a valid transport for network
communications.
The certified delivery transport remains valid until the program explicitly
destroys it.
(Sheet 1 of 3)
transport The new TibrvCmTransport employs this transport object for network
communications.
This object must be a TibrvRvdTransport.
Destroying the TibrvCmTransport does not affect this TibrvRvdTransport object.

262
(Sheet 2 of 3)
cmName Bind this reusable name to the new TibrvCmTransport, so the TibrvCmTransport
represents a persistent correspondent with this name.
If non-null, the name must conform to the syntax rules for Rendezvous subject
names. It cannot begin with reserved tokens. It cannot be a non-reusable name
generated by another call to TibrvCmTransport(). It cannot be the empty string.
If omitted or null, then TibrvCmTransport() generates a unique, non-reusable
name for the duration of the transport.
For more information, see Name on page 263.
requestOld This parameter indicates whether a persistent correspondent requires delivery of

messages sent to a previous certified delivery transport with the same name, for
which delivery was not confirmed. Its value affects the behavior of other CM
sending transports.
If this parameter is true and cmName is non-null, then the new TibrvCmTransport
requires certified senders to retain unacknowledged messages sent to this
persistent correspondent. When the new TibrvCmTransport begins listening to the
appropriate subjects, the senders can complete delivery. (It is an error to supply
true when cmName is null.)
If this parameter is false (or omitted), then the new TibrvCmTransport does not
require certified senders to retain unacknowledged messages. Certified senders
may delete those messages from their ledgers.
ledgerName If this argument is non-null, then the new TibrvCmTransport uses a file-based
ledger. The argument must represent a valid file name. Actual locations
corresponding to relative file names conform to operating system conventions. We
strongly discourage using the empty string as a ledger file name.
If omitted or null, then the new TibrvCmTransport uses a process-based ledger.
For more information, see Ledger File on page 263.
syncLedger If this argument is true, then operations that update the ledger file do not return
until the changes are written to the storage medium.
If this argument is false (or omitted), the operating system writes changes to the
storage medium asynchronously.

|
TibrvCmTransport() 263
(Sheet 3 of 3)
relayAgent Designate the rvrad process with this name as the new transport’s relay agent.
If null or omitted, the new TibrvCmTransport does not use a relay agent.
If non-null, the relay agent name must conform to the syntax rules for reusable
names. For details, see Reusable Names on page 166 in TIBCO Rendezvous Concepts.
It is illegal for a relay agent to have the same name as a CM correspondent.
We strongly discourage using the empty string as a relay agent name.
For more information, see Relay Agent on page 263.
Method Forms With only a transport, create a transient correspondent, with a unique,
non-reusable name. (Supplying null as the cmName has the same effect.)
All other parameters are optional, with default values when omitted.
Name If cmName is null, then TibrvCmTransport() generates a unique, non-reusable

name for the new certified delivery transport.
If cmName is non-null, then the new transport binds that name. A correspondent
can persist beyond transport destruction only when it has both a reusable name
and a file-based ledger.
For more information about the use of reusable names, see CM Correspondent
Name on page 150 in TIBCO Rendezvous Concepts, and Persistent Correspondents
on page 159 in TIBCO Rendezvous Concepts. For details of reusable name syntax,
see Reusable Names on page 166 in TIBCO Rendezvous Concepts.
Relay Agent TibrvCmTransport() automatically connects a transport to its designated relay

agent upon creation; see TibrvCmTransport.connectToRelayAgent() on
page 267.
Ledger File Every certified delivery transport stores the state of its certified communications
in a ledger.
If ledgerFile is null, then the new transport stores its ledger exclusively in
process-based storage. When you destroy the transport or the process terminates,
all information in the ledger is lost.

264
If ledgerFile specifies a valid file name, then the new transport uses that file for
ledger storage. If the transport is destroyed or the process terminates with
incomplete certified communications, the ledger file records that state. When a
new transport binds the same reusable name, it reads the ledger file and continues
certified communications from the state stored in the file.
Even though a transport uses a ledger file, it may sometimes replicate parts of the
ledger in process-based storage for efficiency; however, programmers cannot rely
on this replication.
The syncLedger parameter determines whether writing to the ledger file is a
synchronous operation:
• To specify synchronous writing, supply true. Each time Rendezvous software
writes a ledger item, the call does not return until the data is safely stored in
the storage medium.
• To specify asynchronous writing (the default), supply false. Certified
delivery calls may return before the data is safely stored in the storage
medium, which results in greater speed at the cost of certainty. The ledger file
might not accurately reflect program state in cases of hardware or operating
system kernel failure (but it is accurate in cases of sudden program failure).
Despite this small risk, we strongly recommend this option for maximum
performance.
A program that uses an asynchronous ledger file can explicitly synchronize it
by calling TibrvCmTransport.syncLedger() on page 290.
Destroying a transport with a file-based ledger always leaves the ledger file intact;
it neither erases nor removes a ledger file.
The ledger file must reside on the same host computer as the program that uses it.
See Also TibrvCmTransport.destroy() on page 269

TibrvCmTransport.connectToRelayAgent() on page 267

|
TibrvCmTransport.addListener() 265
TibrvCmTransport.addListener()
Method
Declaration void addListener(

java.lang.String subject)
Purpose Pre-register an anticipated listener.
Remarks Some sending programs can anticipate requests for certified delivery—even
before the listening programs actually register. In such situations, the sending
transport can pre-register listeners, so Rendezvous software begins storing
outbound messages in the sender’s ledger; when the listener requests certified
delivery, it receives the backlogged messages.
If the correspondent with this cmName already receives certified delivery of this
subject from this sender transport, then TibrvCmTransport.addListener()
has no effect.
If the correspondent with this cmName is disallowed,
TibrvCmTransport.addListener() returns an exception with status code
TibrvStatus.NOT_PERMITTED. You can call
TibrvCmTransport.allowListener() to supersede the effect of a prior call to
TibrvCmTransport.disallowListener(); then call
TibrvCmTransport.addListener() again.
It is not sufficient for a sender to use this method to anticipate listeners; the
anticipated listening programs must also require old messages when creating
certified delivery transports.
cmName Anticipate a listener from a correspondent with this reusable
name.
subject Anticipate a listener for this subject. Wildcard subjects are illegal.
See Also Name, page 263

TibrvCmTransport.allowListener() on page 266
TibrvCmTransport.disallowListener() on page 270
TibrvCmTransport.removeListener() on page 280
Anticipating a Listener, page 161 in TIBCO Rendezvous Concepts

266
TibrvCmTransport.allowListener()
Method
Declaration void allowListener(

java.lang.String cmName)
Purpose Invite the named receiver to reinstate certified delivery for its listeners,
superseding the effect of any previous disallow calls.
Remarks Upon receiving the invitation to reinstate certified delivery, Rendezvous software
at the listening program automatically sends new registration requests. The
sending program accepts these requests, restoring certified delivery.
cmName Accept requests for certified delivery to listeners at the
transport with this correspondent name.

Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TibrvCmTransport.connectToRelayAgent() 267
|
TibrvCmTransport.connectToRelayAgent()
Method
Declaration void connectToRelayAgent()

Purpose Connect a certified delivery transport to its designated relay agent.
Remarks Programs may specify a relay agent when creating a CM transport object.
Connect calls are non-blocking; they immediately return control to the program,
and asynchronously attempt to connect to the relay agent (continuing until they
succeed, or until the program makes a disconnect call).
When a transport attempts to connect to a relay agent, Rendezvous software
automatically locates the relay agent process (if it exists). When the program
successfully connects to the relay agent, they synchronize:
• The transport receives a RELAY.CONNECTED advisory, informing it of
successful contact with the relay agent. (Listen for all advisory messages on
the ordinary TibrvTransport that the TibrvCmTransport employs.)
(When a program cannot locate its relay agent, certified delivery software
produces DELIVERY.NO_RESPONSE advisories; however, we recommend
against designing programs to rely on this side effect.)
• If the client transport is a CM listener, the relay agent listens to the same set of
subjects on behalf of the client. The relay agent also updates its confirmation
state to reflect the state of the transport.
• If the client transport is a CM sender, the relay agent updates its acceptance
state to reflect the state of the transport. The sending client updates its
confirmation state to reflect the state of the relay agent.
• The transport and relay agent exchange the CM data messages that they have
been storing during the time they were disconnected.
We recommend that programs remain connected for a minimum of two minutes,

to allow time for this synchronization to complete. (Two minutes is a generous
estimate, which is sufficient for most situations. Actual time synchronization time
can be much shorter, and varies with the number of stored messages and the
degree to which protocol state has changed.)
If the transport is already connected to its relay agent, then this method returns
normally, and does not trigger a RELAY.CONNECTED advisory.
TibrvCmTransport() automatically connects a transport to its designated relay
agent upon creation.

268
Errors The error code TibrvStatus.INVALID_ARG can indicate that the transport does
not have a relay agent.
See Also TibrvCmTransport() on page 261

TibrvCmTransport.disconnectFromRelayAgent() on page 271
Relay Agent, page 169 in TIBCO Rendezvous Concepts

|
TibrvCmTransport.destroy() 269
TibrvCmTransport.destroy()
Method
void destroyEx()
Purpose Destroy a certified delivery transport.
Remarks Destroying a certified delivery transport with a file-based ledger always leaves
the ledger file intact; it neither erases nor removes a ledger file.
These methods automatically disconnect the transport from its relay agent before
destroying the object; see TibrvCmTransport.disconnectFromRelayAgent().
Distributed To destroy a distributed queue transport, use destroyEx(). With the ordinary
Queue destroy call, the distributed queue can lose reliable (non-certified) task messages
before they are processed. In contrast, destroyEx() blocks until previously
assigned tasks are complete; then it destroys the transport and returns. Do not
destroy the underlying transport, nor the transport’s listeners until after
destroyEx() returns.
Restrictions destroyEx() is available in both the thin-message JNI implementation and the
full-message JNI implementation. It is not available in the pure Java
implementation.

TibrvCmTransport.disconnectFromRelayAgent() on page 271

270
TibrvCmTransport.disallowListener()
Method
Declaration void disallowListener(

Purpose Cancel certified delivery to all listeners at a specific correspondent. Deny

subsequent certified delivery registration requests from those listeners.
Remarks Disallowed listeners still receive subsequent messages from this sender, but
delivery is not certified. In other words:
• The listener receives a REGISTRATION.NOT_CERTIFIED advisory, informing it
that the sender has canceled certified delivery of all subjects.
• If the sender’s ledger contains messages sent to the disallowed listener (for
which this listener has not confirmed delivery), then Rendezvous software
removes those ledger items, and does not attempt to redeliver those messages.
• Rendezvous software presents subsequent messages (from the canceling
sender) to the listener without a sequence number, to indicate that delivery is
not certified.
Senders can promptly revoke the acceptance of certified delivery by calling

TibrvCmTransport.disallowListener() within the callback method that
processes the REGISTRATION.REQUEST advisory.
This method disallows a correspondent by name. If the correspondent terminates,
and another process instance (with the same reusable name) takes its place, the
new process is still disallowed by this sender.
To supersede the effect of TibrvCmTransport.disallowListener(), call
TibrvCmTransport.allowListener() on page 266.
cmName Cancel certified delivery to listeners of the transport with this
name.

TibrvCmTransport.allowListener() on page 266
Disallowing Certified Delivery, page 164 in TIBCO Rendezvous Concepts

TibrvCmTransport.disconnectFromRelayAgent() 271
|
TibrvCmTransport.disconnectFromRelayAgent()
Method
Declaration void disconnectFromRelayAgent()

Purpose Disconnect a certified delivery transport from its relay agent.
Remarks Disconnect calls are non-blocking; they immediately return control to the
program, and asynchronously proceed with these clean-up tasks:
• If the client transport is a CM listener, the relay agent attempts to synchronize
its listening state with the transport (to assure that the relay agent adequately
represents the listening interest of the client).
• The transport stops communicating with the relay agent.
• The transport stores subsequent outbound events—including data messages
and protocol state changes. If the transport is a certified sender, it cancels its
request for delivery confirmation of outstanding unconfirmed messages. (See
also, Requesting Confirmation on page 157 in TIBCO Rendezvous Concepts.)
• The relay agent stores subsequent inbound events for the transport—
including data messages and protocol state changes.
• A transport that explicitly disconnects without terminating receives a
RELAY.DISCONNECTED advisory, informing it that is safe to sever the physical
network connection. (Terminating transports never receive this advisory;
instead, it is safe to sever the connection when the destroy call returns.)
TibrvCmTransport.destroy() automatically disconnects a CM transport from

its relay agent before termination.
See Also TibrvCmTransport.connectToRelayAgent() on page 267

TibrvCmTransport.destroy() on page 269
Relay Agent, page 169 in TIBCO Rendezvous Concepts

272
TibrvCmTransport.expireMessages()
Method
Declaration void expireMessages(

String subject,
long sequenceNumber)
throws TibrvException;
Purpose Mark specified outbound CM messages as expired.
Remarks This call checks the ledger for messages that match both the subject and sequence
number criteria, and immediately marks them as expired.
Once a message has expired, the CM transport no longer attempts to redeliver it
to registered listeners.
Rendezvous software presents each expired message to the sender in a
DELIVERY.FAILED advisory. Each advisory includes all the fields of an expired
message. (This call can cause many messages to expire simultaneously.)
Use with extreme caution. This call exempts the expired messages from certified
delivery semantics. It is appropriate only in very few situations.
For example, consider an application program in which an improperly formed
CM message causes registered listeners to exit unexpectedly. When the listeners
restart, the sender attempts to redeliver the offending message, which again
causes the listeners to exit. To break this cycle, the sender can expire the offending
message (along with all prior messages bearing the same subject).
subject Mark messages with this subject.
Wildcards subjects are permitted, but must exactly reflect
the send subject of the message. For example, if the
program sends to A.* then you may expire messages with
subject A.* (however, A.> does not resolve to match A.*).
sequenceNumber Mark messages with sequence numbers less than or equal

to this value.
See Also DELIVERY.FAILED on page 276 in TIBCO Rendezvous Concepts

|
TibrvCmTransport.getDefaultTimeLimit() 273
TibrvCmTransport.getDefaultTimeLimit()
Method
Declaration double getDefaultTimeLimit()
Purpose Get the default message time limit for all outbound certified messages from a
transport.
Remarks Every labeled message has a time limit, after which the sender no longer certifies
delivery.
Sending programs can explicitly set the time limit on a message (see
TibrvCmMsg.setTimeLimit() on page 299). If a time limit is not already set for
the outbound message, the transport sets it to the transport’s default time limit
(extractable with this method); if this default is not set for the transport (nor for
the message), the default time limit is zero (no time limit).
Time limits represent the minimum time that certified delivery is in effect.
See Also TibrvCmTransport.setDefaultTimeLimit() on page 288

TibrvCmMsg.setTimeLimit() on page 299

274
TibrvCmTransport.getLedgerName()
Method
Declaration java.lang.String getLedgerName()
Purpose Extract the ledger name of a certified delivery transport.
Errors The error code TibrvStatus.ARG_CONFLICT can indicate that the transport does
not have a ledger file.
See Also Ledger File, page 263

TibrvCmTransport() on page 261

|
TibrvCmTransport.getName() 275
TibrvCmTransport.getName()
Method
Declaration java.lang.String getName()
Purpose Extract the correspondent name of a certified delivery transport or distributed

queue member.

TibrvCmQueueTransport() on page 306

276
TibrvCmTransport.getRelayAgent()
Method
Declaration java.lang.String getRelayAgent()
Purpose Extract the name of the relay agent used by a certified delivery transport.
See Also Relay Agent, page 263


|
TibrvCmTransport.getRequestOld() 277
TibrvCmTransport.getRequestOld()
Method
Declaration boolean getRequestOld()
Purpose Extract the request old messages flag of a certified delivery transport.
See Also requestOld on page 262


278
TibrvCmTransport.getSyncLedger()
Method
Declaration boolean getSyncLedger()
Purpose Extract the sync ledger flag of a certified delivery transport.


|
TibrvCmTransport.getTransport() 279
TibrvCmTransport.getTransport()
Method
Declaration TibrvRvdTransport getTransport()
Purpose Extract the transport employed by a certified delivery transport or a distributed

queue member.
See Also TibrvTransporton page 176

TibrvRvdTransporton page 198

280
TibrvCmTransport.removeListener()
Method
Declaration void removeListener(

Purpose Unregister a specific listener at a specific correspondent, and free associated

storage in the sender’s ledger.
Remarks This method cancels certified delivery of the specific subject to the
correspondent with this name. The listening correspondent may subsequently
re-register for certified delivery of the subject. (In contrast,
TibrvCmTransport.disallowListener() cancels certified delivery of all
subjects to the correspondent, and prohibits re-registration.)
Senders can call this method when the ledger item for a listening correspondent
has grown very large. Such growth indicates that the listener is not confirming
delivery, and may have terminated. Removing the listener reduces the ledger size
by deleting messages stored for the listener.
When a sending program calls this method, certified delivery software in the
sender behaves as if the listener had closed the endpoint for the subject. The
sending program deletes from its ledger all information about delivery of the
subject to the correspondent with this cmName. The sending program receives a
REGISTRATION.CLOSED advisory, to trigger any operations in the callback method
for the advisory.
If the listening correspondent is available (running and reachable), it receives a
REGISTRATION.NOT_CERTIFIED advisory, informing it that the sender no longer
certifies delivery of the subject.
If the correspondent with this name does not receive certified delivery of the
subject from this sender TibrvCmTransport, then
TibrvCmTransport.removeListener() throws an exception with the status code
TibrvStatus.INVALID_ARG.
cmName Cancel certified delivery of the subject to listeners of this
correspondent.
subject Cancel certified delivery of this subject to the named listener.

Wildcard subjects are illegal.

|
TibrvCmTransport.removeListener() 281
TibrvCmTransport.addListener() on page 265

Canceling Certified Delivery, page 162 in TIBCO Rendezvous Concepts

282
TibrvCmTransport.removeSendState()
Method
Declaration void removeSendState(

Purpose Reclaim ledger space from obsolete subjects.
Background In some programs subject names are useful only for a limited time; after that time,
they are never used again. For example, consider a server program that sends
certified reply messages to client inbox names; it only sends one reply message to
each inbox, and after delivery is confirmed and complete, that inbox name is
obsolete. Nonetheless, a record for that inbox name remains in the server’s ledger.
As such obsolete records accumulate, the ledger size grows. To counteract this
growth, programs can use this method to discard obsolete subject records from
the ledger.
The DELIVERY.COMPLETE advisory is a good opportunity to clear the send state of
an obsolete subject. Another strategy is to review the ledger periodically,
sweeping to detect and remove all obsolete subjects.
Do not use this method to clear subjects that are still in use.
subject Remove send state for this obsolete subject.
Remarks As a side-effect, this method resets the sequence numbering for the subject, so the
next message sent on the subject would be number 1. In proper usage, this
side-effect is never detected, since obsolete subjects are truly obsolete.
See Also TibrvCmTransport.reviewLedger() on page 283

TibrvCmTransport.send() on page 284
DELIVERY.COMPLETE on page 274 in TIBCO Rendezvous Concepts

|
TibrvCmTransport.reviewLedger() 283
TibrvCmTransport.reviewLedger()
Method
Declaration void reviewLedger(

TibrvCmReviewCallback callback,
Purpose Query the ledger for stored items related to a subject name.
Remarks The callback method receives one message for each matching subject of outbound
messages stored in the ledger. For example, when FOO.* is the subject,
TibrvCmTransport.reviewLedger() calls its callback method separately for
each matching subject—once for FOO.BAR, once for FOO.BAZ, and once for
FOO.BOX.
However, if the callback method returns non-null, then

TibrvCmTransport.reviewLedger() returns immediately.
If the ledger does not contain any matching items,
TibrvCmTransport.reviewLedger() returns normally without calling the
callback method.
For information about the content and format of the callback messages, see
TibrvCmReviewCallback.onLedgerMsg() on page 292.
callback This object receives the review messages.
subject Query for items related to this subject name.

If this subject contains wildcard characters (* or >), then review
all items with matching subject names. The callback method
receives a separate message for each matching subject in the
ledger.
closure Pass this closure data to the review callback method.
See Also TibrvCmReviewCallback.onLedgerMsg() on page 292

284
TibrvCmTransport.send()
Method
Declaration void send(

TibrvMsg msg)
Purpose Send a labeled message.
Remarks This method sends the message, along with its certified delivery protocol
information: the correspondent name of the TibrvCmTransport, a sequence
number, and a time limit. The protocol information remains on the message
within the sending program, and also travels with the message to all receiving
programs.
Programs can explicitly set the message time limit; see
TibrvCmMsg.setTimeLimit() on page 299. If a time limit is not already set for
the outbound message, this method sets it to the transport’s default time limit (see
TibrvCmTransport.setDefaultTimeLimit() on page 288); if that default is not
set for the transport, the default time limit is zero (no time limit).
msg Send this message.
See Also TibrvCmTransport.sendReply() on page 285

TibrvCmTransport.sendRequest() on page 286
TibrvCmTransport.setDefaultTimeLimit() on page 288

|
TibrvCmTransport.sendReply() 285
TibrvCmTransport.sendReply()
Method
Declaration void sendReply(

TibrvMsg replyMsg,
TibrvMsg requestMsg)
Purpose Send a labeled reply message.
Remarks This convenience call extracts the reply subject of an inbound request message,
and sends a labeled outbound reply message to that subject. In addition to the
convenience, this call is marginally faster than using separate calls to extract the
subject and send the reply.
This method can send a labeled reply to an ordinary message.
This method automatically registers the requesting CM transport, so the reply
message is certified.
replyMsg Send this outbound reply message.
requestMsg Send a reply to this inbound request message; extract its reply
subject to use as the subject of the outbound reply message.
If this message has a wildcard reply subject, the method
produces an error.
Give special attention to the order of the arguments to this method. Reversing the
inbound and outbound messages can cause an infinite loop, in which the program
repeatedly resends the inbound message to itself (and all other recipients).
See Also TibrvCmTransport.send() on page 284

TibrvCmTransport.sendRequest() on page 286

286
TibrvCmTransport.sendRequest()
Method
Declaration TibrvMsg sendRequest(

TibrvMsg msg,
double timeout)
Purpose Send a labeled request message and wait for a reply.
Blocking can Stall Event Dispatch
This call blocks all other activity on its program thread. If appropriate,
programmers must ensure that other threads continue dispatching events on its
queues.
msg Send this request message.
waiting for a reply.
Remarks Programs that receive and process the request message cannot determine that the
sender has blocked until a reply arrives.
The sender and receiver must already have a certified delivery agreement,
otherwise the request is not certified.
The request message must have a valid destination subject; see
A certified request does not necessarily imply a certified reply; the replying
program determines the type of reply message that it sends.
Operation This method operates in several synchronous steps:

1. Create a TibrvCmListener that listens for messages on the reply subject of
msg.
2. Label and send the outbound message.

TibrvCmTransport.sendRequest() 287
|
3. Block until the listener receives a reply; if the time limit expires before a reply
arrives, then return null. (The reply event uses a private queue that is not
accessible to the program.)
4. Return the reply message as the value of the method call.

TibrvCmTransport.sendReply() on page 285

288
TibrvCmTransport.setDefaultTimeLimit()
Method
Declaration void setDefaultTimeLimit(

double timeLimit)
Purpose Set the default message time limit for all outbound certified messages from a
transport.
delivery.
Sending programs can explicitly set the time limit on a message (see
TibrvCmMsg.setTimeLimit() on page 299). If a time limit is not already set for
the outbound message, the transport sets it to the transport’s default time limit
(set with this method); if this default is not set for the transport, the default time
limit is zero (no time limit).
timeLimit Use this time limit (in whole seconds). The time limit must be
non-negative.
See Also TibrvCmTransport.getDefaultTimeLimit() on page 273


|
TibrvCmTransport.setPublisherInactivityDiscardInterval() 289
TibrvCmTransport.setPublisherInactivityDiscardInterval()
Method
Declaration void setPublisherInactivityDiscardInterval(

int timeout);
Purpose Set a time limit after which a listening CM transport can discard state for inactive
CM senders.
Remarks The timeout value limits the time that can elapse during which such a sender does
not send a message. When the elapsed time exceeds this limit, the listening
transport declares the sender inactive, and discards internal state corresponding
to the sender.
We discourage programmers from using this call except to solve a very specific
problem, in which a long-running CM listener program accumulates state for a
large number of obsolete CM senders with non-reusable names.
Before using this call, review every subject for which the CM transport has a
listener; ensure that only CM senders with non-reusable names send to those
subjects. (If senders with reusable names send messages to such subjects, the
listening transport can discard their state, and incorrect behavior can result.)
timeout Use this time limit (in whole seconds). The time limit must be
non-negative.

290
TibrvCmTransport.syncLedger()
Method
Declaration void syncLedger()

Purpose Synchronize the ledger to its storage medium.
Remarks When this method returns, the transport’s current state is safely stored in the
ledger file.
Transports that use synchronous ledger files need not call this method, since the
current state is automatically written to the storage medium before returning.
Transports that use process-based ledger storage need not call this method, since
they have no ledger file.

TibrvCmTransport.getSyncLedger() on page 278

|
TibrvCmReviewCallback 291
TibrvCmReviewCallback
Interface
Declaration interface com.tibco.tibrv.TibrvCmReviewCallback
Purpose Process ledger review messages.
Remarks Implement this interface to process ledger review messages.

TibrvCmReviewCallback.onLedgerMsg() Programs define this method to process 247
ledger review messages.

292
TibrvCmReviewCallback.onLedgerMsg()
Method
Declaration boolean onLedgerMsg(

TibrvCmTransport cmTransport,
TibrvMsg msg,
Purpose Programs define this method to process ledger review messages.
Remarks TibrvCmTransport.reviewLedger() calls this callback method once for each

matching subject stored in the ledger.
To continue reviewing the ledger, return false from this callback method. To stop
reviewing the ledger, return true from this callback method;
TibrvCmTransport.reviewLedger() cancels the review and returns
immediately.
cmTransport This parameter receives the transport.
subject This parameter receives the subject for this ledger item.
msg This parameter receives a summary message describing the

delivery status of messages in the ledger. The table on
page 292 describes the fields of the summary message.
closure This parameter receives closure data that the program

supplied to TibrvCmTransport.reviewLedger().
(Sheet 1 of 2)
Field Name Description

subject The subject that this message summarizes.
This field has datatype TibrvMsg.STRING.
seqno_last_sent The sequence number of the most recent message sent with this
subject name.
This field has datatype TibrvMsg.U64.

|
TibrvCmReviewCallback.onLedgerMsg() 293
(Sheet 2 of 2)
Field Name Description

total_msgs The total number of messages stored at this subject name.
total_size The total storage (in bytes) occupied by all messages with this
subject name.
If the ledger contains several messages with this subject name,
then this field sums the storage space over all of them.
This field has datatype TibrvMsg.I64.
listener Each summary message can contain one or more fields named
listener. Each listener field contains a nested submessage with
details about a single registered listener.
This field has datatype TibrvMsg.MSG.
listener.name Within each listener submessage, the name field contains the
name of the listener transport.
This field has datatype TibrvMsg.STRING.
listener.last_confirmed Within each listener submessage, the last_confirmed field

contains the sequence number of the last message for which the
listener confirmed delivery.

294
TibrvCmMsg
Class
Declaration class com.tibco.tibrv.TibrvCmMsg

Purpose Define methods to manipulate labeled messages.
Remarks Programs do not create instances of TibrvCmMsg. Instead, programs use its static
methods to get and set certified delivery information of TibrvMsg objects.

TibrvCmMsg.getSender() Extract the correspondent name of the sender from a 295
certified message.
TibrvCmMsg.getSequence() Extract the sequence number from a certified message. 296
TibrvCmMsg.getTimeLimit() Extract the message time limit from a certified message. 298
TibrvCmMsg.setTimeLimit() Set the message time limit of a certified message. 299
Inherited Methods
See Also TibrvMsg on page 46

|
TibrvCmMsg.getSender() 295
TibrvCmMsg.getSender()
Method
Declaration static final java.lang.String getSender(

TibrvMsg msg)
Purpose Extract the correspondent name of the sender from a certified message.
Remarks If the message is from a CM sender, then TibrvCmMsg.getSender() yields a valid

CM correspondent name. If the message is not from a CM sender, then
TibrvCmMsg.getSender() returns null.
msg Extract the sender name from this message.

TibrvCmTransport.getName() on page 275

296
TibrvCmMsg.getSequence()
Method
Declaration static final long getSequence(

TibrvMsg msg)
Purpose Extract the sequence number from a certified message.
Remarks Rendezvous certified delivery sending methods automatically generate positive

sequence numbers for outbound labeled messages.
In receiving programs, zero is a special value, indicating that an inbound message
is not certified.
msg Extract the sequence number from this message.
Exception This method throws an exception to discriminate between certified messages

(included in a certified delivery agreement) and other messages.
• If the message is from a CM sender, and the CM listener is registered for
certified delivery with that sender, then TibrvCmMsg.getSequence() yields a
valid sequence number.
• If the message is from a CM sender, but the listener is not registered for
certified delivery, then TibrvCmMsg.getSequence() in the context of a
TibrvCmListener’s callback method throws an exception with the status code
TibrvStatus.NOT_FOUND. (In any other context, it returns the actual sequence
number stored on the message.)
Notice that the first labeled message that a program receives on a subject
might not be certified; that is, the sender has not registered a certified delivery
agreement with the listener. If appropriate, the certified delivery library
automatically requests that the sender register the listener for certified
delivery. (See Discovery and Registration for Certified Delivery on page 154 in
TIBCO Rendezvous Concepts.)
A labeled but uncertified message can also result when the sender explicitly
disallows or removes the listener.
• If the message is not from a CM sender, then TibrvCmMsg.getSequence() (in
any context) returns zero.
Release 5 In release 6 (and later) the sequence number is a 64-bit unsigned integer, while in
Interaction older releases (5 and earlier) it is a 32-bit unsigned integer.

|
TibrvCmMsg.getSequence() 297
When 32-bit senders overflow the sequence number, behavior is undefined.

When 64-bit senders send sequence numbers greater than 32 bits, 32-bit receivers
detect malformed label information, and process the message as an ordinary
reliable message (uncertified and unlabeled).

298
TibrvCmMsg.getTimeLimit()
Method
Declaration static final double getTimeLimit(

TibrvMsg msg)
Purpose Extract the message time limit from a certified message.
Remarks Programs can explicitly set the message time limit (see
TibrvCmMsg.setTimeLimit() on page 299).
Zero is a special value, indicating no time limit.

If a time limit is not set for a message, this method returns zero. This situation can
occur only for unsent outbound messages, and for inbound unlabeled messages.
This value represents the total time limit of the message, not the time remaining.
msg Extract the time limit from this message.


|
TibrvCmMsg.setTimeLimit() 299
TibrvCmMsg.setTimeLimit()
Method
Declaration static final void setTimeLimit(

TibrvMsg msg,
double timeLimit)
Purpose Set the message time limit of a certified message.
delivery.
Sending programs can explicitly set the message time limit using this method. If a
time limit is not already set for the outbound message,
TibrvCmTransport.send() sets it to the transport’s default time limit (see
TibrvCmTransport.setDefaultTimeLimit() on page 288); if that default is not
set for the transport, the default time limit is zero (no time limit).
It is meaningless for receiving programs to call this method.
msg Set the time limit of this message.
timeLimit Use this time limit (in whole seconds) for the message. The
time limit must be non-negative.
See Also TibrvCmTransport.getDefaultTimeLimit() on page 273

TibrvCmTransport.setDefaultTimeLimit() on page 288
TibrvCmMsg.getTimeLimit() on page 298

300

| 301
Chapter 10 Distributed Queue
Programs can use distributed queues for one of n certified delivery to a group of
worker processes.
A distributed queue is a group of TibrvCmQueueTransport objects, each in a
separate process. From the outside, a distributed queue appears as though a
single transport object; inside, the group members act in concert to process
inbound task messages. Ordinary senders and CM senders can send task
messages to the group. Notice that the senders are not group members, and do
not do anything special to send messages to a group; rather, they send messages
to ordinary subject names. Inside the group, the member acting as scheduler
assigns each task message to exactly one of the other members (which act as
workers); only that worker processes the task message. Each member uses CM
listener objects to receive task messages.
Distributed queues depend upon the certified delivery methods and the fault
tolerance methods.
We do not recommend sending messages across network boundaries to a

distributed queue, nor distributing queue members across network boundaries.
However, when crossing network boundaries in either of these ways, you must
configure the Rendezvous routing daemons to exchange _RVCM and _RVCMQ
administrative messages. For details, see Distributed Queues on page 379 in
See Also Distributed Queue, page 181 in TIBCO Rendezvous Concepts
Topics
• TibrvCmQueueTransport, page 302

302
| Chapter 10 Distributed Queue
TibrvCmQueueTransport
Class
Declaration class com.tibco.tibrv.TibrvCmQueueTransport

extends TibrvCmTransport
Purpose Coordinate a distributed queue for one-of-n delivery.
Remarks Each TibrvCmQueueTransport object employs a TibrvTransport for network

communications. The TibrvCmQueueTransport adds the accounting and
coordination mechanisms needed for one-of-n delivery.
Several TibrvCmQueueTransport objects can employ one TibrvTransport,
which also remains available for its own ordinary listeners and for sending
ordinary messages.
Programs must explicitly destroy each TibrvCmQueueTransport object.
Destroying a TibrvCmQueueTransport invalidates any certified listeners using
that transport (while preserving their certified delivery agreements).
Whether explicitly or implicitly, programs must destroy instances of this class.
Rendezvous software keeps internal references to these objects, so the Java
garbage collector does not delete them automatically.
All members of a distributed queue must listen to exactly the same set of subjects.
See Enforcing Identical Subscriptions on page 184 in TIBCO Rendezvous Concepts.
Scheduler recovery and task rescheduling are available only when the task
message is a certified message (that is, a certified delivery agreement is in effect
between the task sender and the distributed queue transport scheduler).
Disabled Although TibrvCmQueueTransport is a subclass of TibrvCmTransport, all

Methods methods related to sending messages are disabled in TibrvCmQueueTransport.
These disabled methods throw an IllegalStateException; for a list, see
Disabled Methods on page 304. See also Certified Delivery Behavior in Queue
Members on page 183 in TIBCO Rendezvous Concepts.
(Sheet 1 of 2)

TibrvCmQueueTransport() Create a transport as a 306
TibrvCmQueueTransport.destroy() Destroy a distributed queue 309

member object.

|
TibrvCmQueueTransport 303
(Sheet 2 of 2)

TibrvCmQueueTransport.getCompleteTime() Extract the worker complete 310
time limit of a distributed
queue member.
TibrvCmQueueTransport.getUnassignedMessageCount() Extract the number of 311

unassigned task messages
from a distributed queue
transport.
TibrvCmQueueTransport.getWorkerWeight() Extract the worker weight 312

of a distributed queue
member.
TibrvCmQueueTransport.getWorkerTasks() Extract the worker task 313

capacity of a distributed
queue member.
TibrvCmQueueTransport.setCompleteTime() Set the worker complete 314

time limit of a distributed
queue member.
TibrvCmQueueTransport.setTaskBacklogLimit...() Set the scheduler task queue 315

limits of a distributed queue
transport.
TibrvCmQueueTransport.setWorkerWeight() Set the worker weight of a 316

TibrvCmQueueTransport.setWorkerTasks() Set the worker task capacity 317

of a distributed queue
member.

304
Inherited Methods
Legal TibrvCmTransport.getName()
Methods TibrvCmTransport.getTransport()
TibrvTransport.isValid() (override)
Disabled TibrvCmTransport.addListener()
Methods TibrvCmTransport.allowListener()
TibrvCmTransport.connectToRelayAgent()
TibrvCmTransport.disallowListener()
TibrvCmTransport.disconnectFromRelayAgent()
TibrvCmTransport.getDefaultTimeLimit()
TibrvCmTransport.getLedgerName()
TibrvCmTransport.getRelayAgent()
TibrvCmTransport.getRequestOld()
TibrvCmTransport.getSyncLedger()
TibrvCmTransport.removeListener()
TibrvCmTransport.removeSendState()
TibrvCmTransport.reviewLedger()
TibrvCmTransport.send()
TibrvCmTransport.sendReply()
TibrvCmTransport.sendRequest()
TibrvCmTransport.setDefaultTimeLimit()
TibrvCmTransport.syncLedger()
TibrvCmQueueTransport.DEFAULT_COMPLETE_TIME static final double 0
TibrvCmQueueTransport.DEFAULT_WORKER_WEIGHT static final int 1

|
TibrvCmQueueTransport 305
TibrvCmQueueTransport.DEFAULT_WORKER_TASKS static final int 1
TibrvCmQueueTransport.DEFAULT_SCHEDULER_WEIGHT static final int 1
TibrvCmQueueTransport.DEFAULT_SCHEDULER_HEARTBEAT static final double 1.0
TibrvCmQueueTransport.DEFAULT_SCHEDULER_ACTIVATION static final double 3.5


306
TibrvCmQueueTransport()
Constructor
Declaration TibrvCmQueueTransport(
TibrvCmQueueTransport(
int workerWeight,
int workerTasks,
int schedulerWeight,
double schedulerHeartbeat,
double schedulerActivation)
Purpose Create a transport as a distributed queue member.
Remarks The new TibrvCmQueueTransport must employ a valid TibrvRvdTransport for

network communications.
(Sheet 1 of 3)
transport The new TibrvCmQueueTransport employs this TibrvRvdTransport
object for network communications.
Destroying the TibrvCmQueueTransport does not affect this transport.
cmName Bind this reusable name to the new transport object, which becomes a
member of the distributed queue with this name.
The name must be non-null, and conform to the syntax rules for
Rendezvous subject names. It cannot begin with reserved tokens. It
cannot be a non-reusable name generated by a call to
TibrvCmTransport(). It cannot be the empty string.
For more information, see Reusable Names on page 166 in TIBCO


|
TibrvCmQueueTransport() 307
(Sheet 2 of 3)
workerWeight When the scheduler receives a task, it assigns the task to the available
worker with the greatest worker weight.
A worker is considered available unless either of these conditions are
true:
• The pending tasks assigned to the worker member exceed its task
capacity.
• The worker is also the scheduler. (The scheduler assigns tasks to its
own worker role only when no other workers are available.)
When omitted, the default value is 1.
workerTasks Task capacity is the maximum number of tasks that a worker can accept.
When the number of accepted tasks reaches this maximum, the worker
cannot accept additional tasks until it completes one or more of them.
When the scheduler receives a task, it assigns the task to the worker with
the greatest worker weight—unless the pending tasks assigned to that
worker exceed its task capacity. When the preferred worker has too
many tasks, the scheduler assigns the new inbound task to the worker
with the next greatest worker weight.
When omitted, the default value is 1. Value must be greater than zero.
Tuning task capacity to compensate for communication time lag is more

complicated than it might seem. Before setting this value to anything
other than 1, see Task Capacity on page 186 in TIBCO Rendezvous
Concepts.
schedulerWeight Weight represents the ability of this member to fulfill the role of
scheduler, relative to other members with the same name. Cooperating
members use relative scheduler weight values to elect one member as the
scheduler; members with higher scheduler weight take precedence.
When omitted, the default value is 1.
Acceptable values range from 0 to 65535. Zero is a special value,
indicating that the member can never be the scheduler. For more
information, see Rank and Weight on page 204 in TIBCO Rendezvous
Concepts.

308
(Sheet 3 of 3)
schedulerHeartbeat The scheduler sends heartbeat messages at this interval (in seconds).
All TibrvCmQueueTransport objects with the same name must specify
the same value for this parameter. The value must be strictly positive. To
When omitted, the default value is 1.0.
schedulerActivation When the heartbeat signal from the scheduler has been silent for this
interval (in seconds), the cooperating member with the greatest
scheduler weight takes its place as the new scheduler.
All TibrvCmQueueTransport objects with the same name must specify
the same value for this parameter. The value must be strictly positive. To
When omitted, the default value is 3.5.
See Also TibrvCmQueueTransport.destroy() on page 309

Distributed Queue, page 181, in TIBCO Rendezvous Concepts

|
TibrvCmQueueTransport.destroy() 309
TibrvCmQueueTransport.destroy()
Method
Purpose Destroy a distributed queue member object.
Remarks Destroying a TibrvCmQueueTransport object removes the program from the

distributed queue group.
See Also TibrvCmQueueTransport() on page 306

310
TibrvCmQueueTransport.getCompleteTime()
Method
Declaration double getCompleteTime()
Purpose Extract the worker complete time limit of a distributed queue member.
See Also Distributed Queue, page 181, in TIBCO Rendezvous Concepts

TibrvCmQueueTransport.setCompleteTime() on page 314

TibrvCmQueueTransport.getUnassignedMessageCount() 311
|
TibrvCmQueueTransport.getUnassignedMessageCount()
Function
Declaration int getUnassignedMessageCount()

Purpose Extract the number of unassigned task messages from a distributed queue
transport.
Remarks An unassigned task message is a message received by the scheduler, but not yet
assigned to any worker in the distributed queue.
This call produces a valid count only within a scheduler process. Within a worker
process, this call always produces zero.

312
TibrvCmQueueTransport.getWorkerWeight()
Method
Declaration int getWorkerWeight()
Purpose Extract the worker weight of a distributed queue member.

TibrvCmQueueTransport.setWorkerWeight() on page 316

|
TibrvCmQueueTransport.getWorkerTasks() 313
TibrvCmQueueTransport.getWorkerTasks()
Method
Declaration int getWorkerTasks()
Purpose Extract the worker task capacity of a distributed queue member.

TibrvCmQueueTransport.setWorkerTasks() on page 317

314
TibrvCmQueueTransport.setCompleteTime()
Method
Declaration void setCompleteTime(

double completeTime)
Purpose Set the worker complete time limit of a distributed queue member.
Remarks If the complete time is non-zero, the scheduler waits for a worker member to
complete an assigned task. If the complete time elapses before the scheduler
receives completion from the worker member, the scheduler reassigns the task to
another worker member.
Zero is a special value, which specifies no limit on the completion time—that is,
the scheduler does not set a timer, and does not reassign tasks when task
completion is lacking. All members implicitly begin with a default complete time
value of zero; programs can change this parameter using this method.
completeTime Use this complete time (in seconds). The time must be
non-negative.

TibrvCmQueueTransport.getCompleteTime() on page 310

|
TibrvCmQueueTransport.setTaskBacklogLimit...() 315
TibrvCmQueueTransport.setTaskBacklogLimit...()
Method
Declaration void setTaskBacklogLimitInBytes(

int byteLimit)
void setTaskBacklogLimitInMessages(
int msgLimit)
Purpose Set the scheduler task queue limits of a distributed queue transport.
Remarks The scheduler stores tasks in a queue. These properties limit the maximum size of
that queue—by number of bytes or number of messages (or both). When no value
is set for these properties, the default is no limit.
When the task messages in the queue exceed either of these limits, Rendezvous
software deletes new inbound task messages.
Programs may call each of these methods at most once. The calls must occur
before the transport assumes the scheduler role; after a transport acts as a
scheduler, these values are fixed, and subsequent attempts to change them throw
an exception with status code TibrvStatus.NOT_PERMITTED.
byteLimit Use this size limit (in bytes).
Zero is a special value, indicating no size limit.
msgLimit Use this message limit (number of messages).

Zero is a special value, indicating no limit on the number of
messages.

316
TibrvCmQueueTransport.setWorkerWeight()
Method
Declaration void setWorkerWeight(

int workerWeight)
Purpose Set the worker weight of a distributed queue member.
Remarks Relative worker weights assist the scheduler in assigning tasks. When the
scheduler receives a task, it assigns the task to the available worker with the
greatest worker weight.
The default worker weight is 1; programs can set this parameter at creation using
TibrvCmQueueTransport(), or change it dynamically using this method.
workerWeight Use this worker weight.

TibrvCmQueueTransport.getWorkerWeight() on page 312

|
TibrvCmQueueTransport.setWorkerTasks() 317
TibrvCmQueueTransport.setWorkerTasks()
Method
Declaration void setWorkerTasks(

int workerTasks)
Purpose Set the worker task capacity of a distributed queue member.
Remarks Task capacity is the maximum number of tasks that a worker can accept. When
the number of accepted tasks reaches this maximum, the worker cannot accept
additional tasks until it completes one or more of them.
When the scheduler receives a task, it assigns the task to the worker with the
greatest worker weight—unless the pending tasks assigned to that worker exceed
its task capacity. When the preferred worker has too many tasks, the scheduler
assigns the new inbound task to the worker with the next greatest worker weight.
The default worker task capacity is 1.
Tuning task capacity to compensate for communication time lag is more

complicated than it might seem. Before setting this value to anything other than 1,
see Task Capacity on page 186 in TIBCO Rendezvous Concepts.
workerTasks Use this task capacity. Value must be greater than zero.

TibrvCmQueueTransport.getWorkerTasks() on page 313

318

| 319
Chapter 11 Exceptions and Errors
Topics
• TibrvException, page 320

• TibrvStatus, page 322
• TibrvErrorCallback, page 327

320
| Chapter 11 Exceptions and Errors
TibrvException
Class
Declaration class com.tibco.tibrv.TibrvException

extends java.lang.Exception
Purpose Rendezvous software throws exceptions of this class.
Remarks Rendezvous software also throws exceptions defined as part of the Java language.
Field Description
error An error or status code, indicating the reason for the
exception; see TibrvStatus on page 322.
internal In some cases this field contains a Java exception, which can
yield additional information. When no further information is
available, this field is null.

TibrvException.printStackTrace() Print stack trace of this exception, and of the 321
internal exception (if it is set).
Inherited Methods
java.lang.Throwable.fillInStackTrace
java.lang.Throwable.getLocalizedMessage
java.lang.Throwable.getMessage
java.lang.Throwable.printStackTrace (override)
java.lang.Throwable.toString (override)
See Also TibrvStatus on page 322

|
TibrvException.printStackTrace() 321
TibrvException.printStackTrace()
Method
Declaration void printStackTrace()
void printStackTrace(java.io.PrintWriter s)
void printStackTrace(java.io.PrintStream s)
Purpose Print stack trace of this exception, and of the internal exception (if it is set).
Overrides java.lang.Throwable.printStackTrace
s Print the stack trace to this object.
When absent, print to the standard error stream.

322
TibrvStatus
Class
Declaration class com.tibco.tibrv.TibrvStatus
Purpose Define status codes.
(Sheet 1 of 5)
Status Description
TibrvStatus.INIT_FAILURE Cannot create the network transport.
TibrvStatus.INVALID_TRANSPORT The transport has been destroyed, or is otherwise

unusable.
TibrvStatus.INVALID_ARG An argument is invalid. Check arguments other than

messages, subject names, transports, events, queues
and queue groups (which have separate status codes).
TibrvStatus.NOT_INITIALIZED The method cannot run because the Rendezvous

environment is not initialized (open).
TibrvStatus.ARG_CONFLICT Two arguments that require a specific relation are in

conflict. For example, the upper end of a numeric
range is less than the lower end.
TibrvStatus.SERVICE_NOT_FOUND Transport creation failed; cannot match the service

name using getservbyname().
TibrvStatus.NETWORK_NOT_FOUND Transport creation failed; cannot match the network

name using getnetbyname().
TibrvStatus.DAEMON_NOT_FOUND Transport creation failed; cannot match the daemon

port number.
TibrvStatus.NO_MEMORY The method could not allocate dynamic storage.
TibrvStatus.INVALID_SUBJECT The method received a subject name with incorrect

syntax.
TibrvStatus.DAEMON_NOT_CONNECTED The Rendezvous daemon process (rvd) exited, or was

never started. This status indicates that the program
cannot start the daemon and connect to it.

|
TibrvStatus 323
(Sheet 2 of 5)
Status Description
TibrvStatus.VERSION_MISMATCH The library, header files and Rendezvous daemon are
incompatible.
TibrvStatus.SUBJECT_COLLISION It is illegal to create two certified worker events on the

same CM transport with overlapping subjects.
TibrvStatus.TIBRV_VC_NOT_CONNECTED A virtual circuit terminal was once complete, but is

now irreparably broken.
TibrvStatus.NOT_PERMITTED 1. The program attempted an illegal operation.

2. Cannot create ledger file.
TibrvStatus.INVALID_NAME The field name is too long; see Field Name Length on
page 56.
TibrvStatus.INVALID_TYPE 1. The field type is not registered.

2. Cannot update field to a type that differs from the
existing field’s type.
TibrvStatus.INVALID_SIZE The explicit size in the field does not match its explicit
type.
TibrvStatus.INVALID_COUNT The explicit field count does not match its explicit
type.
TibrvStatus.INVALID_DATA The program attempted to add data to a message field,

but the datatype is not supported.
TibrvStatus.NOT_FOUND Could not find the specified field in the message.
TibrvStatus.ID_IN_USE Cannot add this field because its identifier is already

present in the message; identifiers must be unique.
TibrvStatus.ID_CONFLICT After field search by identifier fails, search by name

succeeds, but the actual identifier in the field is
non-null (so it does not match the identifier
supplied).
TibrvStatus.CONVERSION_FAILED Found the specified field, but could not convert it to

the desired datatype.

324
(Sheet 3 of 5)
Status Description
TibrvStatus.RESERVED_HANDLER The datatype handler number is reserved for
Rendezvous internal datatype handlers.
TibrvStatus.ENCODER_FAILED The program’s datatype encoder failed.
TibrvStatus.DECODER_FAILED The program’s datatype decoder failed.
TibrvStatus.INVALID_MSG The method received a message argument that is not a

well-formed message.
TibrvStatus.INVALID_FIELD The program supplied an invalid field as an argument.
TibrvStatus.INVALID_INSTANCE The program supplied zero as the field instance

number (the first instance is number 1).
TibrvStatus.CORRUPT_MSG The method detected a corrupt message argument.
TibrvStatus.TIMEOUT A timed dispatch call returned without dispatching an

event.
A send request call returned without receiving a reply
message.
A virtual circuit terminal is not yet ready for use.
TibrvStatus.INTR Interrupted operation.
TibrvStatus.INVALID_DISPATCHABLE The method received an event queue or queue group

that has been destroyed, or is otherwise unusable.
TibrvStatus.INVALID_DISPATCHER The dispatcher thread is invalid or has been

destroyed.
TibrvStatus.INVALID_EVENT The method received an event that has been

destroyed, or is otherwise unusable.
TibrvStatus.INVALID_CALLBACK The method received NULL instead of a callback

method.
TibrvStatus.INVALID_QUEUE The method received a queue that has been destroyed,

or is otherwise unusable.
TibrvStatus.INVALID_QUEUE_GROUP The method received a queue group that has been

destroyed, or is otherwise unusable.

|
TibrvStatus 325
(Sheet 4 of 5)
Status Description
TibrvStatus.INVALID_TIME_INTERVAL The method received a negative timer interval.
TibrvStatus.SOCKET_LIMIT The operation failed because of an operating system

socket limitation.
TibrvStatus.OS_ERROR Tibrv.open() encountered an operating system error.
TibrvStatus.EOF End of file.
TibrvStatus.INVALID_FILE 1. A certificate file or a ledger file is not recognizable

as such.
2. TibrvSdContext.setUserCertWithKey() or
TibrvSdContext.setUserCertWithKeyBin() could
not complete a certificate file operation; this status
code can indicate either disk I/O failure, or invalid
certificate data, or an incorrect password.
TibrvStatus.FILE_NOT_FOUND Rendezvous software could not find the specified file.
TibrvStatus.IO_FAILED Cannot write to ledger file.
TibrvStatus.NOT_FILE_OWNER The program cannot open the specified file because

another program owns it.
For example, ledger files are associated with
correspondent names.
Java-Specific Status Codes
TibrvStatus.ERROR Default error when the error cannot be specified more

precisely.
TibrvStatus.LIBRARY_NOT_FOUND The JNI library is not present.
TibrvStatus.LIBRARY_NOT_LOADED SecurityException while opening Rendezvous

machinery; the JNI library is required, but not
properly loaded.
TibrvStatus.WRONG_JAVA_ARCHIVE Attempted to open the native (JNI) implementation,

but failed; opened the Java implementation instead.
TibrvStatus.AGENT_NOT_FOUND The transport cannot find the specified rva.

326
(Sheet 5 of 5)
Status Description
TibrvStatus.AGENT_ERROR Invalid response from rva.
TibrvStatus.AGENT_DISCONNECTED The transport has lost its connection to rva. Check the
physical network connection. Check that rva is still
running.
TibrvStatus.REQUEST_FAILED rva could not fulfill a request from the program.
TibrvStatus.INVALID_ENCODING TibrvMsg.setStringEncoding() received an invalid

encoding name.
See Also TibrvException on page 320

|
TibrvErrorCallback 327
TibrvErrorCallback
Interface
Declaration interface com.tibco.tibrv.TibrvErrorCallback
Purpose Process asynchronous errors.
Remarks Programs can implement this interface (optional) to process asynchronous errors.

TibrvErrorCallback.onError() Process asynchronous errors. 328
See Also Tibrv.getErrorCallback() on page 28

Tibrv.setErrorCallback() on page 35

328
TibrvErrorCallback.onError()
Method
Declaration void onError(

java.lang.Object tibrvObject,
int errorCode,
java.lang.String message,
java.lang.Throwable internal)
Purpose Process asynchronous errors.
Remarks Rendezvous software calls this method in two asynchronous error situations:
• The connection to the Rendezvous agent has broken.
In this situation, the tibrvObject parameter receives the broken
TibrvRvaTransport object. All listener objects associated with the broken
transport are invalid.
• A subscription (listener) request failed.
In this situation, the tibrvObject parameter receives the TibrvListener
object representing the failed subscription. This situation is rare.
Programs need not respond the these errors. Programs that do respond to these
errors usually inform the user of the problem.
tibrvObject This parameter receives the object that is the locus of the
error—either a TibrvRvaTransport, or a TibrvListener.
errorCode This parameter receives a status code indicating the error. See
TibrvStatus on page 322.
message This parameter receives a printable string describing the error.

In some cases, this message yields more information than the
error code alone.
internal In some cases this parameter receives a Java exception, which

can yield additional information about the cause of the error.
When no further information is available, this parameter
receives null.

| 329
Appendix A Custom Datatypes
Programs can define custom datatypes by implementing interfaces that encode

and decode the data. Decoder methods of TibrvMsg decode data from
Rendezvous wire format representation into Java objects (for example, while
extracting data from a message field). Encoder methods of TibrvMsg encode data
into Rendezvous wire format representation from Java objects (for example, when
sending a message).
This chapter describes these interfaces, and the methods that bind them to
TibrvMsg.
Topics
• TibrvMsg methods:
— TibrvMsg.getDecoder(), page 330
— TibrvMsg.getEncoder(), page 331
— TibrvMsg.setHandlers(), page 332
• TibrvMsgDecoder, page 333
• TibrvMsgEncoder, page 335

330
| Appendix A Custom Datatypes
TibrvMsg.getDecoder()
Method
Declaration static TibrvMsgDecoder getDecoder(

short userType)
Purpose Extract the decoder interface for a custom datatype.
Remarks If no decoder is registered for the datatype, return null.
userType This type designator must be in the inclusive range
[TibrvMsg.USER_FIRST,TibrvMsg.USER_LAST].
See Also TibrvMsg.setHandlers() on page 332

TibrvMsgDecoder on page 333

|
TibrvMsg.getEncoder() 331
TibrvMsg.getEncoder()
Method
Declaration static TibrvMsgEncoder getEncoder(

short userType)
Purpose Extract the encoder interface for a custom datatype.
Remarks If no encoder is registered for the datatype, return null.
userType This type designator must be in the inclusive range
[TibrvMsg.USER_FIRST, TibrvMsg.USER_LAST].
See Also TibrvMsg.setHandlers() on page 332

TibrvMsgEncoder on page 335

332
TibrvMsg.setHandlers()
Method
Declaration static void setHandlers(

short userType,
TibrvMsgEncoder encoder,
TibrvMsgDecoder decoder)
Purpose Define a custom datatype by registering its encoder and decoder interfaces.
Remarks The encoder and decoder must implement inverse operators. That is, when the
encoder encodes a Java object as a byte array, and the decoder must decode the
byte array to an identical Java object. Conversely, when the decoder decodes the
byte array to a Java object, the encoder must encode the Java object as an identical
byte array.
This method sets (or replaces) both interfaces. Supplying null for either the
encoder or the decoder, removes that interface. Supplying null for both interfaces
disables the custom type (by removing both interfaces).
userType Define a custom datatype with this numeric designator.
This type designator must be in the inclusive range
[TibrvMsg.USER_FIRST,TibrvMsg.USER_LAST].
encoder Register this encoder for the type.
decoder Register this decoder for the type.
See Also TibrvMsgDecoder on page 333


|
TibrvMsgDecoder 333
TibrvMsgDecoder
Interface
Declaration interface com.tibco.tibrv.TibrvMsgDecoder
Purpose Decode custom datatypes from wire format into Java objects.
Remarks To define this interface, programs must implement its method.

TibrvMsgDecoder.decode() Decode data (of a custom datatype) from wire format 334
into a Java object.
See Also TibrvMsg.setHandlers() on page 332.


334
TibrvMsgDecoder.decode()
Method
Declaration java.lang.Object decode(

short type,
byte[] bytes)
Purpose Decode data (of a custom datatype) from wire format into a Java object.
Remarks When this method successfully decodes the data, it must return the decoding as a
Java object. When this method cannot decode the data, it must return null.
type Decode this custom datatype.
bytes Decode the data contained in this byte array.

This argument cannot be null. However, it can be a byte array
with length zero.
See Also TibrvMsgEncoder.encode() on page 337

|
TibrvMsgEncoder 335
TibrvMsgEncoder
Interface
Declaration interface com.tibco.tibrv.TibrvMsgEncoder
Purpose Encode Java objects as wire format custom datatypes.
Remarks To define this interface, programs must implement both of its methods.

TibrvMsgEncoder.canEncode() Test whether this encoder can encode the data as a 336
particular wire format custom datatype.
TibrvMsgEncoder.encode() Encode a Java object as a wire format custom 337

datatype.
See Also TibrvMsg.setHandlers() on page 332.

TibrvMsgDecoder on page 333

336
TibrvMsgEncoder.canEncode()
Method
Declaration boolean canEncode(

short type,
Purpose Test whether this encoder can encode the data as a particular wire format custom
datatype.
Remarks Before calling TibrvMsgEncoder.encode(), TibrvMsg first checks its

applicability by calling this method. Whenever this method indicates that
encoding is viable, TibrvMsgEncoder.encode() must correctly encode the object.
This method must return true if the encoder can encode the data into the
specified custom datatype; otherwise it must return false.
type Test viability of encoding the data as an instance of this custom
datatype.
data Test viability of encoding this data.
See Also TibrvMsgEncoder.encode() on page 337

|
TibrvMsgEncoder.encode() 337
TibrvMsgEncoder.encode()
Method
Declaration byte[] encode(

short type,
Purpose Encode a Java object as a wire format custom datatype.
Remarks Before calling this method, TibrvMsg first checks its applicability by calling
TibrvMsgEncoder.canEncode(). Whenever TibrvMsgEncoder.canEncode()
indicates that encoding is viable, this method must correctly encode the object.
When this method successfully encodes the data, it must return the encoding as a
byte array; the byte array value can have length zero. When this method fails, it
must return null.
Methods that call TibrvMsgEncoder.encode() incorporate its byte array value
directly into a TibrvMsg object.
type Encode the data as an instance of this custom datatype.
data Encode this data.
See Also TibrvMsgDecoder.decode() on page 334

TibrvMsgEncoder.canEncode() on page 336

338

|
TibrvMsgEncoder.encode() 339

340

| 341
Index
A callback method
asynchronous error 330
accept, virtual circuit create 210 fault tolerance 237
activate, fault tolerance 220 fault tolerance monitor 247
activation interval 226 inbound message 125
active goal, fault tolerance 227 review ledger 292
add timer 133
datatype conversion during 53 canEncode() 338
scalar 54 certificate
add() 51, 160 set daemon certificate 37
addField() 56 set user certificate 39, 40
addListener() 265 certified delivery 249
address, IP 99 add
advisory message, see TIBCO Rendezvous Concepts listener 265
agent 6 allow listener 266
allow listener 266 confirm 254
applet, remote 13 connect to relay agent 267
archive files 20 destroy
asynchronous error 35 transport 269
callback method 330 disallow listener 270
disconnect from relay agent 271
expire messages 272
get message parameter
B sequence number 296
time limit 298
backward compatibility. See, release 5. get sender name 295
batch mode 206 get transport parameter
bytes, get field as 63 correspondent name 275
ledger name 274
relay agent 276
request old 277
C sync ledger 278
time limit 273
C library files 21 transport 279
is explicit confirm 255
label information, inbound message 125
ledger review 283
listener 250
create 252

342
| Index
destroy 253 create
message methods 294 certified delivery listener 252
remove certified delivery transport 261
listener 280 date 95
send state 282 dispatcher thread 172
review ledger 283 distributed queue member 306
send 284 event queue 141
reply 285 event queue group 159
request 286 fault tolerance monitor 241
send state, remove 282 inbox name 178
set explicit confirm 256 IP address 100
set time limit IP Port 105
of message 299 listener 121
of transport, default 288 message 50
sync ledger 290 message field 89
transport 257 rva transport 190
create 261 rvd transport 200
destroy 269 embed license 202
character encoding 3 timer 129
get 71 XML data 109
set 79 createAcceptVc() 210
checklist, programmer’s 17 createConnectVc() 211
close() 26 createInbox() 178
closure data, get from event 115 custom datatypes 331
CM queue. See distributed queue customer support xix
com.tibco.tibrv, package 18
compatibility. See, release 5.
complete time, distributed queue
get 310 D
set 314
confirm 254 daemon 6
is explicit 255 daemon TCP socket 200
set explicit 256 datatype
confirmMsg() 254 conversion
connect subject, get 213 Java to wire format 53
connect, virtual circuit create 211 wire format to Java 60
connectToRelayAgent() 267 custom 331
contains(), queue 161 name 72
conversion matrix datatype, Rendezvous 48
Java to wire format 53 date 92
wire format to Java 60 create 95
convert to string deactivate, fault tolerance 220
message 80 decode() 336
message field 91
correspondent, get name 275

|
Index 343
decoder E
get 332
interface 335 elements(), queues in a queue group 164
default queue 138 embedded license 202
isDefault() 150 empty array 52
defaultQueue() 27 encode() 339
delay, reconnect, rva 194, 197 encoder
description 181, 185 get 333
destroy() interface 337
certified delivery listener 253 encoding, character 3
certified delivery transport 269 get 71
distributed queue transport 309 set 79
event 114 environment
event queue 142 isValid() 31
fault tolerance member 225 TibrvSdContext class 36
fault tolerance monitor 243 environment variables 21
queue group 162 environment, Tibrv 23
transport 179 error callback
destroyEx() get 28
certified delivery transport 269 interface 329
disallowListener() 270 set 35
discard amount, get 145 errors 319
disconnectFromRelayAgent() 271 event
dispatch() class 112
queue 143 closure data, get 115
queue group 163 destroy 114
queue or queue group 135 get count from a queue 144
dispatch, timed 156, 169 get queue 116
dispatcher thread 170 poll 136
create 172 timed dispatch 137
interrupt 170 validity 117
distributed queue 301 event dispatch 135
destroy 309 event queue 156
get complete time 310 class 138
get worker task capacity 313 create 141
get worker weight 312 destroy 142
member, create 306 dispatch 143
set complete time 314 get
set scheduler task queue limits 315 discard amount 145
set worker task capacity 317 limit policy 146
set worker weight 316 max events 147
transport 302 name 148

344
| Index
priority 149 file
in a group, test 161 jar 20
is default 150 JNI library 21
is valid 151 ledger 262
limit policy constants 138 file.encoding property 3
poll 152 file.encoding, system property 3
set firewall 13
limit policy 154
name 153
priority 155
timed dispatch 156 G
event queue group 157
exceptions 319 get
expire messages, certified delivery 272 byte size of message 64
expireMessages() 272 description of transport 181
version 29
get (field) 57
by index 66
F datatype conversion during 60
field instance 67
fault tolerance 217 scalar 61
command constants 219 get unassigned task count 311
member 219 get() 57
callback 237 getActivationInterval() 226
destroy 225 getActiveGoal() 227
monitor 239 getAddr() 101
callback 247 getAsBytes()
create 241 IP address 102
destroy 243 IP port 107
field message field 63
add 51, 56 getAsString(), IP address 103
scalar 54 getBytes(), XML data 110
class 87 getByteSize() 64
get 57, 65 getClosure() 115
scalar 61 getCompleteTime() 310
name and identifier 44 getConnectSubject() 213
remove 73 getCount() 144
remove instance 75 getCount(), queue group 165
update 81 getDaemon() 203
scalar 84 getDecoder() 332
update from field 86 getDefaultTimeLimit() 273
field search algorithm getDescription() 181
get 57 getDiscardAmount() 145
remove 73 getEncoder() 333
update 82 getErrorCallback() 28

|
Index 345
getField() 65 getUnassignedMessageCount() 311

getFieldByIndex() 66 getVersion() 29
getFieldInstance() 67 getWeight() 233
getGroupName() getWorkerTasks() 313
fault tolerance member 228 getWorkerWeight() 312
fault tolerance monitor 244 group name
getHeartbeatInterval() 229 fault tolerance 228
getHostName(), rva transport 193 fault tolerance monitor 244
getHttpReconnectDelay(), rva transport 194 group, queue 157
getInterval() 130
getLedgerName() 274
getLimitPolicy() 146
getMaxEvents() 147 H
getName()
certified delivery transport 275 handler, set datatype 334
event queue 148 heartbeat interval 229
getNetwork() 204 host name, rva transport 193
getNumFields() 68 HTTP tunneling 14
getPort() reconnect delay 197
IP port 106 rva transport 196
rva transport 195
getPreparationInterval() 230
getPriority() 149
getQueue() I
event 116
fault tolerance event 231 identifier, field 44
getRelayAgent() 276 implementation
getReplySubject() 69 close environment 26
getRequestOld() 277 is native 30
getSender() 295 JNI and Java 2
getSendSubject() 70 open environment 32
getSequence() 296 inbox, create name 178
getService() 205 index, get field by 66
getStringEncoding() 71 instance (field)
getSubject(), listener 122 get 67
getSyncLedger() 278 remove 75
getTimeLimit() 298 internal machinery 26
getTimeNanoseconds() 96 start (open) 32
getTimeSeconds() 97 stop (close) 26
getTransport() internet web site 13
certified delivery transport 279 interrupt 5
fault tolerance member 232 dispatcher thread 170
fault tolerance monitor 245 interaction with dispatch calls 143
listener 123
getTypeName() 72

346
| Index
interval limit policy
activation, fault tolerance 226 constants 138
heartbeat, fault tolerance 229 get 146
preparation, fault tolerance 230 set 154
timer 130 listener 118
reset 131 certified delivery 250
intranet 16 destroy 253
intra-process transport 34, 186 create 121
IP address 99 create certified delivery 252
IP port 104 get subject 122
isDefault(), queue 150 get transport 123
isExplicitConfirm() 255 locale 3
isHttpTunneling() 196 lost interval 242
isNativeImpl() 30
isValid() 31
event 117
event queue 151 M
fault tolerance member 234
queue group 166 member, fault tolerance 219
transport 180 callback 237
message 46
add field 51, 56
scalar 54
J callback method 125
certified delivery 294
jar file 20 create 50
Java implementation 2 field (as a class) 87
JNI implementation 2 get field 57, 65
JNI library files 21 scalar 61
remove field 73
reply subject 69, 77
reset 76
L send 182
send subject 70, 78
Latin-1 3, 79 size 64
ledger update 81, 86
file 263 scalar 84
name, get 274 monitor, fault tolerance 239
review 283 callback 247
sync 278, 290
library files 21
licensed transport 202

|
Index 347
N port
IP 104
name rva transport 195
certified delivery 295 preparation interval 230
certified delivery transport 263 prepare to activate, fault tolerance 219
get name 275 pre-register certified delivery listener 265
datatype name 72 printStackTrace() 321
event queue 148, 153 priority, of event queue 149
fault tolerance group 228 set 155
fault tolerance monitor 244 process transport class 186
native implementation, test 30 processTransport() 34
native library files 21
nested message, get 58
network interface 200
network transport Q
object 187
set batch mode 206 queue
number of fields in a message 68 add to group 160
create 141
default 27
destroy 142
O dispatch 143
fault tolerance event 231
old messages, request certified delivery 277 get
onError() 330 discard amount 145
onFtAction() 237 event count 144
onFtMonitor() 247 limit policy 146
onLedgerMsg() 292 max events 147
onMsg() 125 name 148
onTimer() 133 priority 149
open() 32 get queue from event 116
isDefault() 150
isValid() 151
poll 152
P set
limit policy 154
package 18 name 153
PEM 39 priority 155
PKCS #12 40 timed dispatch 156
poll()
event queue 152
queue group 167
queue or queue group 136

348
| Index
queue group 157 resetInterval(), timer 131
add queue 160 reviewLedger() 283
contains a queue 161 callback method 292
create 159 rva and rvd 6
destroy 162 rva transport
dispatch 163 class 188
elements 164 create 190
get count of queues 165 get host name 193
is valid 166 get port 195
poll 167 get reconnect delay 194
remove queue 168 network overview 11
timed dispatch 169 set reconnect delay 197
rvd transport
class 198
create 200
R embed license 202
get daemon (TCP socket) 203
raw storage device, as ledger file 263 get network interface 204
reconnect delay, rva transport 194, 197 get service 205
reference count 26, 32 network overview 9
relay agent
connect to 267
disconnect from 271
get from certified delivery transport 276 S
release 5, interaction
fields with same name 67 scalar
sequence numbers, certified delivery 296 add field 54
release number, get 29 get field 61
remote applet 13 update 84
remove(), queue from group 168 secure daemon
removeField(), from message 73 set daemon certificate 37
removeFieldInstance(), from message 75 set user certificate 39, 40
removeListener(), certified delivery 280 set user name 41
removeSendState(), certified delivery 282 SecurityException, cannot access file.encoding
reply property 3
send 183 send 182
send certified 285 certified reply 285
reply subject certified request 286
get 69 reply 183
set 77 request 184
request send state, remove 282
send 184 send subject
send certified 286 get 70
request old, certified delivery 277 set 78
reset(), message 76

|
Index 349
send() 182 subject

certified delivery 284 of a listener 122
sender name, certified delivery 295 reply 69, 77
sendReply() 183 send 70, 78
certified delivery 285 support, contacting xix
sendRequest() 184 sync ledger, certified delivery 290
certified delivery 286 get 278
sequence number, certified delivery 296
release 5, interaction 296
service, UDP or PGM 200
setBatchMode() 206 T
setCompleteTime() 314
setDaemonCert() 37 task capacity of distributed queue 313, 317
setDefaultTimeLimit(), certified delivery 288 TCP port
setDescription() 185 rva transport 195
setErrorCallback() 35 rvd transport, daemon parameter 200
setExplicitConfirm() 256 technical support xix
setHandlers() 334 Thread.interrupt() 143
setHttpReconnectDelay(), rva transport 197 Tibrv 24
setLimitPolicy() 154 Tibrv.close() 26
setName(), event queue 153 Tibrv.defaultQueue() 27
setPriority(), event queue 155 Tibrv.getErrorCallback() 28
setPublisherInactivityDiscardInterval() 289 Tibrv.getVersion() 29
setReplySubject() 77 Tibrv.isNativeImpl() 30
setSendSubject() 78 Tibrv.isValid() 31
setStringEncoding() 79 Tibrv.open() 32
setTaskBacklogLimit...() 315 Tibrv.processTransport() 34
setTime() 98 Tibrv.setErrorCallback() 35
setTimeLimit() 299 TibrvCmListener 250
setUserCertWithKey() 39 TibrvCmListener() 252
setUserCertWithKeyBin() 40 TibrvCmListener.confirmMsg() 254
setUserNameWithPassword() 41 TibrvCmListener.destroy() 253
setWeight(), fault tolerance member 235 TibrvCmListener.isExplicitConfirm() 255
setWorkerTasks() 317 TibrvCmListener.setExplicitConfirm() 256
setWorkerWeight() 316 TibrvCmMsg 294
shared library files 21 TibrvCmMsg.getSender() 295
size TibrvCmMsg.getSequence() 296
message 64 TibrvCmMsg.getTimeLimit() 298
stack trace 321 TibrvCmMsg.setTimeLimit() 299
status codes 322 TibrvCmQueueTransport 302
string and character encoding 3 setTaskBacklogLimit...() 315
string encoding TibrvCmQueueTransport() 306
get 71 TibrvCmQueueTransport.destroy() 309
set 79 TibrvCmQueueTransport.getCompleteTime() 310
string, convert message to 80 TibrvCmQueueTransport.getUnassignedMessageCou

350
| Index
nt() 311 TibrvDispatcher() 172
TibrvCmQueueTransport.getWorkerTasks() 313 TibrvErrorCallback, interface 329
TibrvCmQueueTransport.getWorkerWeight() 312 TibrvErrorCallback.onError() 330
TibrvCmQueueTransport.setCompleteTime() 314 TibrvEvent 112
TibrvCmQueueTransport.setWorkerTasks() 317 TibrvEvent.destroy() 114
TibrvCmQueueTransport.setWorkerWeight() 316 TibrvEvent.getClosure() 115
TibrvCmReviewCallback, interface 291 TibrvEvent.getQueue() 116
TibrvCmReviewCallback.onLedgerMsg() 292 TibrvEvent.isValid() 117
TibrvCmTransport 257 TibrvException 320
TibrvCmTransport() 261 TibrvException.printStackTrace() 321
TibrvCmTransport.addListener() 265 TibrvFtMember 219
TibrvCmTransport.allowListener() 266 TibrvFtMember.destroy() 225
TibrvCmTransport.connectToRelayAgent() 267 TibrvFtMember.getActivationInterval() 226
TibrvCmTransport.destroy() 269 TibrvFtMember.getActiveGoal() 227
TibrvCmTransport.destroyEx() 269 TibrvFtMember.getGroupName() 228
TibrvCmTransport.disallowListener() 270 TibrvFtMember.getHeartbeatInterval() 229
TibrvCmTransport.disconnectFromRelayAgent 271 TibrvFtMember.getPreparationInterval() 230
TibrvCmTransport.expireMessages() 272 TibrvFtMember.getQueue() 231
TibrvCmTransport.getDefaultTimeLimit() 273 TibrvFtMember.getTransport() 232
TibrvCmTransport.getLedgerName() 274 TibrvFtMember.getWeight() 233
TibrvCmTransport.getName() 275 TibrvFtMember.isValid() 234
TibrvCmTransport.getRelayAgent() 276 TibrvFtMember.setWeight() 235
TibrvCmTransport.getRequestOld() 277 TibrvFtMemberCallback, interface 236
TibrvCmTransport.getSyncLedger() 278 TibrvFtMemberCallback.onFtAction() 237
TibrvCmTransport.getTransport() 279 TibrvFtMonitor 239
TibrvCmTransport.removeListener() 280 TibrvFtMonitor() 241
TibrvCmTransport.removeSendState() 282 TibrvFtMonitor.destroy() 243
TibrvCmTransport.reviewLedger() 283 TibrvFtMonitor.getGroupName() 244
TibrvCmTransport.send() 284 TibrvFtMonitor.getTransport() 245
TibrvCmTransport.sendReply() 285 TibrvFtMonitorCallback, interface 246
TibrvCmTransport.sendRequest() 286 TibrvFtMonitorCallback.onFtMonitor() 247
TibrvCmTransport.setDefaultTimeLimit() 288 TibrvIPAddr 99
TibrvCmTransport.setPublisherInactivityDiscardInter TibrvIPAddr() 100
val() 289 TibrvIPAddr.getAddr() 101
TibrvCmTransport.syncLedger() 290 TibrvIPAddr.getAsBytes() 102
TibrvDate 92 TibrvIPAddr.getAsString() 103
TibrvDate() 95 TibrvIPPort 104
TibrvDate.getTimeNanoseconds() 96 TibrvIPPort() 105
TibrvDate.getTimeSeconds() 97 TibrvIPPort.getAsBytes() 107
TibrvDate.setTime() 98 TibrvIPPort.getPort() 106
TibrvDispatchable, interface 134 TibrvListener 118
TibrvDispatchable.dispatch() 135 TibrvListener() 121
TibrvDispatchable.poll() 136 TibrvListener.getSubject() 122
TibrvDispatchable.timedDispatch() 137 TibrvListener.getTransport() 123
TibrvDispatcher 170 TibrvMsg 46

|
Index 351
TibrvMsg() 50 TibrvQueue.getMaxEvents() 147

TibrvMsg.add() 51 TibrvQueue.getName() 148
TibrvMsg.addField() 56 TibrvQueue.getPriority() 149
TibrvMsg.get() 57 TibrvQueue.isDefault() 150
TibrvMsg.getAsBytes() 63 TibrvQueue.isValid() 151
TibrvMsg.getByteSize() 64 TibrvQueue.poll() 152
TibrvMsg.getDecoder() 332 TibrvQueue.setLimitPolicy() 154
TibrvMsg.getEncoder() 333 TibrvQueue.setName() 153
TibrvMsg.getField() 65 TibrvQueue.setPriority 155
TibrvMsg.getFieldByIndex() 66 TibrvQueue.timedDispatch() 156
TibrvMsg.getFieldInstance() 67 TibrvQueueGroup 157
TibrvMsg.getNumFields() 68 TibrvQueueGroup() 159
TibrvMsg.getReplySubject() 69 TibrvQueueGroup.add() 160
TibrvMsg.getSendSubject() 70 TibrvQueueGroup.contains() 161
TibrvMsg.getStringEncoding() 71 TibrvQueueGroup.destroy() 162
TibrvMsg.getTypeName() 72 TibrvQueueGroup.dispatch() 163
TibrvMsg.removeField() 73 TibrvQueueGroup.elements() 164
TibrvMsg.removeFieldInstance() 75 TibrvQueueGroup.getCount() 165
TibrvMsg.reset() 76 TibrvQueueGroup.isValid() 166
TibrvMsg.setHandlers() 334 TibrvQueueGroup.poll() 167
TibrvMsg.setReplySubject() 77 TibrvQueueGroup.remove() 168
TibrvMsg.setSendSubject() 78 TibrvQueueGroup.timedDispatch() 169
TibrvMsg.setStringEncoding() 79 TibrvRvaTransport 188
TibrvMsg.toString() 80 TibrvRvaTransport() 190
TibrvMsg.update() 81 TibrvRvaTransport.getHostName() 193
TibrvMsg.updateField() 86 TibrvRvaTransport.getHttpReconnectDelay() 194
TibrvMsgCallback, interface 124 TibrvRvaTransport.getPort() 195
TibrvMsgCallback.onMsg() 125 TibrvRvaTransport.isHttpTunneling() 196
TibrvMsgDecoder, interface 335 TibrvRvaTransport.setHttpReconnectDelay() 197
TibrvMsgDecoder.decode() 336 TibrvRvdTransport 198
TibrvMsgEncoder, interface 337 setBatchMode() 206
TibrvMsgEncoder.canEncode() 338 TibrvRvdTransport() 200
TibrvMsgEncoder.encode() 339 TibrvRvdTransport.getDaemon() 203
TibrvMsgField 87 TibrvRvdTransport.getNetwork() 204
TibrvMsgField() 89 TibrvRvdTransport.getService() 205
TibrvMsgField.toString() 91 TibrvSdContext 36
TibrvNetTransport 187 TibrvSdContext.setDaemonCert() 37
TibrvProcessTransport 186 TibrvSdContext.setUserCertWithKey() 39
TibrvQueue 138 TibrvSdContext.setUserCertWithKeyBin() 40
TibrvQueue() 141 TibrvSdContext.setUserNameWithPassword() 41
TibrvQueue.destroy() 142 TibrvStatus, interface 322
TibrvQueue.dispatch() 143 TibrvTimer 126
TibrvQueue.getCount() 144 TibrvTimer() 129
TibrvQueue.getDiscardAmount() 145 TibrvTimer.getInterval() 130
TibrvQueue.getLimitPolicy() 146 TibrvTimer.resetInterval() 131

352
| Index
TibrvTimerCallback, interface 132 get 181
TibrvTimerCallback.onTimer() 133 set 185
TibrvTransport 176 destroy 179
TibrvTransport.createInbox() 178 certified delivery 269
TibrvTransport.destroy() 179 distributed queue 309
TibrvTransport.getDescription() 181 distributed queue 302
TibrvTransport.isValid() 180 fault tolerance member 232
TibrvTransport.send() 182 get from certified delivery transport 279
TibrvTransport.sendReply() 183 get from listener 123
TibrvTransport.sendRequest() 184 intra-process 34, 186
TibrvTransport.setDescription() 185 is valid 180
TibrvVcTransport 208 network 187
TibrvVcTransport.createAcceptVc() 210 rva 188
TibrvVcTransport.createConnectVc() 211 create 190
TibrvVcTransport.getConnectSubject() 213 rvd 198
TibrvVcTransport.waitForVcConnection() 214 create 200
TibrvXml 108 embed license 202
TibrvXml() 109 send 182
TibrvXml.getBytes() 110 reply 183
time limit, certified delivery request 184
get 298 virtual circuit 208
get default 273 create accept 210
set 299 create connect 211
set default 288 wait for connection 214
time object 92 tunneling, HTTP 196
timedDispatch() 156 type name 72
queue group 169
queue or queue group 137
timer
callback method 133 U
create 129
event object 126 unassigned tasks 311
get interval 130 unicode 3
reset interval 131 update() 81
toString() update, scalar 84
message 80 updateField() 86
message field 91 user name and password, set 41
translation, character encoding 3
transport
batch mode, set 206
certified delivery 257
create 261
class 176
create inbox name 178
description

|
Index 353
V
valid
event 117
event queue 151
fault tolerance member 234
queue group 166
Tibrv environment 31
transport 180
version number, get 29
virtual circuit
create accept 210
create connect 211
get connect subject 213
transport class 208
wait for connection 214
W
wait, for virtual circuit connection 214
waitForVcConnection() 214
web server 13
weight, fault tolerance
get 233
set 235
withdraw from fault tolerance group 225
worker weight, distributed queue
get 312
set 316
X
XML data 108
get byte array 110

354
| Index

Tibco Rendezvous 8.1 Java Reference

Uploaded by

Copyright:

Available Formats

Tibco Rendezvous 8.1 Java Reference

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Tibco Rendezvous 8.1 Java Reference

Uploaded by

Copyright:

Available Formats

TIBCO Rendezvous®

Chapter 2 Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

TIBCO Rendezvous Java Reference

Chapter 3 Rendezvous Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

TIBCO Rendezvous Java Reference

Chapter 5 Events and Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

Chapter 6 Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Chapter 7 Virtual Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Chapter 8 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

TIBCO Rendezvous Java Reference

Chapter 9 Certified Message Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

TIBCO Rendezvous Java Reference

Chapter 10 Distributed Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Chapter 11 Exceptions and Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Appendix A Custom Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

Figure 1 Java Programs with rvd Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

• Manual Organization, page xvi

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

This section lists documentation resources you may find useful.

TIBCO Product Documentation

TIBCO Rendezvous Java Reference

• TIBCO Rendezvous Administration

TIBCO Rendezvous Java Reference

How to Contact TIBCO Customer Support

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

Rendezvous Java language interface offers several implementations. Table 1

Native (JNI) Native (JNI)

Primary Independent application Independent application Downloadable browser

Scope of Maximal coverage of C functionality. Covers core functionality

Timer Supports fine-resolution timers (within operating Timer granularity is

TIBCO Rendezvous Java Reference

Strings and Character Encodings

Rendezvous software uses strings in several roles:

Some browsers (for example, Microsoft Internet Explorer) do not permit

TIBCO Rendezvous Java Reference

See Also TibrvMsg.getStringEncoding() on page 71

TIBCO Rendezvous Java Reference

Interrupting Event Dispatch Threads

The Java method Thread.interrupt() is ineffective when all of these conditions

TIBCO Rendezvous Java Reference

Rendezvous Daemon and Agent

Java Applications and Applets

Security versus Efficiency

TIBCO Rendezvous Java Reference

Starting rvd Automatically

TIBCO Rendezvous Java Reference

TIBCO Rendezvous Java Reference

Network Overview—rvd Transports

Figure 1 on page 10 shows programs that communicate using rvd transports.