Tib Ems Users Guide - Free Download PDF Ebook

TIBCO Enterprise Message Service™ User’s GuideSoftware Release 4.4 November 2006 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE TIBCO Enterprise Message Service User’s Guide). 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, Information Bus, The Power of Now, TIBCO ActiveEnterprise, TIBCO Adapter, TIBCO Hawk, TIBCO Rendezvous, TIBCO Enterprise, TIBCO Enterprise Message Service, and the TIBCO logo are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, J2EE, JMS 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. PLEASE 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 © 2001–2006 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information |v Contents Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv TIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv Third Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii Chapter 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 JMS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 JMS Message Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Point-to-Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Publish and Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 EMS Destination Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 TIBCO Rendezvous Java Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Administering the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 User and Group Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Using TIBCO Hawk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Integrating With Third-Party Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Transaction Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 TIBCO Enterprise Message Service User’s Guide vi | Contents Chapter 2 Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 EMS Extensions to JMS Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 JMS Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS Message Header Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EMS Message Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS Message Bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maximum Message Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Delivery Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PERSISTENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NON_PERSISTENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RELIABLE_DELIVERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How EMS Manages Persistent Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Persistent Messages Sent to Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Persistent Messages Published to Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Persistent Messages and Failsafe Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character Encoding in Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 17 19 22 23 24 24 25 26 27 27 28 29 30 31 31 33 Message Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Message Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 About Message Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Setting Message Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Message Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NO_ACKNOWLEDGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXPLICIT_CLIENT_ACKNOWLEDGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 37 38 38 Synchronous and Asynchronous Message Consumption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Chapter 3 Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Destination Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destination Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Static Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Temporary Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destination Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 44 44 44 45 45 TIBCO Enterprise Message Service User’s Guide Contents vii | Destination Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . failsafe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . maxbytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . maxmsgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . overflowPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sender_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sender_name_enforced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . flowControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . maxRedelivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . exclusive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . prefetch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 47 48 49 50 50 52 52 53 53 54 54 55 56 56 57 60 Creating and Modifying Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Creating Secure Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards * and > . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards in Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards in Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards and Dynamically Created Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 63 64 64 65 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Inheritance of Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Inheritance of Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Destination Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access Control and Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flow Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enforcing Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routes and Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destination Bridges and Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flow Control, Threads and Deadlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 69 70 70 71 71 71 72 72 73 TIBCO Enterprise Message Service User’s Guide viii | Contents Chapter 4 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 About the Sample Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Compiling the Sample Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Creating Users with the EMS Administration Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Start the EMS Server and EMS Administration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Create Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Point-to-Point Messaging Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Create a Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Start the Sender and Receiver Clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Publish and Subscribe Messaging Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create a Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Start the Subscriber Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Start the Publisher Client and Send Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create a Secure Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create a Durable Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 82 83 84 85 87 Chapter 5 Running the EMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Starting and Stopping the EMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Starting the EMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Stopping the EMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 emsntsreg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Secure Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destination Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authorization Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Admin Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Communication Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sources of Authentication Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timestamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audit Trace Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 94 94 94 95 95 96 96 96 96 97 How EMS Manages Access to Shared Store Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 TIBCO Enterprise Message Service User’s Guide Contents ix | Chapter 6 Using the EMS Administration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Starting the EMS Administration Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 When You First Start tibemsadmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Command Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 add member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 addprop factory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 addprop queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 addprop route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 addprop topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 autocommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 compact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 create bridge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 create durable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 create factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 create group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 create jndiname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 create queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 create route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 create rvcmlistener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 create topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 create user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 delete all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 delete bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 delete connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 delete durable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 delete factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 delete group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 delete jndiname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 delete message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 delete queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 delete route. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 delete rvcmlistener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 delete topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 delete user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 grant queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 grant topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 grant admin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 TIBCO Enterprise Message Service User’s Guide x | Contents info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . purge all queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . purge all topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . purge durable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . purge queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . purge topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . remove member. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeprop factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeprop queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeprop route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . removeprop topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . revoke admin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . revoke queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . revoke topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rotatelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setprop factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setprop queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setprop route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setprop topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show db . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show durable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show durables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show factory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show jndiname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show jndinames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show parents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show rvcmtransportledger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIBCO Enterprise Message Service User’s Guide 118 118 118 118 119 119 119 119 119 119 120 120 120 121 121 122 123 128 128 129 129 129 130 130 131 131 134 137 137 139 139 140 140 140 140 141 141 141 141 141 142 143 144 144 145 . . . . . . Message Tracking Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection and Memory Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Statistic Gathering Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . showacl admin . . . . . . TIBCO SmartSockets Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . time. . . . . . . . . . . . . . . .Contents xi | show rvcmlisteners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transaction rollback. . . . . . . . . . . . . TIBCO Rendezvous Parameters . . . . . . . show topic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tracing and Log File Parameters . updatecrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . showacl topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 tibemsd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LDAP Parameters. . . . . showacl user. . . . . . . . . . . . . . . . . . . . . . . . . . . .conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . whoami . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show users . . . . . . . . . . . . . . . . . . . . . . . . . Detecting Network Connection Failure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storage File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 145 145 146 148 149 150 150 150 150 150 151 151 151 152 152 152 153 153 153 153 153 Chapter 7 Using the Configuration Files . . . . SSL Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . show transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . showacl queue . . . . . . . . . transaction commit . . . . timeout . . . . . . . . . . . show stat. . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Location of Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 167 173 174 176 178 181 182 182 183 186 188 192 198 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . showacl group . . . . . . . . . . 156 Mechanics of Configuration . . . . . . Fault Tolerance Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Detecting Network Connection Failure Parameters—Deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global System Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Administrator Permissions . . . . .2b Interfaces. . . . . . . . . . . Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . durables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 234 235 235 239 240 241 241 When Permissions Are Checked . . . . . . . . . . . . . . . . . . . Protection Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destination-Level Permissions. . . . . . . . . . . . . . .conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of Setting User Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 201 202 202 203 203 205 206 208 212 215 216 Chapter 8 Authentication and Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .conf . . . . .conf . . . . . . . .0. . . . . . . . . . . . . . . . . . 231 Server Control . . . . . . . . . . . . . . . . . . . . . . Configuring an External Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .conf . . . . . . .conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . factories. . . . . . . . . . . . . . . . . . . . . . . . 243 Chapter 9 Developing an EMS Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transports. . . . . . queues. . . . . . . . . . . . . . . . . . . . . . groups. . . . . . . . .conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Destination Control . . . . . . . . . . . . . . . . . . . . . . . . . . . acl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .conf . . . . . . . . . . . . . . . . . . . . . 246 246 247 248 Sample Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Administrator Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xii | Contents Using Other Configuration Files . . . . . . . . Granting and Revoking Administration Permissions . . . . . . . . . . . . .conf . . . . . . .conf . . . . . . . 242 Example of Permission Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 and 1. . . . . .conf . . . . 221 EMS Access Control . . Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Administrative User and Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Summary of JMS 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inheritance of User Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS 1. . . . . . . . . . . . . . . . . . . . . . . . . . Enforcement of Administrator Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 223 224 225 226 228 230 Enabling Access Control . . . . . . . . . . . . . . . . . 245 JMS Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . routes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . bridges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Revoking User Permissions. . . . . . . . . . . . . . . . . . . . . . .2b Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Permissions . . . users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Users and Groups . . . . . . . . . 249 TIBCO Enterprise Message Service User’s Guide . . . tibrvcm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 294 294 297 Chapter 11 Working With TIBCO Rendezvous . . . . . . . . . . Performing Fault-Tolerant Lookups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Creating Connection Factories for Secure Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Factories . 274 Working with Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Timeout and Delay Parameters. . . . . . . . . . . . . . 272 Creating a Message Listener for Asynchronous Message Consumption . . . . . . . . . . . . . . . . . . . . . . . Dynamically Creating Connection Factories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 277 279 280 282 Chapter 10 Using the EMS Implementation of JNDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C# Programmer’s Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Creating and Modifying Administered Objects in EMS . . . . . . . . . . . . . 269 Configuring a Message Producer . . . . . . . 290 Looking up Administered Objects Stored in EMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java Programmer’s Checklist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 250 252 257 258 258 258 260 Connecting to the EMS Server . . . . . . . . . . . . Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Looking up Connection Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecated Configuration Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Transport Definitions. . . . . . . . . . . . . . . . . . . . . . . 263 Creating a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Dynamically Creating Topics and Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending Messages . . . . 270 Creating a Message Consumer . . . . Receiving Messages . . . . . . . . . . .Contents xiii | Programmer Checklists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting and Getting Message Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stopping and Closing a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Looking Up Objects Using Full URL Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Connection Attempts. . . . . . . . . . . . . . . . . . . . . . . . . 267 Creating a Message Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 300 301 301 Configuring Transports for Rendezvous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing Secure Lookups . C Programmer’s Checklist . . . . . . 289 Creating Connection Factories for Fault-Tolerant Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Setting an Exception Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Starting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subscribe Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Export Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv | Contents Topics . . . . . . . Configuration . Transport Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMSExpiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Destination Name—Syntax and Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . Certified Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 335 335 336 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Transports for SmartSockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Types. . . . . . . . . . . . . . . . Certified Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Queues . . . . JMS Property Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMSDestination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Import Only when Subscribers Exist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMSReplyTo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Chapter 12 Working With TIBCO SmartSockets . . . . . . . . Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Import—Start and Stop . . . . . . . . . . . . 306 306 307 307 308 308 308 309 310 310 310 310 311 312 312 312 312 313 313 314 315 317 Pure Java Rendezvous Programs . JMS Header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMSReplyTo. . . . . . . . Import—Start and Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the Servers . . . . . . . . Guaranteed Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Import Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 326 326 327 327 328 332 332 Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Import Only when Subscribers Exist . . . . . 334 Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcard Subscriptions . . . . 354 Enabling Message Tracing on a Message . . . . . . . . . . . . . . . . 347 Log Files and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Statistic Gathering . . . . . . . . . . . . . . Import Destination Names Must be Unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 Monitoring Server Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Digital Certificate File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 337 337 337 338 338 338 339 340 340 340 341 342 344 345 Chapter 13 Monitoring Server Activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Monitor Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 355 356 358 359 360 360 361 363 Chapter 14 Using the SSL Protocol . . . . . . . . . . . . . . . . . . . . . . Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Implications of Monitor Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Private Key Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Enabling Message Tracing for a Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 Digital Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guaranteed Delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overall Server Statistics . . . . . . . . . . . . . 371 Command Line Options . . .Contents xv | Import Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 SSL Support in TIBCO Enterprise Message Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMSReplyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Messages . . . . . . . Destination Names . . . . . . . . . . . . . . . . . . . JMS Property Fields . . . . . . . . 369 Configuring SSL in the Server . . . 368 File Names for Certificates and Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Monitor Topics . . . . . . . . . . . . . . . . . . Export Issues . Working with Server Statistics . . . . . . . . 348 Tracing on the Server . . . . . . . . . . . . 349 Message Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMS Header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 SSL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JMSReplyTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Body . . . . . . . Displaying Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . 348 Configuring the Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guaranteed Delivery. . . . . . . SmartSockets Message Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Eliminating Redundant Paths with a One-Hop Zone . . . . . . . . . . . . . . . . . . . . . . . 381 Third-Party SSL Hardware Accelerators . . . . . . . . 382 Chapter 15 Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Messages Stored in Shared State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Fault-Tolerant Servers . . . . . . . . . . . . . . . . . . . . Zone . . . . . . . . . . . . . . . . . . . . . 403 403 404 405 406 406 407 408 Active and Passive Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi | Contents Configuring SSL in EMS Clients . . . . . . . 378 SSL Authentication Only . . . Authorization and Fault-Tolerant Servers. . . . . . . 397 Setting Reconnection Failure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Chapter 16 Working With Routes . . . . . . . . . . . . . . . . . . . . . . . . . Storage Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overlapping Zones . . . . . 397 Specifying More Than Two URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 Supported Cipher Suites . . . . . . . . . . . . . . . . . . . . 372 Client Digital Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reconnect Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Configuring SSL. . . . . . . . . . . . . . . . . . . . 383 Fault Tolerance Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 Syntax for Cipher Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SSL . . . . . . . . . . . . . . . . . . Storage Parameters . . . . . . . . Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . Global Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unique Routing Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Detection . . . . . . . . . . . . . . . . . . . . . . . . Implementing Shared State . 386 386 386 389 390 391 391 394 394 394 395 395 396 396 Configuring Clients for Fault-Tolerant Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Route . . . . . . . . . . . . . . . . . . . . . . 401 Overview of Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shared State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Heartbeat Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Specifying Cipher Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Redelivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Appendix C Error and Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UNIX Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Routing and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . 431 Appendix B Monitor Messages . . . . . . . . . . . . . . . . . . . 425 Overview of Server Management With TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . 493 TIBCO Enterprise Message Service User’s Guide . . . . . 415 Propagating Registered Interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 Installing the Classes . . . . . . . . . . . . . . . . . . . . 411 Routing and SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Appendix A Using TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Error and Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 Description of Topic Message Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 427 428 429 Method Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Routed Topic Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Contents xvii | Configuring Routes and Zones . . . . 448 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Routed Queues . . . . . . . . . . . . . . . . . . . . . Windows Installation . . . . . 415 Selectors for Routing Topic Messages . . . . . . . . . . . . . . . . . . . . . . . . 410 Routes to Fault-Tolerant Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 Description of Monitor Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii Contents | TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . groups. . . . . . . . . . . . . . . . . . . . . . . . . 404 Routes: Unique Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2b Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Point-to-point messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Persistent Message Delivery . . . . . . . . . . . . . . . . . . . . . 4 Publish and subscribe messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Bridging a topic to multiple destinations . . . . . . . . . . . . . . . . . . . . 387 Routes: bidirectionality and corresponding destinations . . .0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Failed Primary Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Persistent Messages Sent to a Queue. . . . . . . . . . . . . . 300 SmartSockets Transports in the EMS Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 JMS 1. . . . . . . . . . . . . . . 32 Clients sending messages with a specific encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Reliable Message Delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Recovered Server Becomes Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Zones: one-hop . . . . . . . . . 233 JMS 1. . . . . . . . . . . . . . . . . 73 Users. . . . . . . . . . . . . . . . . . . . . 34 Message Delivery and Acknowledgement . . . . . . . . . . . . . . . . . .1 Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Flow Control Deadlock across Two Threads . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Zones: multi-hop . . . . . . . . . . . . . . . . . . . . . . . . . 403 Routes: global destinations . . . . . . . . . . . . 24 Non-Persistent Message Delivery . . . . 36 Bridging a topic to a queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Persistent Messages Published to a Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Clients receiving messages . . . . . . . . . 247 Rendezvous Transports in the EMS Server . . . 326 Primary Server and Backup Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Clients sending UTF-8 encoded messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .| xix Figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Figure 10 Figure 11 Figure 12 Figure 13 Figure 14 Figure 15 Figure 16 Figure 17 Figure 18 Figure 19 Figure 20 Figure 21 Figure 22 Figure 23 Figure 24 Figure 25 Figure 26 Figure 27 Figure 28 Message Delivery. . . and permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Routing: Topic Selectors. . . 408 Routing: Propagating Subscribers. . . . . . . . . . . . 422 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xx | Figures Figure 29 Figure 30 Figure 31 Figure 32 Figure 33 Zones: overlap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Routing: Authorization . . . . . . . example . . 417 Routing: Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Summary of message properties . . 148 Show transactions table information . . . . . . . . . . . . . . . . . . . . . .| xxi Tables Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15 Table 16 Table 17 Table 18 Table 19 Table 20 Table 21 Table 22 Table 23 Table 24 Table 25 Table 26 Table 27 Table 28 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Show topics table information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Fault Tolerance Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Description of output fields . . 90 tibemsadmin Options . . . . . . . . 139 show queue Table Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . 137 show durables Table Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii Summary of administration features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 show routes Table Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 show queues Table Information . . . . . . . . . . . . . . . . 46 Prefetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Detecting Network Connection Failure Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 tibemsd Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Destination properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Set server parameters . . . . . . . . . . . . . 158 Storage File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi Syntax Typographical Conventions. . . . . . . . . . . . . . . 134 Description of output fields . . 9 JMS Message Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 show topic Table Information . . . . . . . . . . 22 Destination Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 JMS Message Types . . . . . . . . . . . . . . . . . 131 show connections: type Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 show durable Table Information . . . . . . . . . . . . . . 158 Connection and Memory Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Global System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxii | Tables Table 29 Table 30 Table 31 Table 32 Table 33 Table 34 Table 35 Table 36 Table 37 Table 38 Table 39 Table 40 Table 41 Table 42 Table 43 Table 44 Table 45 Table 46 Table 47 Table 48 Table 49 Table 50 Table 51 Table 52 Table 53 Table 54 Table 55 Table 56 Table 57 Table 58 Table 59 Table 60 Message Tracking Parameters . . . . . . . 302 Rendezvous: Mapping JMS Header Fields to RV Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Shareable Image Library Files for OpenVMS . . . . . . . . . . . . . . . . . . . . . . . 257 Rendezvous: Transport Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 SmartSockets Mapping Message Properties (Import & Export) . . . . . . . . . . . . . . . 313 Rendezvous Mapping Message Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 SmartSockets: Transport Parameters . . . . . . . . . . . . . . . . . . . . . . . . 162 Statistic Gathering Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 SmartSockets: Mapping Message Types (Export) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 TibrvJMSTransport class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 SmartSockets: Mapping Data Types . . . . . . . . . . . . . . . . . . 240 JMS API object summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Global administrator permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Rendezvous: Mapping Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Queue Permission . . . . . . . . . . . . . . . . . . . . . . . . . 162 SSL Server Parameters . 314 Rendezvous: Mapping Message Types (Import). . . . . . . . . . . . . . . . . . . . . . . 229 Default configuration for popular LDAP servers . . . . . . . . . . . . . . . . . . . . . . . 161 TIBCO Rendezvous Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Static Library Files for Microsoft Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Linker Flags for 32-Bit UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Linker Flags for 64-Bit UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Dynamic Library Files for Microsoft Windows . . . 226 Destination-level administration permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Topic Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Rendezvous: Mapping Message Types (Export). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 LDAP Parameters . . . . . . . . . . . 164 Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Static Library Files for OpenVMS . . . . . . . . . . . . . . . 161 Tracing and Log File Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 EMS Assembly DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 TIBCO SmartSockets Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 TIBCO Enterprise Message Service User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 Message properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 TIBCO Enterprise Message Service classes in TIBCO Hawk . . . . . . . . . . . . 374 Qualifiers for Cipher Suites in Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 OpenSSL Qualifiers for Cipher Suites . . . . 378 Shared Storage Criteria for Fault Tolerance . . . . . . . . . . . .Tables xxiii | Table 61 Table 62 Table 63 Table 64 Table 65 Table 66 Table 67 Table 68 Table 69 Table 70 Table 71 Table 72 Table 73 Table 74 Table 75 Table 76 Table 77 Table 78 Server tracing options . . . . . . . . . . . . . . . . . . . . . 372 ConnectionFactory SSL parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 File types . . . . . . . . . . . 350 Message monitoring qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Event Reason Property Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 TIBCO Hawk MicroAgent Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 SSL JAR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 SSL Parameters for Routes . . . . . . . . . . 437 Event Action Property Values . . 429 TIBCO Hawk method names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 Monitor topics . . . . . . . . . . . 391 Shared State Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 Supported Cipher Suites in Java API . . . . . . . xxiv Tables | TIBCO Enterprise Message Service User’s Guide . page xxvi Typographical Conventions. not all operating system platforms for a specific software version are released at the same time. page xxx TIBCO Enterprise Message Service User’s Guide . This software may be available on multiple operating systems. However. It also integrates with TIBCO Rendezvous and TIBCO SmartSockets message products.txt file for the availability of this software version on a specific operating system platform. Please see the readme. page xxviii How to Contact TIBCO Customer Support.| xxv Preface TIBCO Enterprise Message Service™ software lets application programs send and receive messages according to the Java Message Service (JMS) protocol. Topics • • • Related Documentation. NET API Reference The . TIBCO Enterprise Message Service . TIBCO Enterprise Message Service Java API Reference The Java API reference is available as JavaDoc.NET API reference is available in PDF and HTML format. This document also contains lists of known issues and closed issues for this release. and configuration. TIBCO Enterprise Message Service Release Notes Read the release notes for a list of new and changed features. its features. TIBCO Enterprise Message Service Documentation The following documents form the TIBCO Enterprise Message Service documentation set: • • • TIBCO Enterprise Message Service User’s Guide Read this manual to gain an overall understanding of the product. TIBCO Enterprise Message Service Installation Read the relevant sections of this manual before installing this product. • • • • Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products: • • TIBCO Rendezvous™ software TIBCO SmartSockets™ software TIBCO Enterprise Message Service User’s Guide . TIBCO Enterprise Message Service C & COBOL API Reference The C API reference is available in HTML and PDF formats.xxvi | Preface Related Documentation This section lists documentation resources you may find useful. TIBCO Enterprise Message Service Application Integration Guide This manual presents detailed instructions for integrating TIBCO Enterprise Message Service with third-party products. and you can access the reference only through the HTML documentation interface. available through java.sun.Related Documentation xxvii | Third Party Documentation • • Java™ Message Service specification. TIBCO Enterprise Message Service User’s Guide .com/products/jms/index. Chappell. California. O’Reilly and Associates. 2001.html Java™ Message Service by Richard Monson-Haefel and David A. Sebastopol. For example: Ctrl+C. For example: Esc. to indicate what a user types. italic font Italic font is used in the following ways: • • • To indicate a document title. For example: See TIBCO BusinessWorks Concepts for more details. bold code font Bold code font is used in the following ways: • • • In procedures. filenames.xxviii | Preface Typographical Conventions The following typographical conventions are used in this manual. For example: Use MyCommand to start the TIBCO foo process. In large code samples. For example: MyCommand pathname Key combinations Key name separated by a plus sign indicate keys pressed simultaneously. To introduce new terms For example: A portal page may contain several portlets. code examples. pathnames. TIBCO Enterprise Message Service User’s Guide . To indicate a variable in a command or code syntax that you must replace. Table 1 General Typographical Conventions Convention code font Use Code font identifies commands. For example: Type the username admin. Ctrl+Q. to indicate the parts of the sample that are of particular interest. and output displayed in a command window. In command syntax. to indicate the default value. Key names separated by a comma and space indicate keys pressed one after the other. Portlets are mini-applications that run in a portal. Typographical Conventions xxix | Table 2 Syntax Typographical Conventions Use An optional item in a command or code syntax. which can be either param1 and param2 or param3 and param4: MyCommand {param1 param2} | {param3 param4} In the next example. the command requires two parameters. For example. The first parameter must be param1. Other syntax notations may appear within each logical group. For example. For example. And the last parameter is either param3 or param4. The first parameter can be either param1 or param2 and the second can be either param3 or param4: MyCommand {param1 | param2} {param3 | param4} In the next example. if no parameter is specified. For example: MyCommand [optional_parameter] required_parameter Convention [ ] | A logical ’OR’ that separates multiple items of which only one may be chosen. MyCommand is enabled: MyCommand [enable | disable] { } A logical group of items. you can select only one of the following parameters: MyCommand para1 | param2 | param3 bold code font The default parameter. You can optionally include param2 as the second parameter. the command can accept either two or three parameters. the following command requires two parameters. MyCommand param1 [param2] {param3 | param4} TIBCO Enterprise Message Service User’s Guide . and information about getting started with TIBCO Product Support. If you do not have a username. TIBCO Enterprise Message Service User’s Guide .xxx | Preface How to Contact TIBCO Customer Support For comments or problems with this manual or the software it addresses. • For an overview of TIBCO Support Services.com/services/support • If you already have a valid maintenance or support contract. visit this site: http://www. please contact TIBCO Support Services as follows. visit this site: http://support.com Entry to this site requires a username and password. you can request one.tibco.tibco. page 3 Client APIs. page 11 Routing. page 8 Administration.|1 Chapter 1 Overview This chapter contains a general overview of Java Message Service (JMS) and TIBCO Enterprise Message Service concepts. page 2 JMS Message Models. page 12 Integrating With Third-Party Products. page 12 TIBCO Enterprise Message Service User’s Guide . page 9 Security. page 11 Fault Tolerance. Topics • • • • • • • • JMS Overview. 2 | Chapter 1 Overview JMS Overview Java Message Service 1. For more information on JMS requirements and features. see the following sources: • • Java Message Service specification.4 has passed Sun Microsystem Technology Compatibility Kit (TCK) for Java Message Service 1. The JMS framework (an interface specification. Therefore. and another for raw materials tracking.4 is compliant with the JMS 1. in conjunction with TIBCO and others.1 (JMS 1. such as TIBCO Rendezvous and TIBCO SmartSockets. Sun Microsystems developed this specification. EMS 4.sun. Java Message Service by Richard Monson-Haefel and David A. 2001. California. TIBCO Enterprise Message Service implements JMS and integrates support for connecting other message services. available through http://java. not an implementation) is designed to supply a basis for MOM development. This chapter describes the concepts of JMS and its implementation in TIBCO Enterprise Message Service. TIBCO Enterprise Message Service User’s Guide . you may have several applications: one for customer relations. JMS Compliance TIBCO Enterprise Message Service 4.html.com/products/jms/index. to supply a uniform messaging interface among enterprise applications. Sebastopol.1 (JMS) is a Java framework specification for messaging between applications. one for product inventory. Each application is crucial to the operation of the enterprise. Chappell. but even more crucial is communication between the applications to ensure the smooth flow of business processes. Message-oriented-middleware (MOM) creates a common communication protocol between these applications and allows you to easily integrate new and existing applications in your enterprise computing environment. Using a message service allows you to integrate the applications within an enterprise.1). For example. O’Reilly and Associates.1 specification. Messages are structured data that one application sends to another. Figure 1 illustrates an application producing a message. such as TIBCO Rendezvous™ and TIBCO SmartSockets™. The server also provides enterprise-class functionality such as fault-tolerance. The creator of the message is known as the producer and the receiver of the message is known as the consumer. Figure 1 Message Delivery Message Producer Message TIBCO EMS Server Message Message Consumer EMS Client EMS Client JMS supports two messaging models: • • Point-to-point (queues) Publish and subscribe (topics) TIBCO Enterprise Message Service User’s Guide . The TIBCO EMS server acts as an intermediary for the message and manages its delivery to the correct destination. sending it by way of the server.JMS Message Models 3 | JMS Message Models JMS is based on creation and delivery of messages. and a different application receiving the message. message routing. and communication with other messaging systems. Figure 2 Point-to-point messages TIBCO EMS Server Message Producer Queue Receive Message Acknowledge EMS Clients EMS Client Message Consumers Send Message TIBCO Enterprise Message Service User’s Guide . Regardless of whether the queue is exclusive or not. Non-exclusive queues are useful for balancing the load of incoming messages across multiple receivers. If the queue is not exclusive. Exclusive queues are useful when you want only one application to receive messages for a specific queue. Figure 2 illustrates point-to-point messaging using a non-exclusive queue. Each message consumer receives a message from the queue and acknowledges receipt of the message. and more than one consumer can retrieve messages from the same queue. only one consumer can ever consume each message that is placed on the queue. The message producer sends the message to the queue. The message is taken off the queue so that no other consumer can receive it. More than one producer can send messages to the same queue. The queue can be configured to be exclusive. the message consumer retrieves messages from the queue and sends acknowledgement that the message was received. then all queue messages can only be retrieved by the first consumer specified for the queue. If the queue is exclusive.4 | Chapter 1 Overview Point-to-Point Point-to-point messaging has one producer and one consumer per message. any number of receivers can retrieve messages from the queue. This style of messaging uses a queue to store messages until they are received. if desired. Each message consumer subscribes to a topic. Subscribers subscribe to topics. Figure 3 Publish and subscribe messages TIBCO EMS Server Message Producer Subscribe to Topic Deliver Message Publish Message Message Consumers Topic Acknowledge (if necessary) EMS Clients EMS Client Durable Subscribers for Topics By default. In this model. subscribers only receive messages when they are active. See Creating a Message Consumer on page 272 for details on how to create durable subscribers. or until the storage limit has been reached for the topic. or until the message expiration time for the message has been reached. all messages stored on the server for that topic are published to the durable subscriber. and a message from a single publisher can be received by many subscribers. The EMS APIs allow you to create durable subscribers to ensure that messages are received. similar to how radio or television signals are broadcast and received. producers address messages to a topic. the producer is known as a publisher and the consumer is known as a subscriber. all subscribed consumers receive the message. Many publishers can publish to the same topic. When a message is published to that topic. Figure 3 illustrates publish and subscribe messaging. If messages arrive on the topic when the subscriber is not available. Messages for durable subscriptions are stored on the server as long as durable subscribers exist for the topic. and all messages published to the topic are received by all subscribers to the topic. even if the message consumer is not currently running. TIBCO Enterprise Message Service User’s Guide . This type of message protocol is also known as broadcast messaging because messages are sent over the network and received by all interested subscribers. When an application restarts and recreates a durable subscriber with the same ID.JMS Message Models 5 | Publish and Subscribe In a publish and subscribe message system. the subscriber does not receive those messages. Durable subscribers can receive messages from a durable subscription even if the subscriber was not available when the message was originally delivered. You can exchange messages with other message services. The EMS destination features include: • You can set a secure mode for access control at the queue or topic level. For more information on creating bridges between destinations and situations where this may be useful. This can be useful if your application requires that you send the same message to both a topic and a queue. Only one receiver can receive messages from an exclusive queue. See Destination Control on page 232. you can specify a property on the queue that determines the maximum number of times a message should be redelivered. Topics can either receive or send Rendezvous and TIBCO SmartSockets messages. You can set queues to be exclusive or non-exclusive. This is useful when message producers send messages much faster than message consumers can receive them. See Working With Routes on page 401. see Destination Bridges on page 68. You can specify a redelivery policy for queues. You can trace and log all messages passing through a destination. so that some destinations may require permission and others may not. See trace on page 54. See Working With TIBCO Rendezvous on page 299 and Working With TIBCO SmartSockets on page 325. See exclusive on page 56. You can also create bridges between destinations of the same or different types to create a hybrid messaging model for your application. More than one receiver can receive messages from non-exclusive queues. See flowControl on page 53 and overflowPolicy on page 50. You can control the flow of messages to a destination. See maxRedelivery on page 56. You can route messages sent to destinations to other servers. • • • • • • • • TIBCO Enterprise Message Service User’s Guide . see Flow Control on page 71. You can set threshold limits for the amount of memory used by the EMS server to store messages for a topic or a queue and fine-tune the server’s response to when the threshold is exceeded.6 | Chapter 1 Overview EMS Destination Features TIBCO Enterprise Message Service allows you to configure destinations to enhance the functionality of each messaging model. Queues can receive TIBCO Rendezvous and TIBCO SmartSockets messages. When messages must be redelivered. For more information on flow control. The wildcard destination name is the parent. See prefetch on page 57 for more information. and any names that match the wildcard destination name inherit the properties of the parent. Administrator operations can use wildcards in destination names. You can set the failsafe mode on a topic or queue to direct the server to write persistent messages to disk synchronously to guarantee messages are not lost under any circumstances. See sender_name on page 52 and sender_name_enforced on page 53. you can specify that queue receivers are to only receive one message at a time. • • TIBCO Enterprise Message Service User’s Guide . See failsafe on page 47.EMS Destination Features 7 | • • You can include the user name of the message producer in the message. Alternatively. See Wildcards on page 63. You can specify that a consumer is to receive batches of messages in the background to improve performance. These examples illustrate various features of EMS. TIBCO Enterprise Message Service User’s Guide . The examples are included in the samples subdirectory of the EMS installation directory.com/products/jms/index.sun.8 | Chapter 1 Overview Client APIs Java applications use the javax. for creating the connection to the EMS server. see Pure Java Rendezvous Programs on page 319. you can also view the documentation on these interfaces along with the JMS specification at java. and creating the destination (topic or queue) on which to send or receive messages.jms package to send or receive JMS messages. This is a standard set of interfaces. See the following for more information: • • TIBCO Enterprise Message Service C & COBOL API Reference (online documentation) TIBCO Enterprise Message Service . specified by the JMS specification.html. specifying the type of message to send. For more information about running the examples. You may wish to view these example programs when reading about the corresponding features in this manual. You can find a description of the javax. TIBCO Enterprise Message Service includes parallel APIs for other development environments.NET API Reference Sample Code EMS includes several example programs. TIBCO Rendezvous Java Applications EMS includes a Java class that allows pure Java TIBCO Rendezvous applications to connect directly with the EMS server. Because EMS implements the JMS standard. Getting Started.jms package in TIBCO Enterprise Message Service Java API Reference included in the online documentation. see Chapter 4. on page 75. Administering the Server EMS has several administration features that allow you to monitor and manage the server. on page 347 TIBCO Enterprise Message Service User’s Guide .NET). The administration interfaces allow you to create and manage administered objects such as ConnectionFactories. EMS clients can retrieve references to these administered objects by using Java Naming and Directory Interface (JNDI). The administration APIs are described in the online documentation. on page 221 Chapter 13. Configure log files to provide information about various server activity. Monitoring Server Activity. Using the EMS Administration Tool.Administration 9 | Administration EMS provides mechanisms for administering server operations and creating objects that are managed by the server. Authentication and Permissions. Topics. Creating static administered objects allows clients to use these objects without having to implement the objects within the client. such as ConnectionFactories and Destinations. Using the EMS Administration Tool. Administration functions can be issued either using the command-line administration tool or by creating an application that uses the administration API (either Java or . Table 3 Summary of administration features (Sheet 1 of 2) Feature Configuration files allow you to specify server characteristics. Using the Configuration Files. and Queues. The following table provides a summary of administration features and details where in the documentation you can find more information. on page 101 Chapter 8. You can also specify who can perform administrative activities with administrator permissions. on page 155 Chapter 6. More Information Chapter 7. on page 101. Authentication and permissions can restrict access to the server and to destinations. The command-line administration tool is described in Chapter 6. Administration tool provides a command line interface for managing the server. The EMS server can also use an external system. on page 347 User and Group Management EMS provides facilities for creating and managing users and groups locally for the server. Using TIBCO Hawk.10 | Chapter 1 Overview Table 3 Summary of administration features (Sheet 2 of 2) Feature The server can publish messages when various system events occur. This allows you to create robust monitoring applications that subscribe to these system monitor topics. such as an LDAP server for authenticating users and storing group information. See Chapter 8. Monitoring Server Activity. Monitoring Server Activity. The server can provide various statistics at the desired level of detail. on page 425 for more information. More Information Chapter 13. on page 347 Chapter 13. Using TIBCO Hawk You can use TIBCO Hawk for monitoring and managing the EMS server. TIBCO Enterprise Message Service User’s Guide . See Appendix A. on page 221 for more information about configuring EMS to work with external systems for user and group management. Authentication and Permissions. on page 365 for more information about SSL support in EMS. you must explicitly configure SSL within EMS. on page 383 for more information about the fault-tolerance features of EMS. with the primary server accepting client connections and performing the work of handling messages. EMS supports SSL between the following components: • • • • • between an EMS client and the EMS server between the administration tool and the EMS server between the administration APIs and the EMS server between routed servers between fault-tolerant servers See Chapter 14. such as credit card numbers. Secure Sockets Layer (SSL) is a protocol for transmitting encrypted data over the Internet or an internal network. Fault Tolerance You can configure EMS servers as primary and backup servers to provide fault tolerance for your environment. Using the SSL Protocol. SSL works by using public and private keys to encrypt data that is transferred over the SSL connection. TIBCO Enterprise Message Service User’s Guide . and many Web sites and Java applications use the protocol to obtain confidential user information. Fault Tolerance. See Chapter 15. and the secondary server acting as a backup in case of failure. the backup server assumes operation and becomes the primary active server. The primary and backup servers act as a pair.Security 11 | Security For communication security between servers and clients. and between servers and other servers. Most web browsers support SSL. When the active server fails. see TIBCO Enterprise Message Service Application Integration Guide. Integrating With Third-Party Products EMS allows you to work with third-party naming/directory service products or with third-party application servers. EMS implements all interfaces necessary to be JTA compliant. Transaction Support EMS can integrate with Java Transaction API (JTA) compliant transaction managers.12 | Chapter 1 Overview Routing EMS provides the ability for servers to route messages between each other. provided there are no cycles (that is. EMS stores and forwards messages in most situations to provide operation when a route is not connected. Working With Routes. on page 401 for more information about the routing features of EMS. The EMS C API is compliant with the X/Open XA specification. TIBCO Enterprise Message Service User’s Guide . the message can not be routed to any server it has already visited). Topic messages can be routed across multiple hops. See Chapter 16. Queue messages can travel at most one hop to any other server from the server that owns the queue. | 13 TIBCO Enterprise Message Service User’s Guide . 14 | Chapter 1 Overview TIBCO Enterprise Message Service User’s Guide . page 17 Message Priority. page 24 How EMS Manages Persistent Messages. page 30 Message Compression. page 35 Message Acknowledgement. page 36 Synchronous and Asynchronous Message Consumption. page 16 JMS Message Structure. page 23 Message Delivery Modes. page 38 TIBCO Enterprise Message Service User’s Guide . page 27 Character Encoding in Messages.| 15 Chapter 2 Messages This chapter provides an overview of EMS messages. Topics • • • • • • • • • EMS Extensions to JMS Messages. In addition to the EMS message properties. See Message Acknowledgement on page 36. you can specify a NO_ACKNOWLEDGE mode so that consumers do not need to acknowledge receipt of messages. EMS also provides an EXPLICIT_CLIENT_ACKNOWLEDGE and EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE mode that restricts the acknowledgement to single messages. PERSISTENT and NON_PERSISTENT. EMS extends the MapMessage and StreamMessage body types. These extensions allow EMS to exchange messages with TIBCO Rendezvous and ActiveEnterprise formats that have certain features not available within the JMS MapMessage and StreamMessage. For consumer sessions. EMS provides a select number of extensions to JMS. However. instead of a flat message. — You can use arrays as well as primitive types for the values. See EMS Message Properties on page 19 for the list of message properties that are specific to EMS. see Message Body on page 315. See RELIABLE_DELIVERY on page 26. they are extensions and therefore not compliant with JMS specifications. These extensions add considerable flexibility to the MapMessage and body types. TIBCO Enterprise Message Service adds these two extensions to the MapMessage and StreamMessage body types: — You can insert another MapMessage or StreamMessage instance as a submessage into a MapMessage or StreamMessage. StreamMessage • • For more information on compatibility with Rendezvous messages. EMS also includes a RELIABLE_DELIVERY mode that eliminates some of the overhead associated with the other delivery modes. generating a series of nested messages.16 | Chapter 2 Messages EMS Extensions to JMS Messages The JMS specification details a standard format for the header and body of a message. Extended messages are tagged as extensions with the vendor property tag JMS_TIBCO_MSG_EXT. if desired. TIBCO Enterprise Message Service User’s Guide . Properties are provider-specific and can include information on specific implementations or enhancements to JMS functionality. These are: • The JMS standard specifies two delivery modes for messages. Table 4 describes the message header fields. If set to 0. if your EMS server or client application are based on a version of EMS prior to 4. message does not expire. RELIABLE_DELIVERY or publish method or publish method JMSDeliveryMode send JMSExpiration send or publish method Length of time that message will live before expiration. clients automatically synchronize their clocks with the server. Synchronize clocks to a tolerance that is a very small fraction of the smallest message expiration time.JMS Message Structure 17 | JMS Message Structure JMS messages have a standard structure. This structure includes the following sections: • • • Header (required) Properties (optional) Body (optional) JMS Message Header Fields The header contains ten predefined fields that contain values used to route and deliver messages. if your client application uses non-zero values for message expiration. as described in RELIABLE_DELIVERY on page 26. Table 4 JMS Message Headers (Sheet 1 of 2) Header Field JMSDestination Set by send Comments Destination to which message is sent Persistent or non-persistent message. EMS extends the delivery mode to include a mode. you must ensure that clocks are synchronized among all the host computers that send and receive messages. However. The time-to-live is specified in milliseconds. In EMS version 4. The default is persistent.4.4 and later. TIBCO Enterprise Message Service User’s Guide . or publish method JMSMessageID send or publish method or publish method Value uniquely identifies each message sent by a provider. Entering a value in this field is optional. This ID can be used to link messages. such as linking a response message to a request message. it is possible that the message was delivered to the client earlier. Entering a value for this field is optional. but not acknowledged at that time. message type identifier If this field is set. A destination to which a message reply should be sent. Timestamp of time when message was handed off to a provider to be sent. to define message priority as normal or expedited. between 0 and 9. See Message Priority on page 23 for more information. Larger numbers represent higher priority. JMSTimestamp send JMSCorrelationID message client JMSReplyTo message client message client JMS provider JMSType JMSRedelivered TIBCO Enterprise Message Service User’s Guide . Message may actually be sent later than this timestamp.18 | Chapter 2 Messages Table 4 JMS Message Headers (Sheet 2 of 2) Header Field JMSPriority Set by send Comments Uses a numerical ranking. The EMS properties are summarized in Table 5 and described in more detail in subsequent sections in this chapter. The properties area is optional. Client programs may use the TIBCO-specific properties to access EMS features. Table 5 Summary of message properties (Sheet 1 of 2) Property JMS_TIBCO_CM_PUBLISHER Description Correspondent name of an RVCM sender for messages imported from TIBCO Rendezvous. applications. if possible. The JMS specification describes the JMS message properties. TIBCO-specific property names begin with JMS_TIBCO. This section describes the message properties that are specific to EMS. and administrators on JMS systems can add optional properties. Extends the functionality of the MapMessage and StreamMessage body types to include submessages or arrays. Sequence number of an RVCM message imported from TIBCO Rendezvous. vendors. More Info 314 JMS_TIBCO_CM_SEQUENCE 314 JMS_TIBCO_COMPRESS 35 JMS_TIBCO_DISABLE_SENDER 21 JMS_TIBCO_IMPORTED 314 340 JMS_TIBCO_MSG_EXT 16 314 340 TIBCO Enterprise Message Service User’s Guide . Allows messages to be compressed for more efficient storage. Specifies that the user name of the message sender should not be included in the message. and can be left empty. but not for communicating application-specific information among client programs.JMS Message Structure 19 | EMS Message Properties In the properties area. Set by the server when the message has been imported from Rendezvous or SmartSockets. Contains the user name of the message sender. it sets this property to the SmartSockets sender header field (in SmartSockets syntax).20 | Chapter 2 Messages Table 5 Summary of message properties (Sheet 2 of 2) Property JMS_TIBCO_MSG_TRACE Description Specifies the message should be traced from producer to consumer. More Info 353 JMS_TIBCO_PRESERVE_UNDELIVERED 21 JMS_TIBCO_SENDER 21 340 JMS_TIBCO_SS_SENDER TIBCO Enterprise Message Service User’s Guide . Specifies the message is to be placed on the undelivered message queue if the message must be removed. When the EMS server imports a message from TIBCO SmartSockets. the application that sends or publishes the message must set the boolean JMS_TIBCO_PRESERVE_UNDELIVERED property to true before sending or publishing the message. If JMS_TIBCO_PRESERVE_UNDELIVERED is set to true. and the message producer’s user name will not be included in the message. Including the Message Sender Within a message. If JMS_TIBCO_PRESERVE_UNDELIVERED is set to false. the server checks the message’s JMS_TIBCO_PRESERVE_UNDELIVERED property. EMS can supply the user name given by the message producer when a connection is created. $sys. Message producers can specify the JMS_TIBCO_DISABLE_SENDER boolean property for a particular message. using the purge queue command described under Command Listing on page 106. message producers can specify that the user name is to be left out of the message.JMS Message Structure 21 | Undelivered Message Queue If a message expires or has exceeded the value specified by the maxRedelivery property on a queue. The sender_name and sender_name_enforced properties on the destination determine whether the message producer’s user name is included in the sent message. When the sender_name property is enabled and the sender_name_enforced property is not enabled on a destination. If you wish to remove messages from the undelivered message queue without receiving them. You should create a queue receiver to receive and handle messages as they arrive on the undelivered message queue. You can only set the undelivered property on individual messages.undelivered queue with the administration tool. However. if the sender_name_enforced property is enabled. When a user name is included in a message. the server moves the message to the undelivered message queue.undelivered. you can purge the $sys. You can also remove messages using the administrative API included with TIBCO Enterprise Message Service. TIBCO Enterprise Message Service User’s Guide . This undelivered message queue is a system queue that is always present and cannot be deleted. To make use of the undelivered message queue. the message will be deleted by the server. the JMS_TIBCO_DISABLE_SENDER property is ignored and the user name is always included in the message. a message consumer can retrieve that user name by getting the string message property named JMS_TIBCO_SENDER. there is no way to set the undelivered message queue as an option at the per-topic or per-queue level. This is useful for simple event notification.String When EMS is exchanging messages with Rendezvous or ActiveEnterprise. The bytes are not typed. you can generate a series of nested StreamMessages.String. or no message body at all. as described in EMS Extensions to JMS Messages on page 16. ObjectMessage A serializable object constructed in the Java programming language. java. The entries can be accessed sequentially by enumeration or directly by name. as described in EMS Extensions to JMS Messages on page 16. The order of entries is undefined. A set of name/value pairs. you can generate a series of nested MapMessages. and must be read sequentially. The names are objects. A java. When EMS is exchanging messages with Rendezvous or ActiveEnterprise. and the values are Java primitive value types or their wrappers.lang.lang.22 | Chapter 2 Messages JMS Message Bodies A JMS message has one of several types of message bodies. BytesMessage StreamMessage A stream of uninterrupted bytes. A stream of primitive values in the Java programming language. The types of messages are described in Table 6. TIBCO Enterprise Message Service User’s Guide . they are not assigned to a primitive data type. that is. Table 6 JMS Message Types Message Type Message TextMessage MapMessage Contents of Message Body This message type has no body. Each set of values belongs to a primitive data type. then it delivers messages with higher priority before those with lower priority. However. You can set default message priority for the Message Producer. as a value in the range [0.Message Priority 23 | Maximum Message Size EMS supports messages up to a maximum size of 512MB. chapter 3. since messages approaching this maximum size will strain the performance limits of most current hardware and operating system platforms. The default priority can be overridden by the client when sending a message. When the EMS server has several messages ready to deliver to a consumer client. as described in Configuring a Message Producer on page 270. In contrast. when the server rarely has only one message at a time to deliver to a consumer. as described in Sending Messages on page 280.9]. See Also JMS Specification. and must select among them. we recommend that application programs use smaller messages.4. and other vendors might not implement it). However.10 TIBCO Enterprise Message Service User’s Guide . priority ordering applies only when the server has a backlog of deliverable messages for a consumer. Message Priority The JMS specification includes a JMSPriority message header field in which senders can set the priority of a message. EMS does support message priority (though it is optional. then the priority ordering feature will not be apparent. the producer must wait for the server to reply with a confirmation. You can set the default delivery mode for the Message Producer. as described in Configuring a Message Producer on page 270. PERSISTENT As shown in Figure 4. EMS extends these delivery modes to include a RELIABLE_DELIVERY mode. JMS supports PERSISTENT and NON_PERSISTENT delivery modes for both topic and queue. This delivery mode ensures delivery of messages to the destination on the server in almost all circumstances.24 | Chapter 2 Messages Message Delivery Modes The JMSDeliveryMode message header field defines the delivery mode for the message. This default delivery mode can be overridden by the client when sending a message. as described in Sending Messages on page 280. However. when a producer sends a PERSISTENT message. The message is persisted on disk by the server. Figure 4 Persistent Message Delivery Message Message Producer TIBCO EMS Server Confirmation TIBCO Enterprise Message Service User’s Guide . the cost is that this delivery mode incurs two-way network traffic for each message or committed transaction of a group of messages. Regardless of whether authorization is enabled or disabled.Message Delivery Modes 25 | NON_PERSISTENT Sending a NON_PERSISTENT message omits the overhead of persisting the message on disk to improve performance. the default condition is for the producer to wait for the server to reply with a confirmation in the same manner as when using PERSISTENT mode. Figure 5 Non-Persistent Message Delivery Message Message Producer TIBCO EMS Server Depending on npsend_check_mode TIBCO Enterprise Message Service User’s Guide . you can use the npsend_check_mode parameter in the tibemsd. See the description for the npsend_check_mode parameter on page 169 for details. If authorization is enabled on the server. the server does not send a confirmation to the message producer.conf file to specify the conditions under which the server is to send confirmation of NON_PERSISTENT messages to the producer. If authorization is disabled on the server. such as stock price quotations. Reliable mode decreases the volume of message traffic. the message is not sent to any message consumer. Sending a RELIABLE_DELIVERY message omits the server confirmation to improve performance regardless of the authorization setting. unless the connection to the server has been terminated. In some cases a message published in reliable mode may be disqualified and not handled by the server because the destination is not valid or access has been denied. the publishing application will not receive any exceptions.26 | Chapter 2 Messages RELIABLE_DELIVERY EMS extends the JMS delivery modes to include reliable delivery. despite the fact that no consumer received the message. all publish calls will always succeed (not throw an exception) unless the connection to the server has been terminated. Figure 6 Reliable Message Delivery Message Producer Message TIBCO EMS Server When using RELIABLE_DELIVERY mode. In this case. allowing higher message rates. However. the server never sends the producer a receipt confirmation or access denial and the producer does not wait for it. Therefore. which is useful for messages containing time-dependent data. the client application does not receive any response from the server. When you use the reliable delivery mode. TIBCO Enterprise Message Service User’s Guide . Should the server fail before sending persistent messages to subscribers. NON_PERSISTENT Persistent Messages Sent to Queues Persistent messages sent to a queue are always written to disk. and RELIABLE_DELIVERY messages are never written to persistent storage. the server can be restarted and the persistent messages will be sent to the subscribers when they reconnect to the server. PERSISTENT messages are written to persistent storage when they are received by the EMS server.How EMS Manages Persistent Messages 27 | How EMS Manages Persistent Messages As described in Message Delivery Modes on page 24. PERSISTENT and NON_PERSISTENT. JMS defines two message delivery modes. and EMS defines a RELIABLE_DELIVERY mode. Figure 7 Persistent Messages Sent to a Queue TIBCO EMS Server Message Producer Queue Send Message Receive Message Message Consumer EMS Client EMS Client Disk TIBCO Enterprise Message Service User’s Guide . . However.and/or. In the absence of a durable subscriber or subscriber with a fault-tolerant connection.. non-durable subscribers that re-connect after a server failure are considered newly created subscribers and are not entitled to receive any messages created prior to the time they are created (that is.. TIBCO Enterprise Message Service User’s Guide . This improves performance by eliminating the unnecessary disk I/O to persist the messages. messages published before the subscriber re-connects are not resent). the server does not needlessly save persistent messages.28 | Chapter 2 Messages Persistent Messages Published to Topics Persistent messages published to a topic are written to disk only if that topic has at least one durable subscriber or one subscriber with a fault-tolerant connection to the EMS server. In this case. Fault Tolerant Consumer EMS Clients This behavior is consistent with the JMS specification because durable subscribers to a topic cause published messages to be saved. Figure 8 Persistent Messages Published to a Topic Other Consumers TIBCO EMS Server Subscribe to Topic Message Producer Publish Message Topic Durable Consumer EMS Client Either type of consumer must subscribe to the topic for messages to be saved to disk Disk .. there are no subscribers that need messages resent in the event of a server failure. Additionally. subscribers to a topic that are connected to a fault-tolerant server need to receive messages from the secondary server after a failover. How EMS Manages Persistent Messages 29 | Persistent Messages and Failsafe Destinations By default, persistent messages received by the EMS server are asynchronously written to disk. This means that, when a producer sends a persistent message, the server does not wait for the write -to-disk operation to complete before returning control to the producer. Should the server fail before completing the write-to-disk operation, the producer has no way of detecting the failure to persist the message and taking corrective action. You can set the failsafe property on a topic or queue to specify that persistent messages for the topic or queue be synchronously written to disk. When failsafe is set, the producer remains blocked until the server has completed the write-to-disk operation. Each EMS server writes persistent messages to a store file. To prevent two servers from using the same store file, each server restricts access to its store file for the duration of the server process. For details on how EMS manages shared store files, see How EMS Manages Access to Shared Store Files on page 98. TIBCO Enterprise Message Service User’s Guide 30 | Chapter 2 Messages Character Encoding in Messages Character encodings are named sets of numeric values for representing characters. For example, ISO 8859-1, also known as Latin-1, is the character encoding containing the letters and symbols used by most Western European languages. If your applications are sending and receiving messages that use only English language characters (that is, the ASCII character set), you do not need alter your programs to handle different character encodings. The EMS server and application APIs automatically handle ASCII characters in messages. Character sets become important when your application is handling messages that use non-ASCII characters (such as Japanese language). Also, clients encode messages by default as UTF-8. Some character encodings use only one byte to represent each character, but UTF-8 can potentially use two bytes to represent the same character. For example, the Latin-1 is a single-byte character encoding. If all strings in your messages contain only characters that appear in the Latin-1 encoding, you can potentially improve performance by specifying Latin-1 as the encoding for strings in the message. EMS clients can specify a variety of common character encodings for strings in messages. The character encoding for a message applies to strings that appear in any of the following places within a message: • • • property names and property values MapMessage field names and values data within the message body The EMS client APIs (Java, .NET and C) include mechanisms for handling strings and specifying the character encoding used for all strings within a message. The following sections describe the implications of string character encoding for EMS clients. Nearly all character sets include unprintable characters. EMS software does not prevent programs from using unprintable characters. However, messages containing unprintable characters (whether in headers or data) can cause unpredictable results if you instruct EMS to print them. For example, if you enable the message tracing feature, EMS prints messages to a trace log file. TIBCO Enterprise Message Service User’s Guide Character Encoding in Messages 31 | Supported Character Encodings Each message contains the name of the character encoding used to encode strings within the message. This character encoding name is one of the canonical names for character encodings contained in the Java specification. You can obtain a list of canonical character encoding names from the following location: http://java.sun.com/j2se/1.4/docs/guide/intl/encoding.doc.html Java and .NET clients use these canonical character encoding names when setting or retrieving the character encoding names. C clients have a list of macros that correspond to these canonical names. See the C API references for a list of supported character encodings in these interfaces. Sending Messages When a client sends a message, the message stores the character encoding name used for strings in that message. Java clients represent strings using Unicode. A message created by a Java client that does not specify an encoding will use UTF-8 as the named encoding within the message. UTF-8 uses up to four bytes to represent each character, so a Java client can improve performance by explicitly using a single-byte character encoding, if possible. Java clients can globally set the encoding to use with the setEncoding method or the client can set the encoding for each message with the setMessageEncoding method. For more information about these methods, see the TIBCO Enterprise Message Service Java API Reference. Typically, C clients manipulate strings using the character encoding of the machine on which they are running. EMS provides a character encoding library for C clients to determine the encoding in messages and convert strings to and from Unicode. C clients should explicitly set the character encoding they are using when they create and send a message. For more information, see TIBCO Enterprise Message Service C & COBOL API Reference. Figure 9 illustrates EMS clients sending messages encoded in UTF-8. Java clients use this encoding by default. C clients must explicitly set this encoding and convert strings from the local encoding to UTF-8 before sending the message. TIBCO Enterprise Message Service User’s Guide 32 | Chapter 2 Messages Figure 9 Clients sending UTF-8 encoded messages Java EMS Client ... javax.jms.MapMessage msg = session.createMapMessage(); ... java.lang.String myName = "François"; java.lang.String myAddr = "555 rue de L'Arbalète"; ... msg.setString("name",myName); msg.setString("address",myAddr); ... C EMS Client ... tibiconv_LocalToUTF8("François", UTF8name, 8); tibiconv_LocalToUTF8("555 rue de L'Arbalète", UTF8addr, 21); ... tibemsMsg_SetEncoding(message, "TIBICONV_UTF8"); ... tibemsMapMsg_SetString(message, "name", UTF8name); tibemsMapMsg_SetString(message, "address", UTF8addr); ... Java clients automatically encode strings as UTF-8. Message Encoding: UTF-8 name XXXXXXX address XXXXXXX ... To create a message with UTF-8 encoding, the C client must use the tibiconv library if the local machine does not use UTF-8 as the local encoding. The C client must also specify the string encoding used in the message with the tibemsMsg_SetEncoding function. Figure 10 illustrates clients explicitly setting the encoding of strings within a message to ISO-8859-1 (Latin-1). The client must set this encoding explicitly for the message, but there is no need to convert the strings — this happens automatically. The C client’s local encoding is Latin-1, so there is no need to convert the strings. However, the C client must specify the encoding of the message before sending. TIBCO Enterprise Message Service User’s Guide Character Encoding in Messages 33 | Figure 10 Clients sending messages with a specific encoding Java EMS Client ... javax.jms.MapMessage msg = session.createMapMessage(); setMessageEncoding(msg ,"ISO-8859-1 ") ... java.lang.String myName = "François"; java.lang.String myAddr = "555 rue de L'Arbalète"; ... msg.setString("name",myName); msg.setString("address",myAddr); ... C EMS Client ... name = "François"; addr = "555 rue de L'Arbalète"; ... tibemsMsg_SetEncoding(message, "TIBICONV_LATIN_1"); ... tibemsMapMsg_SetString(message, "name", name); tibemsMapMsg_SetString(message, "address", addr); ... Java clients can set the character encoding globally or for each message. Message Encoding: ISO-8859-1 name address ... XXXXXXX XXXXXXX If the C client wishes to send the message with locally-encoded strings, the client should set the encoding of the message to the name of the local encoding. This allows any client receiving the message to properly read the encoded strings in the message. Receiving Messages Each message stores the name of the character encoding the sender used. A message receiver can use this information to decode the strings in the message, if necessary. Java automatically performs any necessary conversion and represents strings in Unicode. Java clients do not need to explicitly perform any operations to display strings stored in a message. C clients must compare the encoding used for the message with the encoding of the local machine. If the encodings match, the C client can display the string without conversion. If the encodings do not match, the C client must use the tibconv library functions to convert the string to the local encoding before the string can be displayed. TIBCO Enterprise Message Service User’s Guide 34 | Chapter 2 Messages Figure 11 illustrates EMS clients receiving messages. The Java client can receive the message and display the strings without any additional conversion. The C client must determine the encoding in the message, compare it to the encoding used on the local machine, and then perform conversion, if the encodings do not match. Figure 11 Clients receiving messages Regardless of the message encoding, strings in Java clients are always represented in Unicode. A Java client does not need to manually convert strings to a local encoding when receiving messages. Message Encoding: ISO-8859-1 name XXXXXXX address XXXXXXX ... Java EMS Client ... javax.jms.Message message = subscriber.receive(); ... java.lang.String myName = msg.getString("name"); java.lang.String myAddr = msg.getString("address"); ... System.println(myName + "," + myAddr); ... Message Encoding: UTF-8 name XXXXXXX address XXXXXXX ... C EMS Client ... tibiconv_GetDefaultEncoding( defEncoding); tibjmsMsg_GetEncoding(message, msgEncoding); ... tibjmsMapMsg_GetString(message, "name", name); tibjmsMapMsg_GetString(message, "address", addr); ... C clients must compare the encoding of the message to the local machine's default encoding. If the message's encoding is the same as the local encoding, the client can retrieve strings from the message and display them. If the encodings are different, the client must convert the message strings into the local encoding using functions in tibconv before displaynig the strings. TIBCO Enterprise Message Service User’s Guide Message Compression 35 | Message Compression TIBCO Enterprise Message Service allows a client to compress the body of a message before sending the message to the server. EMS supports message compression/decompression across client types (Java, C and C#). For example, a Java producer may compress a message and a C consumer may decompress the message. Message compression is supported in .NET clients when using the install package for Visual C++ 8 / .NET 2.0. .NET in the Visual C++ 7 / .NET 1.1 package does not support compression. About Message Compression Message compression is especially useful when messages will be stored on the server (persistent queue messages, or topics with durable subscribers). Setting compression ensures that messages will take less memory space in storage. When messages are compressed and then stored, they are handled by the server in the compressed form. Compression assures that the messages will usually consume less space on disk and will be handled faster by the EMS server. The compression option only compresses the body of a message. Headers and properties are never compressed. It is best to use compression when the message bodies will be large and the messages will be stored on a server. When messages will not be stored, compression is not as useful. Compression normally takes time, and therefore the time to send or publish and receive compressed messages is generally longer than the time to send the same messages uncompressed. There is little purpose to message compression for small messages that are not be stored by the server. Setting Message Compression Message compression is specified for individual messages. That is, message compression, if desired, is set at the message level. TIBCO Enterprise Message Service does not define a way to set message compression at the per-topic or per-queue level. To set message compression, the application that sends or publishes the message must access the message properties and set the boolean property JMS_TIBCO_COMPRESS to true before sending or publishing the message. TIBCO Enterprise Message Service User’s Guide 36 | Chapter 2 Messages Compressed messages are handled transparently. The client code only sets the JMS_TIBCO_COMPRESS property. The client code does not need to take any other action. Message Acknowledgement The interface specification for JMS requires that message delivery be guaranteed under many, but not all, circumstances. Figure 12 illustrates the basic structure of message delivery and acknowledgement. Figure 12 Message Delivery and Acknowledgement 1 Message Producer 3 Message TIBCO EMS Server 4 5 Message Acknowledgement Confirmation of acknowledgement Message Consumer 2 Confirmation The following describes the steps in message delivery and acknowledgement: 1. A message is sent from the message producer to the machine on which the EMS server resides. 2. For persistent messages, the EMS server sends a confirmation to the procedure that the message was received. 3. The server sends the message to the consumer. 4. The consumer sends an acknowledgement to the server that the message was received. A session can be configured with a specific acknowledge mode that specifies how the consumer-to-server acknowledgement is handled. These acknowledge modes are described below. 5. In many cases, the server then sends a confirmation of the acknowledgement to the consumer. TIBCO Enterprise Message Service User’s Guide Message Acknowledgement 37 | The JMS specification defines three levels of acknowledgement for non-transacted sessions: • CLIENT_ACKNOWLEDGE specifies that the consumer is to acknowledge all messages that have been delivered so far by the session. When using this mode, it is possible for a consumer to fall behind in its message processing and build up a large number of unacknowledged messages. AUTO_ACKNOWLEDGE specifies that the session is to automatically acknowledge consumer receipt of messages when message processing has finished. DUPS_OK_ACKNOWLEDGE • • specifies that the session is to "lazily" acknowledge the delivery of messages to the consumer. "Lazy" means that the consumer can delay acknowledgement of messages to the server until a convenient time; meanwhile the server might redeliver messages. This mode reduces session overhead. However, should JMS fail, the consumer may receive duplicate messages. EMS extends the JMS acknowledge modes to include: • • • NO_ACKNOWLEDGE EXPLICIT_CLIENT_ACKNOWLEDGE EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE The acknowledgement mode is set when creating a Session, as described in Creating a Session on page 264. NO_ACKNOWLEDGE NO_ACKNOWLEDGE mode suppresses the acknowledgement of received messages. After the server sends a message to the client, all information regarding that message for that consumer is eliminated from the server. Therefore, there is no need for the client application to send an acknowledgement to the server about the received message. Not sending acknowledgements decreases the message traffic and saves time for the receiver, therefore allowing better utilization of system resources. Sessions created in no-acknowledge receipt mode cannot be used to create durable subscribers. Also, queue receivers on a queue that is routed from another server are not permitted to specify NO_ACKNOWLEDGE mode. TIBCO Enterprise Message Service User’s Guide 38 | Chapter 2 Messages EXPLICIT_CLIENT_ACKNOWLEDGE EXPLICIT_CLIENT_ACKNOWLEDGE is like CLIENT_ACKNOWLEDGE except it acknowledges only the individual message, rather than all messages received so far on the session. One example of when EXPLICIT_CLIENT_ACKNOWLEDGE would be used is when receiving messages and putting the information in a database. If the database insert operation is slow, you may want to use multiple application threads all doing simultaneous inserts. As each thread finishes its insert, it can use EXPLICIT_CLIENT_ACKNOWLEDGE to acknowledge only the message that it is currently working on. EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE is like DUPS_OK_ACKNOWLEDGE except it ’lazily" acknowledges only the individual message, rather than all messages received so far on the session. Synchronous and Asynchronous Message Consumption The EMS APIs allow for both synchronous or asynchronous message consumption. For synchronous consumption, the message consumer explicitly invokes a receive call on the topic or queue. When synchronously receiving messages, the consumer remains blocked until a message arrives. See Receiving Messages on page 282 for details. The consumer can receive messages asynchronously by registering a message listener to receive the messages. When a message arrives at the destination, the message listener delivers the message to the message consumer. The message consumer is free to do other operations between messages. See Creating a Message Listener for Asynchronous Message Consumption on page 274 for details. TIBCO Enterprise Message Service User’s Guide | 39 TIBCO Enterprise Message Service User’s Guide . 40 | Chapter 2 Messages TIBCO Enterprise Message Service User’s Guide . page 66 Destination Bridges. page 46 Creating and Modifying Destinations. page 71 TIBCO Enterprise Message Service User’s Guide . page 68 Flow Control.| 41 Chapter 3 Destinations This chapter describes destinations (topics and queues). page 61 Wildcards. Topics • • • • • • • Destination Overview. page 42 Destination Properties. page 63 Inheritance. Servers connected by routes exchange messages sent to temporary topics. several client processes (and in several threads within a process) can create local objects denoting the destination. Temporary destinations support only local use. and consume messages from it. Client programs create temporary destinations. several client processes (and in several threads within a process) can create local objects denoting the destination. servers connected by routes do exchange messages sent to temporary topics. Client programs create dynamic destinations. if permitted by the server configuration. Temporary Temporary destinations are ideal for limited-scope uses. Scope of Delivery Dynamic destinations support concurrent use. That is.42 | Chapter 3 Destinations Destination Overview Destinations for messages can be either Topics or Queues. and temporary destinations. TIBCO Enterprise Message Service User’s Guide . or dynamically by a client application. Dynamic Dynamic destinations give client programs the flexibility to define destinations as needed for short-term use. However. The sections that follow provide more detail. only the client connection that created a temporary destination can consume messages from it. and client programs use them—relieving program developers and end users of the responsibility for correct configuration. A destination can be created statically in the server configuration files. That is. dynamic. Table 7 summarizes the differences between static. temporary topics are ideal destinations for reply messages in request/reply interactions. Static destinations support concurrent use. As a result. Creation Administrators create static destinations using EMS server administration tools or API. Table 7 Destination Overview (Sheet 1 of 2) Aspect Purpose Static Static destinations let administrators configure EMS behavior at the enterprise level. such as reply subjects. Administrators define these administered objects. That is. and consume messages from it. no messages are stored in the queue TIBCO Enterprise Message Service User’s Guide . or until the client disconnects from the server. Dynamic Client programs lookup dynamic destinations by name. Duration A temporary destination remains in the server either until the client that created it explicitly deletes it. Successful lookup returns a local object representation of the destination. A static destination remains in the server until an administrator explicitly deletes it.Destination Overview 43 | Table 7 Destination Overview (Sheet 2 of 2) Aspect Lookup Static Client programs lookup static destinations by name. A dynamic destination remains in the server as long as at least one client actively uses it. The server automatically deletes it (at a convenient time) when all applicable conditions are true: • Topic or Queue all client programs that access the destination have disconnected Topic no offline Temporary Not applicable. Successful lookup returns a local object representation of the destination. • durable subscribers exist for the topic • Queue queue. GEN_LEDGER. When you use the show queues or show topics command in the administration tool. See Inheritance of Properties on page 66 for more information. you could have an accounting application that publishes messages on several destinations. as required by client applications.GEN_LEDGER. The application could prefix all messages with ACCT. ACCT. The use of wildcards in destination names can also be used to define "parent" and "child" destination relationships. Changes to the configuration information can be made in a variety of ways. and ACCT. you can use the administration tool. For example. ACCT. or you can use the administration APIs. See Creating and Modifying Destinations on page 61 for more information about how clients use static destinations.RECEIVABLE. you see dynamic topics and queues have an asterisk (*) in front of their name in the list of topics or queues.GEN_LEDGER. where the child destinations inherit the properties from its parents.MISC could be subjects for the general ledger portion of the application. The period character allows you to create multi-part destination names that categorize destinations. Static Destinations Configuration information for static destinations is stored in configuration files for the EMS server.). Dynamic Destinations Dynamic destinations are created on-the-fly by the EMS server. Clients can obtain references to static destinations through a naming service such as JNDI or LDAP. Dynamic destinations do not appear in the configuration files and exist as long as there are messages or consumers on the destination. it means that the property was inherited from the parent queue or topic and cannot be changed. See Wildcards on page 63 for more information. To manage static destinations. TIBCO Enterprise Message Service User’s Guide . you can edit the configuration files using a text editor. Separating the subject name into elements allows applications to use wildcards for specifying more than one subject. and each element of the name could specify a specific component of the application. each element separated by the period character (.44 | Chapter 3 Destinations Destination Names A destination name is a string divided into elements.CASH. See Dynamically Creating Topics and Queues on page 267 for details on topics and queues can be dynamically created by the EMS server. If a property of a queue or topic has an asterisk (*) character in front of its name. As a result. This allows all messages delivered to one destination to also be delivered to the bridged destination. you can create a bridge between a topic and a queue or from a topic to another topic. temporary topics are ideal destinations for reply messages in request/reply interactions. between the same destination type. Destination Bridges You can create server-based bridges between destinations of the same or different types to create a hybrid messaging model for your application. or to more than one destination. Servers connected by routes exchange messages sent to temporary topics. See Destination Bridges on page 68 for more information about destination bridging.Destination Overview 45 | Temporary Destinations TIBCO Enterprise Message Service supports temporary destinations as defined in JMS specification 1. For more information on temporary queues and topics. You can bridge between different destination types.1 and its API. TIBCO Enterprise Message Service User’s Guide . For example. refer to the JMS documentation described in Third Party Documentation on page xxvii. conf or queues. Table 8 lists the properties that can be assigned to topics and queues. Table 8 Destination properties (Sheet 1 of 2) Property failsafe secure maxbytes maxmsgs overflowPolicy global sender_name sender_name_enforced flowControl trace import export maxRedelivery exclusive prefetch expiration Described on Page 47 48 49 50 50 52 52 53 53 54 54 55 56 56 57 60 Topic Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No No Yes Yes Queue Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes TIBCO Enterprise Message Service User’s Guide .conf file or by means of the setprop topic or setprop queue command in the EMS Administrator Tool.46 | Chapter 3 Destinations Destination Properties This section contains a description of properties for topics and queues. You can set the properties directly in the topics. The following sections describe each property. the administrator should set the failsafe property for the topic or the queue. However. In this mode. all data for that queue or topic are written into external storage in synchronous mode. TIBCO Enterprise Message Service User’s Guide . some data could be lost without the possibility of recovery. Although failsafe mode guarantees no messages are lost. In synchronous mode. messages are written to the file on disk in asynchronous mode to obtain maximum performance. in case of software or hardware failure. The functionality of these properties is replaced with the import and export properties. In failsafe mode. the data may remain in system buffers for a short time before it is written to disk and it is possible that. tibrv_import tibrvcm_import tibrv_export tibrvcm_export — — — — Described on Page Topic Queue Yes Yes Yes Yes Yes Yes No No failsafe As described in Persistent Messages and Failsafe Destinations on page 29. The failsafe property ensures that no messages are ever lost in case of server failure. a write operation is not complete until the data is physically recorded on the external device. it also significantly affects the performance. this mode provides the best combination of performance and reliability. For situations in which any loss of data is not acceptable. You can set failsafe using the form: failsafe When failsafe is not set. for many applications that can tolerate the rare loss of a few messages.Destination Properties 47 | Table 8 Destination properties (Sheet 2 of 2) Property Deprecated Properties The following properties are available for backward-compatibility with previous versions. the failsafe property determines whether the server writes persistent messages to disk synchronously or asynchronously. The server authorization property acts as a master switch for checking permissions. and set the secure property on each affected destination. See Chapter 8. To configure secure communication between clients and server. the server checks user permissions on secure destinations only when the authorization property is enabled. That is. the server does not check permissions for that destination and any authenticated user can perform any operation on that topic or queue. The secure property is independent of SSL—it controls basic authentication and permission verification within the server.48 | Chapter 3 secure Destinations When the secure property is enabled for a destination. you must both enable the authorization configuration parameter. You can set secure using the form: secure If the secure property is not set for a destination. on page 221 for more information on permissions and the secure property. Authentication and Permissions. it instructs the server to check user permissions whenever a user attempts to perform an operation on that destination. TIBCO Enterprise Message Service User’s Guide . To enforce permissions. see Using the SSL Protocol on page 365. When a destination inherits different values of this property from several parent destinations. For queues. megabytes. For example.Destination Properties 49 | maxbytes Topics and queues can specify the maxbytes property in the form: maxbytes=value[KB|MB|GB] where value is the number of bytes. the server does not limit the memory allocation for the queue. For topics. when the subscriber consumes messages (freeing storage) the topic can accept additional messages for the subscriber. or is not set. it inherits the smallest value. MB or GB after the number to specify kilobytes. For example. You can optionally include a KB. Exceeding either limit causes the server to reject new messages until consumers reduce the the queue size to below these limits. For example: maxbytes=1000KB Means 1000 kilobytes. or gigabytes. then the queue size could reach this limit. TIBCO Enterprise Message Service User’s Guide . Should this limit be exceeded. if a durable subscriber is off-line for a long time. You can set both maxmsgs and maxbytes properties on the same queue. if a receiver is off-line for a long time. If maxbytes is zero. summed over all messages in the queue. That is. which would prevent further memory allocation for additional messages. maxbytes limits the maximum size (in bytes) that the topic can store for delivery to each durable subscriber on that topic. pending messages accumulate until they exceed maxbytes. respectively. maxbytes defines the maximum size (in bytes) that the queue can store. messages will be rejected by the server and the message producer send calls will return an error (see also overflowPolicy). the limit applies separately to each durable subscriber on the topic. For example: maxbytes=1000 Means 1000 bytes. the server does not accept the message into storage. When adding a message would exceed this limit. so the impact of each overflowPolicy value is described separately for topics and queues.50 | Chapter 3 Destinations maxmsgs Topics and queues can specify the maxmsgs property in the form: maxmsgs=value where value defines the maximum number of messages that can be waiting in a queue. then that policy is inherited by the child destination. the server does not limit the number of messages in the queue. and the message producer’s send call returns an error (but see also overflowPolicy). If no parent has OVERFLOW_REJECT_INCOMING set and a parent has OVERFLOW_DISCARD_OLD policy set. Exceeding either limit causes the server to reject new messages until consumers reduce the the queue size to below these limits. Set the overflowPolicy using the form: overflowPolicy=default|discardOld|rejectIncoming If overflowPolicy is not set. If wildcards are used in the .conf file the inheritance of the overflowPolicy policy from multiple parents works as follows: • • • If a child destination has a non-default overflowPolicy policy set. If no parent has the OVERFLOW_REJECT_INCOMING or set. If a parent has OVERFLOW_REJECT_INCOMING set. overflowPolicy Topics and queues can specify the overflowPolicy property to change the effect of exceeding the message capacity established by either maxbytes or maxmsgs. or is not set. then it is inherited by the child destination over any other policy. The effect of overflowPolicy differs depending on whether you set it on a topic or a queue. then the default policy is used by the child destination. You can set both maxmsgs and maxbytes properties on the same queue. If maxmsgs is zero. then the policy is default. then that policy is used and it does not inherit any conflicting policy from a parent. OVERFLOW_REJECT_INCOMING • TIBCO Enterprise Message Service User’s Guide . the oldest messages are discarded from the queue and an error is returned to the message producer. if messages on the queue have exceeded the maxbytes or maxmsgs value. This is the same default behavior for topics and queues as in EMS 4. if any of the subscribers have an outstanding number of undelivered messages on the server that are over the message limit. In this case. only the oldest messages for the one subscriber are discarded. For example. regardless of maxbytes or maxmsgs setting. if any of the subscribers have an outstanding number of undelivered messages on the server that are over the message limit. For queues. no error returned to the producer because messages could be delivered to some subscribers and discarded for others. all new messages are rejected and an error is returned to the producer. discardOld For topics. discardOld specifies that. default specifies that new messages are rejected by the server and an error is returned to the producer if the established maxbytes or maxmsgs value has been exceeded. while the other two subscribers continue to receive all of their messages. discardOld specifies that.) TIBCO Enterprise Message Service User’s Guide . the oldest messages are discarded before they are delivered to the subscriber. but only one subscriber exceeds the message limit. rejectIncoming specifies that. rejectIncoming For topics. rejectIncoming specifies that. The discardOld setting impacts subscribers individually. if messages on the queue have exceeded the maxbytes or maxmsgs value. When messages are discarded for subscribers. default specifies that messages are sent to subscribers. (This is the same as the default behavior. For queues. all new messages are rejected and an error is returned to the producer. For queues. you might have three subscribers to a topic.Destination Properties 51 | default For topics.3. enter: setprop queue myQueue maxmsgs=1000. You can set sender_name using the form: sender_name When the sender_name property is enabled. sender_name The sender_name property specifies that the server may include the sender’s username for messages sent to this destination. If authentication for the server is turned off. the SSL connection protocol guarantees the client is authenticated using the client’s digital certificate. If authentication for the server is enabled. the server places whatever user name the message producer supplied when the message producer created a connection to the server. TIBCO Enterprise Message Service User’s Guide . If a message producer sets the JMS_TIBCO_DISABLE_SENDER property to true for a message. on page 401.overflowPolicy=rejectIncoming global Messages destined for a topic or queue with the global property set are routed to the other servers that are participating in routing with this server. the server takes the user name supplied by the message producer when the connection is established and places that user name into the JMS_TIBCO_SENDER property in the message. the server overrides the sender_name property and does not add the sender name to the message. enter: setprop topic myTopic maxbytes=100KB. Working With Routes. see Chapter 16.overflowPolicy=discardOld To reject all new messages published to myTopic when the memory used by undelivered messages for any of the topic subscribers exceeds 100KB.52 | Chapter 3 Examples Destinations To discard messages on myQueue when the number of queued messages exceeds 1000. The message producer can override this behavior by specifying a property on a message. If SSL is used. the server authenticates the user name supplied by the connection and the user name placed in the message property will be an authenticated user. You can set global using the form: global For further information on routing between servers. clients may not be willing to disclose the username of their message producers. This will allow clients to avoid sending messages to destinations that would cause their message producer usernames to be exposed. this property overrides the sender_name property. For example: flowControl=1000KB Means 1000 kilobytes. In these situations. Unlike the behavior established by the overflowPolicy property.Destination Properties 53 | sender_name_enforced The sender_name_enforced property specifies that messages sent to this destination must include the sender’s user name. The server retrieves the user name of the message producer using the same procedure described in the sender_name property above. TIBCO Enterprise Message Service User’s Guide . flowControl The flowControl property specifies the target maximum size the server can use to store pending messages for the destination. respectively. This is useful when message producers send messages much more quickly than message consumers can consume them. If this is the case. You can set sender_name_enforced using the form: sender_name_enforced If the sender_name property is also set on the destination. If you specify the flowControl property without a value. unlike. In some business situations. the operator of the EMS server should develop a policy for disclosing a list of destinations that have these properties enabled. the target maximum is set to 256KB. MB or GB after the number to specify kilobytes. megabytes. or gigabytes. You can optionally include a KB. these clients may wish to avoid sending messages to destinations that have the sender_name or sender_name_enforced properties enabled. the sender_name property. flowControl never discards messages or generates errors back to producer. You can set flowControl using the form: flowControl=size[KB|MB|GB] where size is the maximum number of bytes of storage for pending messages of the destination. Should the number of messages exceed the maximum. However. the server will slow down the producers to the rate required by the message consumers. there is no way for message producers to override this property. Working With TIBCO SmartSockets. See Flow Control on page 71 for more information about flow control.conf file.conf file. see these chapters: • • Chapter 11. Rendezvous) before configuring topics with the import property. You can specify the name of one or more transports of the same type in the import property. Also. You can set trace using the form: trace[=body] Specifying trace (without =body). as specified by the [NAME] ids in the transports. Specifying trace=body generates trace messages that include the message body. and configure the external system (for example.RV2" Currently you can configure transports for TIBCO Rendezvous reliable and certified messaging protocols.conf file must be set to enable before the value in this property is enforced by the server. import The import property allows messages published by an external system to be received by a EMS destination (a topic or a queue). You can set import using the form: import="list" where list is one or more transport names. Working With TIBCO Rendezvous. You must purchase. trace Specifies that tracing should be enabled for this destination. See Message Tracing on page 353 for more information about message tracing. as long as the transport to the external system is configured. you must configure the communication parameters to the external system by creating a named transport in the transports.54 | Chapter 3 Destinations The flow_control parameter in tibemsd. install. generates trace messages that include only the message sequence and message ID. on page 299 Chapter 12. Multiple transport names in the list are separated by commas. For example: import="RV1. For complete details about external message services. on page 325 TIBCO Enterprise Message Service User’s Guide . For example: export="RV1. on page 325 TIBCO Enterprise Message Service User’s Guide .Destination Properties 55 | export The export property allows messages published by a client to a topic to be exported to the external systems with configured transports. you must configure the communication parameters to the external system by creating a named transport in the transports. Multiple transport names in the list are separated by commas. install. Working With TIBCO SmartSockets.conf file. You can specify the name of one or more transports of the same type in the export property. and configure the external system (for example. Working With TIBCO Rendezvous. You can set import using the form: export="list" where list is one or more transport names.RV2" Currently you can configure transports for Rendezvous reliable and certified messaging protocols. as specified by the [NAME] ids in the transports. Rendezvous) before configuring topics with the export property. For complete details about external message services. Also. on page 299 Chapter 12. You must purchase.conf file. see these chapters: • • Chapter 11. if the JMS_TIBCO_PRESERVE_UNDELIVERED property on the message is set to true. so there is no maximum. This arrangement prevents a large buildup of messages at one receiver and balances the load of incoming messages across a set of queue receivers. When none of the receivers are ready to receive more messages. see Undelivered Message Queue on page 21. See Undelivered Message Queue on page 21 for details. No other consumers can receive messages from the queue. You can set maxRedelivery using the form: maxRedelivery=count where count is an integer between 2 and 255 that specifies the maximum number of times a message can be delivered to receivers. When exclusive is set for a queue. For messages that have been redelivered. the server sends all messages on that queue to one consumer. the server waits until a queue receiver reports that it can accept a message. the message is placed on the undelivered queue so it can be handled by a special consumer. TIBCO Enterprise Message Service User’s Guide . the JMSRedelivered header property is set to true and the JMSXDeliveryCount property is set to the number of times the message has been delivered to the queue. You can set exclusive using the form: exclusive Non-Exclusive Queues & Round-Robin Delivery By default. Instead. the server distributes another round of messages— one to each receiver that is still ready. the current number of delivery attempts in the JMSXDeliveryCount property is not retained. the server selects one of the standby consumers as the new primary. exclusive The exclusive property is available for queues only (not for topics).56 | Chapter 3 Destinations maxRedelivery The maxRedelivery property specifies the number of attempts the server should make to redeliver a message sent to a queue. these additional consumers act in a standby role. If any receivers are still ready to accept additional messages. For more information about undelivered messages. and begins delivering messages to it. the message is either destroyed or. Once the server has attempted to deliver the message the specified number of times. exclusive is not set for queues and the server distributes messages in a round-robin—one to each receiver that is ready. A value of zero disables maxRedelivery. if the primary consumer fails. If the server restarts. When a destination does not set any value for prefetch. The prefetch property applies to both topics and queues.Destination Properties 57 | prefetch The message consumer portion of a client and the server cooperate to regulate fetching according to the prefetch property. then the default value is 5. TIBCO Enterprise Message Service User’s Guide . or no destination in the parent chain sets a value for prefetch. That is. none 0 The destination inherits the prefetch value from a parent destination with a matching name. or an implicit call (in an asynchronous consumer). Disables automatic fetch. the message consumer initiates fetch only when the client calls receive—either an explicit synchronous call. then the default value is 0 (that is. If it has no parent. See Automatic Fetch Disabled on page 59 for details. See Inheritance on page 59 for details. or more 1 The message consumer automatically fetches messages from the server—initiating fetch only when it does not currently hold a message. See Automatic Fetch Enabled on page 58 for details. You can set prefetch using the form: prefetch=value where value is one of the values in Table 9. The message consumer never stores more than the number of messages specified by value. Table 9 Prefetch Value 2 Description The message consumer automatically fetches messages from the server. inherit the prefetch value). the server does not deliver them to other consumers (unless the first consumer’s connection to the server is broken). — The message consumer initiates the fetch phase by signalling to the server that it is ready for more messages. The receive call embraces both of these phases. The work around is to set prefetch=none. but this can have performance implications on large volume interfaces. client code takes a message from the message consumer. However. To reduce waiting time for client programs.58 | Chapter 3 Destinations If both prefetch and maxRedelivery are set to a non-zero value. The first message is replayed 4 times. the message consumer can prefetch messages—that is. when a message consumer prefetches a group of messages. the other 4 pre-fetched messages are also sent to the undelivered queue and are not processed by the receiving application. fetch a batch of messages from the server. then there is a potential to lose prefetched messages if one of the messages exceeds the maxRedelivery limit. — The server responds by transferring one or more messages to the client. prefetch=5 and maxRedelivery=4. one by one. For example. It can improve performance by decreasing or eliminating client idle time while the server transfers a message. However. set prefetch to a positive integer. Automatic Fetch Enabled To enable automatic fetch. TIBCO Enterprise Message Service User’s Guide . It initiates fetch when needed and it accepts a message from the message consumer. • In the accept phase. Background Delivering messages from the server destination to a message consumer involves two independent phases—fetch and accept: • The fetch phase is a two-step interaction between a message consumer and the server. hits the maxRedelivery limit and is sent to the undelivered queue (as expected). Automatic fetch ensures that a message is always waiting when client code is ready to accept one. and hold them for client code to accept. which stores them in the message consumer. a message consumer can still hold a message. a receive call initiates fetch. then the child destination uses the default value (which is 5). A third receive call initiates another fetch. and the server does not deliver it to another consumer (unless the first consumer’s connection to the server is broken). but its timeout elapses before the server finishes transferring the message. these behaviors are possible: • • • When all parent destinations set the value none. TIBCO Enterprise Message Service User’s Guide . Inheritance When a destination inherits the prefetch property from parent destination with matching names. Even when prefetch=none. then the child destination inherits the largest value from among the entire parent chain. To prevent messages from waiting in this state for long periods of time. When any parent destination sets a non-zero numeric value. then the child destination inherits the value none.Destination Properties 59 | Automatic Fetch Disabled To disable automatic fetch. set prefetch=none. A second receive call does not fetch another message. it accepts the message that is already waiting. instead. code programs either to call receive with no timeout. This situation leaves a fetched message waiting in the message consumer. Notice that a waiting message still belongs to the message consumer. When none of the parent destinations sets any non-zero numeric value. or to call it (with timeout) repeatedly and shorten the interval between calls. For example. See Undelivered Message Queue on page 21 for details. if the JMS_TIBCO_PRESERVE_UNDELIVERED property on the message is set to true. the server overrides the JMSExpiration value set by the producer in the message header with the time specified by the expiration property.4. such as msec. When a message expires it is either destroyed or. min.4 and later. hour or day to describe the time value as being in milliseconds.4 client application uses non-zero values for message expiration. the message is placed on the undelivered queue so it can be handled by a special consumer. if your EMS server or client application are based on a version of EMS prior to 4. hours. Zero is a special value that indicates messages to the destination never expire. when the server delivers a message to that destination. You can set the expiration property for any queue and any topic using the form: expiration=time[msec|sec|min|hour|day] where time is the number of seconds. clients automatically synchronize their clocks with the server. seconds. if your pre-4. You can optionally include time units. Synchronize clocks to a tolerance that is a very small fraction of the smallest message expiration time. For example: expiration=10min Means 10 minutes. you must ensure that clocks are synchronized among all the host computers that send and receive messages. In EMS version 4. sec. minutes. However. TIBCO Enterprise Message Service User’s Guide . or days. respectively.60 | Chapter 3 Destinations expiration If an expiration property is set for a destination. you can set an overflowPolicy by entering: addprop queue myQueue maxmsgs=1000. enter: create queue myQueue To create a topic named myTopic. For example. You create a queue using the create queue command and a topic using the create topic command. For example. Administered objects can also be stored in the EMS server and looked up using the EMS implementation of JNDI.Creating and Modifying Destinations 61 | Creating and Modifying Destinations Destinations are typically "static" administered objects that can be stored in a JNDI or LDAP server. to create a new queue named myQueue. setprop topic.overflowPolicy=discardOld To change the overflowPolicy from discardOld to rejectIncoming.conf files. enter: addprop queue myQueue overflowPolicy=rejectIncoming The setprop queue and setprop topic commands remove properties that are not explicitly set by the command. This section describes how to use the EMS Administration Tool described in Chapter 6 to create and modify destination objects in EMS. You can use the show queues and show topics commands to list all of the queues and topics on your EMS server and the show queue and show topic commands to show the configuration details of specific queues and topics. enter: setprop queue myQueue maxmsgs=100 TIBCO Enterprise Message Service User’s Guide . For example. A queue or topic may include optional properties that define the specific characteristics of the destination. enter: create topic myTopic The queue and topic data stored on the EMS server is located in the queues. removeprop queue. respectively. to change maxmsgs to 100 and to remove the overflowPolicy parameter. addprop topic. These properties are described in Destination Properties on page 46 and they can be specified when creating the queue or topic or modified for an existing queue or topic using the addprop queue. setprop queue.conf and topics. to discard messages on myQueue when the number of queued messages exceeds 1000. and removeprop topic commands. in the EMS Administration Tool. TIBCO Enterprise Message Service User’s Guide . You can set the secure property on a topic or queue and then use the grant topic or grant queue command to specify which users and/or groups are allowed to perform which actions on the destination. Authentication and Permissions. For example.62 | Chapter 3 Destinations Creating Secure Destinations By default. named myQueue. on page 221 for more information. all authenticated EMS users have permissions to perform any action on any topic or queue. The secure property requires that you enable the authorization property on the EMS server. to create a secure queue. enter: set server authorization=enabled create queue myQueue secure grant queue myQueue joe send grant queue myQueue eric send grant queue myQueue sally receive See Chapter 8. to which only users "joe" and "eric" can send messages and "sally" can receive messages. where the child destinations inherit the properties and permissions from its parents. When > is mixed with text. For example: foo.* Matches foo. foo.boo.Wildcards 63 | Wildcards You can use wildcards when specifying statically created destinations in queues.bar. it matches one or more trailing elements. • • The wildcard > by itself matches any destination name.> Matches foo.bar Matches foo.boo. but not foo. TIBCO Enterprise Message Service User’s Guide .bar and foo.boo.boo. and foo.bar. but not foo. For example: foo. foo. • The wildcard * means that any token can be in the place of *. * and >.bar. You must first understand wildcards to understand the inheritance rules described in Inheritance on page 66. Wildcards * and > To understand the rules for inheritance of properties. foo.conf and topics. it is important to understand the use of the two wildcards.boo.conf. The use of wildcards in destination names can be used to define "parent" and "child" destination relationships.bar.boo.bar.*.bar. bar. • • You cannot publish to wildcard topics. foo. Wildcards in Queues TIBCO Enterprise Message Service enables you to use wildcards in queue names in some situations. foo. but TIBCO Enterprise Message Service User’s Guide . However.bar is not in the configuration file.*). if the queue configuration file includes a line: foo. If you subscribe to a topic containing a wildcard. You can subscribe to a wildcard topic (for example foo.bar).* or foo. if there is no matching topic name in the configuration file. or foo.* then users can dynamically create queues not foo. If foo.64 | Chapter 3 Destinations Wildcards in Topics TIBCO Enterprise Message Service enables you to use wildcards in topic names in some situations: • You can subscribe to wildcard topics. if you subscribe to foo. no messages will be published on that topic.bar.*. then you can publish to foo.bob. foo. foo. you will receive any message published to a matching topic.>. whether or not there is a matching topic in the configuration file (for example. The wildcard queue names in the configuration files must have non-wildcard children to send and receive messages. and so forth.bar. For example.* you will receive messages published to a topic named foo.bar if foo.> exists in the configuration file. you can use wildcard queue names in the configuration files. However. For example. You can neither send to nor receive from wildcard queue names.bob. bar. and foo.boo.* The EMS server can dynamically create queues with names like foo.conf file contains: > The EMS server can dynamically create a queue with any name. The same basic wildcard rules apply to dynamically created destinations as described above for static destinations.*. Examples • If the queues. the EMS server may dynamically create destinations on behalf of its clients. TIBCO Enterprise Message Service User’s Guide .bar and foo.boo. • If the topics. but not foo.Wildcards 65 | Wildcards and Dynamically Created Destinations As described in Dynamically Creating Topics and Queues on page 267.bar The EMS server can dynamically create topics with names like foo. The use of wildcards in the . foo.bar.> The EMS server can dynamically create topics with names like foo. • If the queues.boo.conf file contains only: foo.bar.boo.boo.conf files can be used to control the allowable names of dynamically created destinations. foo.bar.conf file contains only: foo. but not foo.bar.bar. • If the topics.conf file contains only: foo.boo. refer to Destination Properties on page 46. For more information on wildcards.66 | Chapter 3 Destinations Inheritance This section describes the inheritance of properties and permissions. In other words.bar queue has a maxbytes value of 2000.conf file: foo.bar has both the secure and sender_name properties. Inheritance of Properties All destination properties are inheritable for both topics and queues. you can override the value established in a parent. If your EMS server were to dynamically create a foo.* failsafe foo. if you have the following in your topics. However.bar and foo. on page 221. it too would have the failsafe property.* maxbytes=200 foo. EMS does not offer the ability to remove inherited properties. if you have the following in your topics.* secure without making foo.bar secure. For example. For more information on permissions. refer to Chapter 8. foo.bar sender_name Then foo. TIBCO Enterprise Message Service User’s Guide .* secure foo.conf file: foo. refer to Wildcards on page 63. For example.bar foo.conf file: foo. This means that a property set for a "wildcarded" destination is inherited by all destinations with matching names. For example.bob Topics foo. there is no way to make topic foo.bar maxbytes=2000 The foo. if you have the following in your queues.new topic.*. for properties that are assigned values.bob are failsafe topics because they inherit failsafe from their parent. For more information on destination properties. Authentication and Permissions. In the above example. The properties inherited from a parent are in addition to the properties defined for the child destination. it can not be removed. For example. If the parent has a permission. Permissions have positive boolean inheritance. You must plan before assigning properties to topics and queues. These permission sets are additive. For example.Inheritance 67 | When there are multiple ancestors for a destination. For more information on permissions.bar topic has the sender_name. the destination inherits the properties from all of the parents. if a user has permission to publish on topic foo. refer to Wildcards on page 63. For example: > maxbytes=2000 foo. the user also has permission to publish on foo. Property inheritance is powerful.*. if you enter the following line in the topics. For example.new. if Bob belongs to GroupA. but can be complex to understand and administer.* maxbytes=200 foo. This might require a great deal of memory for storage and greatly decrease the system performance. All rules for wildcards apply to inheritance of permissions. secure and failsafe properties. Using wildcards to assign properties must be used carefully.bar failsafe The foo. then the child inherits that permission. For example: > sender_name foo. For more information on wildcards. the destination inherits the smallest value.bar and foo. on page 221. TIBCO Enterprise Message Service User’s Guide .* secure foo. refer to Chapter 8. then Bob has publish permission on that topic. Once a permission right has been granted through inheritance. Inheritance of Permissions Inheritance of permissions is similar to inheritance of properties. When there are multiple parents for a destination that contain conflicting property values.bar topic has a maxbytes value of 200.bar The foo. and of all permissions set for every group in which the user is a member. Permissions for a single user are the union of the permissions set for that user. and GroupA has publish permission on a topic. Authentication and Permissions. regardless of additional entries.conf file: > failsafe you make every topic failsafe. However. Figure 13 and Figure 14 illustrate example bridging scenarios. you can specify a particular destination name. You can also create a bridge between one destination and multiple destinations. That is. Another example is an application that publishes messages to several topics. For example. you can create a bridge from a topic to a queue or from a queue to a topic.b to queue q. such processing requires significant coding effort in the application.B Subscriber Queue queue.B Consumer TIBCO Enterprise Message Service User’s Guide . For example. may also need the messages to be published to several monitoring applications.queue. an application may send messages to a queue for distributed load balancing. When specifying a bridge.* are sent to foo. EMS provides a server-based solution to this problem. possibly of different types.queue.68 | Chapter 3 Destinations Destination Bridges Some applications require the same message to be sent to more than one destination. An application can process messages so that they are sent multiple times to the required destinations. You can create bridges between destinations so that messages sent to one destination are also delivered to all bridged destinations.c. you can create a bridge from topic a. Bridges are created between one destination and one or more other destinations of the same or of different types. Figure 13 Bridging a topic to a queue TIBCO EMS Server Subscriber Publisher Topic A. For example. All messages however. must also be sent to a database for backup and for data mining.* to queue foo. messages delivered to any topic matching foo.b and topic a. or you can use wildcards. if you specify a bridge on topic foo. however. A queue is used to collect all messages and send them to the database. That same application. For example. That is.Destination Bridges 69 | Figure 14 Bridging a topic to multiple destinations TIBCO EMS Server Subscriber Publisher Topic A. Each destinationName can specify more than one destinationToBridgeTo.C. Creating a Bridge Bridges are configured in the bridges. and therefore any destination matching the pattern will have the specified bridge. destinationToBridgeTo is the name of the destination you wish to create a bridge to. and selector="messsgeSelector" is an optional message selector to specify the subset of messages the destination should receive. the bridge illustrated in Figure 13 and Figure 14 would be specified as the following in bridges. Each destinationName can specify wildcards.conf configuration file.B.conf: [topic:A.B Subscriber Consumer Bridges are not transitive.B has a bridge to queue Q. messages sent to a destination with a bridge are only delivered to the specified bridged destinations and are not delivered across multiple bridges. Messages delivered to A. Queue Q. topic A.B Topic C. You specify a bridge using the following syntax: [destinationType:destinationName] destinationType=destinationToBridgeTo selector="messageSelector" where destinationType is the type of the destination (either topic or queue).C.B topic=C. TIBCO Enterprise Message Service User’s Guide . destinationName is the name of the destination from which you wish to create a bridge.B Specifying a message selector on a bridged destination is described in the following section.B are also delivered to Q. For example.B Subscriber Queue queue.B has a bridge to topic B.B] queue=queue. but not to B.B. Access Control and Bridges Message producers must have access to a destination to send messages to that destination.B] queue=queue. This can cause unnecessary network traffic if each bridged destination is only interested in a subset of the messages sent to the original destination. If a message cannot be delivered to a bridged destination because the message producer does not have the correct permissions for the bridged destination. see the documentation for the Message class in the relevant EMS API reference document. all messages sent to a destination with a bridge are sent to all bridged destinations.70 | Chapter 3 Destinations Selecting the Messages to Bridge By default. and therefore fails and is rolled back. Transactions When a message producer sends a message within a transaction. ’high’)" For detailed information about message selector syntax. TIBCO Enterprise Message Service User’s Guide . if the transaction succeeds. a bridge automatically has permission to send to its target destination. Therefore. all messages sent across a bridge are part of the transaction. However. no consumers for bridged destinations receive the messages.B selector="urgency in(’medium’. all messages are delivered to all bridged destinations.B topic=C. You can optionally specify a message selector for each bridge to determine which messages are sent over that bridge. The following is an example of specifying a selector on the bridges defined in the previous section: [topic:A. the transaction cannot complete. If the transaction fails. Special configuration is not required. Message selectors for bridged destinations are specified as the selector property on the bridge. message producers may send messages more rapidly than message consumers can receive them. MB.Flow Control 71 | Flow Control In some situations. When you wish to control the flow of messages on a destination. Each destination can specify a target maximum size for storing pending messages. The flowControl property specifies the target maximum size of stored pending messages for the destination. See Chapter 7. To avoid this. and other factors. flowControl = 60MB specifies the target maximum storage for pending messages for a destination is 60 Megabytes. number of message producers. depending upon message size.conf enables and disables flow control globally for the EMS server. You can specify KB. set the property on that destination. or GB for the units. the server does not enforce any flow control on destinations. and the server can potentially exhaust its storage capacity if the message consumers do not receive messages quickly enough. Once message consumers have received messages and the pending message storage goes below the specified limit. When the storage for pending messages is near the specified limit. on page 155 for more information about working with configuration parameters. the server may use slightly more or less storage before enforcing flow control. For example. The calls do not return until the storage has decreased below the specified limit. When flow_control is disabled (the default setting). EMS blocks message producers when new messages are sent. the server blocks all new calls to send a message from message producers. When the target is reached. The pending messages for a destination are stored by the server until they can be delivered. Setting the flowControl property on a destination but specifying no value causes the server to use a default value of 256KB. TIBCO Enterprise Message Service User’s Guide . unless you specify the units for the size. When flow_control is enabled. Enabling Flow Control The flow_control parameter in tibemsd. the server enforces any flow control settings specified for each destination. When flow control is enabled. This effectively slows down message producers until the message consumers can receive the pending messages. the server allows the send message calls to return to the caller and the message producers can continue processing. EMS allows you to control the flow of messages to a destination. flowControl Enforcing Flow Control The value specified for the flowControl property on a destination is a target maximum for pending message storage. The size specified is in bytes. Using the Configuration Files. Destination Bridges and Flow Control Flow control can be specified on destinations that are bridged to other destinations. if a topic has inactive durable subscriptions or no current subscribers. If the flowControl property is set on the topic on the server receiving the messages. TIBCO Enterprise Message Service User’s Guide . If you wish the flow of messages sent by way of the bridge to slow down when receivers on the bridged-to destination cannot process the messages quickly enough. Also. the server cannot enforce flow control for that topic. For topics. when the pending message size limit is reached.bar). foo.72 | Chapter 3 Destinations If there are no message consumers for a destination.*). if a queue has no started receivers. then flow control is enforced as long as there are subscribers to that topic or any parent topic (for example. That is. If the flowControl property is set on the topic on the server sending the messages. if there are subscribers to foo. you must set the flowControl property on both destinations on either side of the bridge. flow control can be specified for a topic on either the server where messages are produced or the server where messages are received. This could be due to network latency between the routed servers or it could be because flow control on the other server is preventing new messages from being sent. Flow control is not relevant for queue messages that are routed to another server. the server does not enforce flow control for the destination. the server cannot enforce flow control for that queue. the server may block any topic publishers when sending new messages if messages cannot be sent quickly enough by way of the route. if flow control is set on a specific topic (for example. Routes and Flow Control For global topics where messages are routed between servers. messages are not forwarded by way of the route until the topic subscriber receives enough messages to lower the pending message size below the specified limit. If any of those consumers are within the same thread of program control. The dependency analysis is analogous to mutex deadlock. Deadlock can even occur across several threads (or even programs on different hosts). But more complex cases can arise. Figure 15 Flow Control Deadlock across Two Threads Dependency D e p e n d e n c y Thread T1 P1 Destinations with Flow Control Send Msg Consume Dest A Consume Thread T2 C2 C1 Dest B Send Msg P2 D e p e n d e n c y Dependency TIBCO Enterprise Message Service User’s Guide . consider the situation in Figure 15: • • • Producer P1 in thread T1 has a consumer C2 in thread T2. producers to that destination can block waiting for flow control signals from the destination’s consumers. For example. Namely. Because of the circular dependency. deadlock can occur if either producer blocks its thread waiting for flow control signals. you must be careful to avoid potential deadlock situations. if dependencies link them. You must analyze your programs and distributed systems in a similar fashion to avoid potential deadlock. The simplest case to detect is when producer and consumer are in the same session (sessions are limited to a single thread). Threads and Deadlock When using flow control. Producer P2 in T2 has a consumer C1 in T1. a potential for deadlock exists. the producer will not unblock until the destination contains fewer messages. When flow control is in effect for a destination. and the consumer in the blocked thread cannot reduce the number of messages.Flow Control 73 | Flow Control. 74 | Chapter 3 Destinations TIBCO Enterprise Message Service User’s Guide . page 82 TIBCO Enterprise Message Service User’s Guide . page 81 Publish and Subscribe Messaging Example.| 75 Chapter 4 Getting Started This chapter provides a quick introduction to setting up a simple EMS configuration and running some sample client applications to publish and subscribe users to a topic. page 78 Point-to-Point Messaging Example. page 76 Compiling the Sample Clients. Topics • • • • • About the Sample Clients. page 77 Creating Users with the EMS Administration Tool. NET and Java sample clients. you will compile and run the Java sample clients.. you will use some of the sample clients in the ems/samples/java directory. see the Readme files in their respective folders.NET sample clients. For information on how to run the C and . The ems/samples directory contains the /c.76 | Chapter 4 Getting Started About the Sample Clients The EMS sample clients were designed to allow you to run TIBCO Enterprise Message Service with minimum start-up time and coding. see the readme files in their respective directories. which contain the C. /cs. The jms/samples/java/JNDI subdirectory contains sample clients that use the JNDI lookup technique. For information on compiling and running the other sample clients. The ems/samples/java directory contains three sets of files: • • • Sample clients for TIBCO Enterprise Message Service implementation. The jms/samples/java/tibrv subdirectory contains sample clients that demonstrate the interoperation of TIBCO Enterprise Message Service with TIBCO Rendezvous applications. In this chapter. TIBCO Enterprise Message Service User’s Guide . and /java subdirectories. In this chapter. except for those samples in the JNDI and tibrv subdirectories. which is located in the ems/sample/java directory. Make sure you have Java JDK 1. /ems/samples/java TIBCO Enterprise Message Service User’s Guide . On Windows systems.java This compiles all the samples in the directory. Enter setup to set the environment and classpath: > setup 5. For example.Compiling the Sample Clients 77 | Compiling the Sample Clients To compile and run the sample clients you need to execute "setup" script. 2. an error message appears.bat. 3. on a Windows system this might look like: set TIBEMS_ROOT=C:\tibco\EMS 4. If they do not compile correctly. the setup file is setup.4 or greater installed and that you’ve added the bin directory to your PATH variable. Compile the samples: > javac -d .sh. the class files will appear in the directory. the setup file is setup. To compile the sample client files: 1. Open the correct setup script file and verify that the TIBEMS_ROOT environment variable identifies the correct pathname to your /tibco/ems directory. Open a command line or console window. If the files compile successfully. *. and navigate to the /ems/samples/java directory. On Unix systems. Start the EMS Server and EMS Administration Tool In this example. On a computer running Windows. you can also start the EMS server from the Start menu.NET. Start the EMS server Start the EMS server as described in Running the EMS Server on page 89. TIBCO Enterprise Message Service User’s Guide . All of the parameters you set using the administration tool in this chapter can also be set by editing the configuration files described in Using the Configuration Files on page 155. .78 | Chapter 4 Getting Started Creating Users with the EMS Administration Tool This section describes how to start the EMS server and use the administration tool to create two new users. You must first start the EMS server before starting the EMS administration tool. following the path Programs>TIBCO Enterprise Message Service 4.4>Start EMS server. You can also programmatically set parameters using the C. Parameters set programmatically by a client are only set for the length of the session. or Java APIs. you will create topics and users using the EMS administration tool. use the connect server command as follows: > connect [server URL] [user-name] [password] For more information on this command. follow the procedure described in When You First Start tibemsadmin on page 104. To connect the EMS administration tool to the EMS server. For further information on the administration tool. see Starting the EMS Administration Tool on page 102 and Command Listing on page 106. following the path Programs>TIBCO Enterprise Message Service 4. you can also start the administration tool from the Start menu. Once you have logged in.Creating Users with the EMS Administration Tool 79 | Start the Administration Tool and Connect to the EMS Server Start the EMS administration tool as described in Starting the EMS Administration Tool on page 102. TIBCO Enterprise Message Service User’s Guide . If this is the first time you’ve used the EMS administration tool. execute one of the following commands: • If you are using TIBCO Enterprise Message Service on a single computer. On a computer running Windows. connect it to the EMS server.4>Start EMS administration tool. see connect on page 108. After starting the administration tool. type connect in the command line of the Administration tool: > connect You will be prompted for a login name. the screen will display: connected to tcp://localhost:7222 tcp://localhost:7222> • If you are using TIBCO Enterprise Message Service in a network. user command. In the administration tool. refer to create user on TIBCO Enterprise Message Service User’s Guide . use the create user command to create two users: 1.80 | Chapter 4 Getting Started Create Users Once you have connected the administration tool to the server. Enter the commit command. enter: tcp://localhost:7222> create user user1 tcp://localhost:7222> create user user2 The tool will display messages confirming that user1 and created. user2 have been You have now created two users. 2. You can confirm this with the show command: tcp://localhost:7222> show users User Name Description user1 user2 users For more information on the create page 111. For more information on the commit command. Messages placed on a queue by the sender are persistent until read by the receiver. as described in Point-to-Point on page 4. In each command line window. TIBCO Enterprise Message Service User’s Guide . To create a new queue: 1. Enter the commit command to save the queue as a permanent queue. In the administration tool. enter setup to set the environment and classpath: > setup 3. Create a Queue In the point-to-point messaging model. client send messages to and receive messages from a queue. execute the tibjmsMsgConsumer client to direct user2 to read the messages from the message queue: > java tibjmsMsgConsumer -queue myQueue -user user2 The messages placed on the queue are displayed in the receiver’s window. see commit on page 107 and autocommit on page 107. refer to create queue on page 110. In the second command line window. 2. use the create queue named myQueue: queue command to create a new tcp://localhost:7222> create queue myQueue 2. In the first command line window. Open two command line windows and in each window navigate to the /ems/samples/java folder. execute the tibjmsMsgProducer application to direct user1 to place some messages to the myQueue queue: > java tibjmsMsgProducer -queue myQueue -user user1 Hello User2 4.Point-to-Point Messaging Example 81 | Point-to-Point Messaging Example This section demonstrates how to use point-to-point messaging. For more information on the create queue command. Start the Sender and Receiver Clients 1. so you can start the sender and receiver clients in any order. TIBCO Enterprise Message Service User’s Guide . Create a Topic In the publish/subscribe model. For more information on the create topic command. you publish and subscribe to topics. For this exercise. This example is not intended to be comprehensive or representative of a robust application. see commit on page 107 and autocommit on page 107. To execute the client samples. For more information on the commit command. you will execute a message producer client and two message consumer clients that demonstrate the publish/subscribe messaging model described in Publish and Subscribe on page 5. refer to the readme within the sample directory. Enter the commit command to save the topic as a permanent topic. use the create topic named myTopic: topic command to create a new tcp://localhost:7222> create topic myTopic 2. In the administration tool. open three separate command line windows and navigate to the /tibco/ems/samples/java directory in each window.82 | Chapter 4 Getting Started Publish and Subscribe Messaging Example In this section. To create a new topic: 1. For more information on the samples. For more information on compiling the samples. refer to create topic on page 111. refer to Compiling the Sample Clients on page 77. you must give them commands from within the sample directory that contains the compiled samples. Execute the tibjmsMsgConsumer client to assign user1 as a subscriber to the myTopic topic: > java tibjmsMsgConsumer -topic myTopic -user user1 The screen will display a message showing that user2 is subscribed to myTopic. To start user2 as a subscriber: 1. Enter setup to set the environment and classpath: > setup 3. 2. navigate to the /ems/samples/java folder. navigate to the /ems/samples/java folder. Enter setup to set the environment and classpath: > setup 3.Publish and Subscribe Messaging Example 83 | Start the Subscriber Clients You start the subscribers first because they enable you to observe the messages being received when you start the publisher. The command windows do not return to the prompt when the subscribers are running. 2. In the first command line window. To start user1 as a subscriber: 1. Execute the tibjmsMsgConsumer application to assign user2 as a subscriber to the myTopic topic: > java tibjmsMsgConsumer -topic myTopic -user user2 The screen will display a message showing that user2 is subscribed to myTopic. TIBCO Enterprise Message Service User’s Guide . In the second command line window. However. In this example. To start the publisher: 1. Execute the tibjmsMsgProducer client to direct user1 to publish some messages to the myTopic topic: > java tibjmsMsgProducer -topic myTopic -user user1 hello user2 where ’hello’ and ’user2’ are separate messages. while the subscriber requires the name of the topic and the user. Enter setup to set the environment and classpath: > setup 3. TIBCO Enterprise Message Service User’s Guide .84 | Chapter 4 Getting Started Start the Publisher Client and Send Messages Setting up the publisher is very similar to setting up the subscriber. user1 is both a publisher and subscriber. In the third command line window. the publisher also requires messages. the command window for the publisher returns to the prompt for further message publishing. The command line window will display a message stating that both messages have been published: Publishing on topic 'myTopic' Published message: hello Published message: user2 After the messages are published. 2. navigate to the /ems/samples/java folder. you will see an error message. Note that if you attempt to use the form: java tibjmsMsgProducer -topic myTopic -user user1 without adding the messages. reminding you that you must have at least one message text. For more information on the secure property. For more information on topic permissions. all authenticated users have all permissions (publish. see the section about secure on page 48. on page 221. If the secure property is not added to a topic.97C44203CDFA:2} JMSDestination={Topic[myTopic]} JMSReplyTo={null} JMSDeliveryMode={PERSISTENT} JMSRedelivered={false} JMSCorrelationID={null} JMSType={null} JMSTimestamp={Tue Mar 21 12:04:56 PST 2006} JMSExpiration={0} JMSPriority={4} } Properties={} Text={user2} } Create a Secure Topic In this example. only users with publish permission on the topic can publish. while other users cannot publish. Authentication and Permissions.97C44203CDF A:1} JMSDestination={Topic[myTopic]} JMSReplyTo={null} JMSDeliveryMode={PERSISTENT} JMSRedelivered={false} JMSCorrelationID={null} JMSType={null} JMSTimestamp={Tue Mar 21 12:04:56 PST 2006} JMSExpiration={0} JMSPriority={4} } Properties={} Text={hello} } Received message: TextMessage={ Header={ JMSMessageID={ID:EMS-SERVER. you make myTopic into a secure topic and grant user1 permission to publish to the myTopic and user2 permission to subscribe to myTopic.Publish and Subscribe Messaging Example 85 | The first and second command line windows containing the subscribers will show that each subscriber received the two messages: Subscribing to topic: myTopic Received message: TextMessage={ Header={ JMSMessageID={ID:EMS-SERVER. Add the secure Property to the Topic When the secure property is added to a topic. subscribe. only users who have been assigned a certain permission can perform the actions allowed by that permission. For example. create durable subscribers) on that topic. TIBCO Enterprise Message Service User’s Guide . see Chapter 8. as described in Start the Publisher Client and Send Messages on page 84. You can now start user1 as the publisher and send messages to user2. do the following steps: 1. refer to grant topic on should start as a subscriber in the same manner as before. enter Control-C to stop each subscriber. Enter the commit command to save the permissions. use the set authorization property: server command to enable the tcp://localhost:7222> set server authorization=enabled The authorization property enables checking of permissions set on destinations. In the administration tool. 2. Start the Subscriber and Publisher Clients Start the subscribers. In each subscriber window. but not to subscribe. User2 topic command. As a result. grant publish permission to user1 and subscribe permission to the user2. 3. Grant Topic Access Permissions to Users To see how permissions affect the ability to publish and receive messages. Note that you cannot start user1 as a subscriber because user1 has permission to publish. For more information on the addprop topic command.86 | Chapter 4 Getting Started To enable server authorization and add the secure property to a topic. Enter the following command to add the secure property to a topic named myTopic: tcp://localhost:7222> addprop topic myTopic secure For more information on the set server command. as described in Start the Subscriber Clients on page 83. In the administration tool. For more information on the grant page 117. refer to set server on page 123. Use the grant myTopic: topic command to grant permissions to users on the topic 1. enter: tcp://localhost:7222> grant topic myTopic user1 publish tcp://localhost:7222> grant topic myTopic user2 subscribe 2. TIBCO Enterprise Message Service User’s Guide . you receive an exception message including the statement: Operation not permitted. refer to addprop topic on page 107. In the subscriber window. 2. you create a durable subscriber that stores messages published to topic myTopic on the EMS server. enter Control-C to stop the subscriber. Enter Control-C to stop the subscriber and then unsubscribe the durable subscription: > java tibjmsDurable -unsubscribe The subscriber is no longer durable and any additional messages published to the myTopic topic are lost. Execute the tibjmsDurable application to assign user2 as a durable subscriber to the myTopic topic: > java tibjmsDurable -topic myTopic -user user2 4. 8. TIBCO Enterprise Message Service User’s Guide . use the show durables command to confirm that user2 is a durable subscriber to myTopic: tcp://localhost:7222> show durables Topic Name Durable User * myTopic subscriber user2 Msgs 0 Size 0. To start user2 as a durable subscriber: 1. 6.0 Kb 5. where subscriptions are stored on the server and subscribers can receive messages even if it was inactive when the message was originally delivered. In the a command line window. Enter setup to set the environment and classpath: > setup 3. If messages are published when the subscriber is not available. navigate to the /ems/samples/java folder. In this example. You can create durable subscriptions. by default. In the administration tool. as described in Start the Publisher Client and Send Messages on page 84: > java tibjmsMsgProducer -topic myTopic -user user1 hello user2 7. the subscriber does not receive those messages.Publish and Subscribe Messaging Example 87 | Create a Durable Subscriber As described in Publish and Subscribe on page 5. Restart the subscriber: > java tibjmsDurable -topic myTopic -user user2 The stored messages are displayed in the subscriber window. In another command line window. execute the tibjmsMsgProducer client. only receive messages when they are active. subscribers. 88 | Chapter 4 Getting Started TIBCO Enterprise Message Service User’s Guide . page 90 emsntsreg. the TIBCO Enterprise Message Service Server must be running. page 92 Security Considerations. The server implements all types of message persistence and no messages are stored on the client side.| 89 Chapter 5 Running the EMS Server To use TIBCO Enterprise Message Service with your applications. page 98 TIBCO Enterprise Message Service User’s Guide . Topics • • • • Starting and Stopping the EMS Server. page 94 How EMS Manages Access to Shared Store Files. The server and the clients work together to implement TIBCO Enterprise Message Service. Navigate to the /ems/bin subdirectory (or include /ems/bin in your PATH) 2.conf on page 157 for more information about configuration parameters and more information about each parameter Table 10 tibemsd Options Option -config Description config file name config file name is the name of the main configuration file for tibemsd server. Turns on tracing of SSL connections.conf. see Tracing on the Server on page 349. Default is tibemsd.conf. string -ssl_password -ssl_trace Private key password. The value has the same format as the value of log_trace parameter specified with set server command of the administration tool.90 | Chapter 5 Running the EMS Server Starting and Stopping the EMS Server This section describes how to start and stop the EMS server. See tibemsd.4>Start EMS Server To start the EMS server from the command line: 1. -trace items Specifies the trace items. Type tibemsd [options] where options are described in Table 10. Starting the EMS Server On a computer running Microsoft Windows. These items are not stored in the configuration file. URL of the active server. following the path: Programs>TIBCO Enterprise Message Service 4. The command options to tibemsd are similar to the parameters you specify in tibemsd. -ssl_debug_trace -ft_active active_url TIBCO Enterprise Message Service User’s Guide . it will become the active server. it will act as a backup server. you can start the EMS server from the Start menu. If this server can connect to the active server. If this server cannot connect to the active server. Print the certificates loaded by the server and do more detailed tracing of SSL-related situation. and the command options override any value specified in the parameters. in seconds. Activation interval (maximum length of time between heartbeat signals) which indicates that active server has failed. Default is 3.Starting and Stopping the EMS Server 91 | Table 10 tibemsd Options (Cont’d) Option -ft_heartbeat -ft_activation Description seconds seconds Heartbeat signal for the active server. TIBCO Enterprise Message Service User’s Guide . Stopping the EMS Server You can stop the EMS server by means of the shutdown command from the EMS Administration Tool. Set in seconds: default is 10. This interval should be set to at least twice the heartbeat interval. and must be tibemsd. Supply command line arguments to tibemsd. Insert or remove a service with this base name. you can use this suffix to distinguish between them in the Windows services applet. this parameter is optional. This utility facilitates registry. register a new service). Optional with /i. Syntax emsntsreg /i [/a] service_name directory [arguments] [suffix] emsntsreg /r [service_name] [suffix] Remarks Some situations require the EMS server to start automatically. Automatically start the new service. it must be tibemsd. When inserting a service. However. You can satisfy this requirement by registering the server daemon with the Windows service manager.92 | Chapter 5 Running the EMS Server emsntsreg Utility Purpose Register or unregister the EMS server daemon as a Windows service. /r TIBCO Enterprise Message Service User’s Guide . Remove a service from the registry. You must have administrator privileges to change the Windows registry. 2000 and XP). suffix When registering more than one tibemsd service. This command does not support space characters in directory paths or file names. Optional with /i. this parameter is required. Optional. if it is present. Restrictions Location Locate this utility program as an executable file in the EMS bin directory. When removing a service. Description Insert a new service in the registry (that is. Enclose the entire arguments string in double quote characters. Parameter /i /a service_name directory arguments Use this directory pathname to locate the tibemsd executable. Required. This utility applies only to Microsoft Windows (all supported versions. including NT. you must avoid configuration conflicts. For example. you must also supply the service_name. For EMS services. the service process finds the directory containing the main configuration file (tibemsd. Command Summary Windows Services Applet To view a command line summary. it must be tibemsd. it also displays this additional information: • • The suffix (if you supply one) The process ID (PID)—when the service is running TIBCO Enterprise Message Service User’s Guide . When you register several EMS services. In this example. emsntsreg /i tibemsd C:\tibco\ems\bin "-config C:\tibco\ems\7222\tibemsd. • Remove To unregister a service. and creates all secondary configuration files in that directory. In this example. the utility removes the service named tibemsd. two instances of tibemsd cannot listen on the same port.conf" 7222 emsntsreg /i tibemsd C:\tibco\ems\bin "-config C:\tibco\ems\7223\tibemsd. run the utility with this command line: emsntsreg The Windows services applet displays the name of each registered service.conf" 7223 Notice these aspects of this example: • When you supply a -config argument.conf).emsntsreg 93 | Register To register tibemsd as a Windows service. run the utility with this command line: emsntsreg /r [service_name] [suffix] Both parameters are optional. If the service_name is present. the numerical suffix and the configuration directory both reflect the port number that the service uses. To supply the suffix parameter. run the utility with this command line: emsntsreg /i [/a] tibemsd directory [arguments] [suffix] Example 1 This simple example registers one service: emsntsreg /i tibemsd C:\tibco\ems\bin Example 2 This example registers a service with command line arguments: emsntsreg /i tibemsd C:\tibco\ems\bin "-trace DEFAULT" Example 3 This pair of example commands registers two services with different configuration files. When both parameters are absent. each service uses a different configuration directory. you must properly configure all three of these items: • • • The server’s authorization parameter (see Authorization Parameter. Secure Environment To ensure secure deployment. Benign Environment Only authorized administrators have physical access or • • domain access. you must enable this parameter. topics and queues).94 | Chapter 5 Running the EMS Server Security Considerations This section highlights information relevant to secure deployment. EMS administration must meet the following criteria: • • Correct Installation EMS is correctly installed and configured. its configuration files. Destination Security Three interacting factors affect the security of destinations (that is. file system and network protocols ensure domain separation for EMS. LDAP servers. The default value of this parameter is disabled—the server does not check any permissions. In a secure deployment. TIBCO Enterprise Message Service User’s Guide . etc. Domain Control The operating system. below) The secure property of individual destinations (see secure on page 48) The ACL permissions that apply to individual destinations (see Authentication and Permissions on page 221) Authorization Parameter The server’s authorization parameter acts as a master switch for checking permissions for connection requests and operations on secure destinations. and allows all operations. to prevent unauthorized access to the server. For secure deployment. Only authorized administrators have access. Physical Controls The computers where EMS is installed are located in areas where physical entry is controlled to prevent unauthorized access. We recommend that all administrators read this section. and they cooperate in a benign environment. and those administrators cooperate in a benign environment. create a user with the name anonymous and no password. this feature (anonymous user connections) is outside the tested configuration of EMS security certification. Individual topics and queues can still be secure. For more information on destination security. the user admin can connect without a password. the server always requires it. the server does not check user authentication. The form of authentication can be either an X. TIBCO Enterprise Message Service User’s Guide . Creating the user anonymous does not mean that anonymous has all permissions. Once the administrator password has been set. Connection Security When authorization is enabled. the server requires a name and password before users can connect. the administrator must change the admin password immediately after installation. Nonetheless. see Assign a Password to the Administrator on page 104. all user connections are allowed.Security Considerations 95 | Admin Password For ease in installation and initial testing. To configure a secure deployment. the default setting for the admin password is no password at all. which do not require password authorization. The user anonymous can access only non-secure destinations.509 certificate or a username and password (or both). When authorization is disabled. Even when authorization is enabled. Only authenticated users can connect to the server. the user admin must still supply the correct password to connect to the server. refer to the destination property secure on page 48. the administrator (admin) may explicitly allow anonymous user connections. Until you set an actual password. However. even when authorization is disabled. and the ability to use these destinations (either sending or receiving) is controlled by the access control list of permissions for those destinations. and Create Users on page 80. To allow these connections. External data from and LDAP. and at least one punctuation character. see Using the SSL Protocol on page 365. at least one numeric character. EMS software does not automatically enforce such standards for passwords. with at least one upper case character. neither of these are part of the EMS product. To ensure a secure deployment. SSL communication requires software to implement SSL on both server and client. For security equivalent to single DES (an industry minimum). You must enforce such policies within your organization. you must explicitly configure SSL within EMS. C client programs can use the OpenSSL library shipped with EMS. TIBCO Enterprise Message Service User’s Guide . The server can use two sources of secure password authentication data: • • Local data from the EMS configuration files.96 | Chapter 5 Running the EMS Server Communication Security For communication security between servers and clients. See ssl_server_trusted on page 191. security experts recommend passwords that contain 8–14 characters. Java client programs must use either JSSE (part of the Java environment) or separately purchased SSL software from Entrust. Sources of Authentication Data The server uses only one source of X. Timestamp The administration tool can either include or omit a timestamp associated with the output of each command. You must safeguard the security of EMS configuration files and LDAP servers. and between servers and other servers. you must explicitly enable the timestamp feature. namely. We recommend enforcing strong standards for passwords.509 certificate authentication data. the server parameter ssl_server_trusted (its value is set in EMS an configuration file). The EMS server includes the OpenSSL implementation. Use the following administration tool command: time on Passwords Passwords are a significant point of vulnerability for any enterprise. so all administrative operations produce audit output. For further details. TIBCO Enterprise Message Service User’s Guide . The DEFAULT setting includes +ADMIN.Security Considerations 97 | Audit Trace Logs Audit information is output to log files (and stderr). Audit information in log files is always timestamped. Server tracing options. on page 350. and is configured by the server parameters log_trace and console_trace (see Tracing and Log File Parameters on page 183). see Table 61. Administrators can read and print the log files for audit review using tools (such as text editors) commonly available within all IT environments. EMS software does not include a special tool for audit review. l_type = F_WRLCK. Windows On Windows platforms. On UNIX platforms.98 | Chapter 5 Running the EMS Server How EMS Manages Access to Shared Store Files To prevent two EMS servers from using the same store file.l_whence = 0.l_len = 0. servers use the standard fcntl operating system call to implement cooperative file locking: struct flock fl.l_start = 0. we recommend checking the operating system documentation for this call. since UNIX variants differ in their implementations. fl. fl. TIBCO Enterprise Message Service User’s Guide . err = fcntl(file. This section describes how EMS manages locked store files. UNIX To ensure correct locking. fl. int err. servers use the standard Windows CreateFile function. fl. &fl). each server restricts access to its store file for the duration of the server process. F_SETLK. supplying FILE_SHARE_READ as the dwShareMode (third parameter position) to restrict access to other servers. | 99 TIBCO Enterprise Message Service User’s Guide . 100 | Chapter 5 Running the EMS Server TIBCO Enterprise Message Service User’s Guide . Topics • • • Starting the EMS Administration Tool.| 101 Chapter 6 Using the EMS Administration Tool This chapter gives an overview of commands and use in the administration tool for TIBCO Enterprise Message Service. page 105 Command Listing. page 106 TIBCO Enterprise Message Service User’s Guide . page 102 Naming Conventions. Use this user name to connect to server. Ignore errors when executing script file.exe on Windows platforms. Line breaks within the file delimit each command. On a computer running Windows. Table 11 lists options for tibemsadmin. Any valid tibemsadmin command described in this chapter can be executed. Type tibemsadmin -help to display information about tibemsadmin startup parameters. Use this password to connect to server. Running the EMS Server. All tibemsadmin parameters are optional. you can also start the administration tool from the Start menu.4>Start EMS administration tool. or -h script-file -script -server -user server-url Connect to specified server. The EMS server must be started as described in Chapter 5. Execute the specified text file containing tibemsadmin commands then quit. That is.102 | Chapter 6 Using the EMS Administration Tool Starting the EMS Administration Tool The EMS Administration Tool is located in your installation_path /bin directory and is a stand-alone executable named tibemsadmin on UNIX and tibemsadmin. and each command is separated by a line break. user-name password -password -ignore TIBCO Enterprise Message Service User’s Guide . every command must be contained on a single line (no line breaks within the command). following the path Programs>TIBCO Enterprise Message Service 4. Table 11 tibemsadmin Options Option -help Description Print the help screen. This parameter only ignores errors in command execution but not syntax errors in the script. on page 89 before you start the EMS Administration Tool. Do not verify hostname against the name on the certificate. Mangled string in the output can be set as a value of server password or server SSL password in the server configuration file. which is useful for debugging. If the password is not entered it is prompted for. File containing trusted certificate(s). and the private key. Private key or PKCS#12 password. Show additional tracing. Show loaded certificates and certificates sent by the host. File containing client certificate and (optionally) extra issuer certificate(s). -ssl_trusted filename -ssl_identity filename -ssl_issuer filename -ssl_password password -ssl_noverifyhostname -ssl_hostname name -ssl_trace -ssl_debug_trace TIBCO Enterprise Message Service User’s Guide . This parameter may be entered more than once if required. Name expected in the certificate sent by the host. File containing extra issuer certificate(s) for client-side identity. it will be prompted for. but has not been specified.Starting the EMS Administration Tool 103 | Table 11 tibemsadmin Options (Cont’d) Option -mangle [password] Description Mangle the password and quit. If the password is required. Examples tibemsadmin -server "tcp://host:7222" tibemsadmin -server "tcp://host:7222" -user admin -password secret Some options are needed when you choose to make a SSL connection. The user name and password entered on one command line are not reused with subsequent connect commands entered in the script file or interactively. the administration tool now requires your password before connecting to the server. 2. For more information on SSL connections. Assign a Password to the Administrator 1. refer to set password on page 122. Using the SSL Protocol. For further information about setting and resetting passwords. To protect access to the server configuration. TIBCO Enterprise Message Service User’s Guide . When You First Start tibemsadmin The administration tool has a default user with the name admin. It is only used to connect to the server specified in the same command line.104 | Chapter 6 Using the EMS Administration Tool When a command specifies -user and -password. page 365. you must assign a password to the user admin. Log in and connect to the administration tool. refer to Chapter 14. This is the default user for logging in to the administration tool. Use the set password command to change the password: set password admin password When you restart the administration tool and type connect. that information is not stored for later use. as described directly above. • Dot separates elements within a destination name (foo. "description field"). and cannot be used in names except as wildcards. topics or queues: • • • • $ is illegal at the beginning of the queue or topic names—but legal at the beginning of user and group names. see Wildcards on page 63. A user name cannot contain colon (":") character. Space characters are permitted in a description field—if the entire description field is enclosed in double quotes (for example.*) and can be used only for that purpose. groups. TIBCO Enterprise Message Service User’s Guide .bar. Both * and > are wildcards.Naming Conventions 105 | Naming Conventions These rules apply when naming users. For more information about wildcards. . See factories. SSL commands are listed in several tables in Chapter 14. Many of the commands listed below accept arguments that specify the names of users.. Property names are separated by spaces.] Add one or more users to the group. topics or queues..pem ssl_trusted=cert2. TIBCO Enterprise Message Service User’s Guide . addprop factory addprop factory factory-name properties .user3.. Property names are separated by commas. Adds properties to the queue. see Destination Properties on page 46. For information on properties that can be assigned to queues. Using the SSL Protocol. see Administration Commands and External Users and Groups on page 236. For information about the syntax and naming conventions that apply to these names. Adds properties to the factory.user2. User names that are not already defined are added to the group as external users.106 | Chapter 6 Using the EMS Administration Tool Command Listing The command line interface of the administration tool allows you to perform a variety of functions. groups.... The following is an alphabetical listing of the commands including command syntax and a description of each command.. An example is: addprop factory MyTopicFactory ssl_trusted=cert1.pem ssl_verify_host=disabled addprop queue addprop queue queue-name properties. see Naming Conventions on page 105.conf on page 208 for the list of factory properties. add member add member group_name user_name [. on page 365. Note that SSL commands are not listed in this table. see Configuring Routes and Zones on page 410.. see Destination Properties on page 46. For route properties. the EMS server acts on each admin command immediately making it part of the configuration. For information on properties that can be assigned to topics.. commit commit Commits all configuration changes into files on disk. The autocommit feature only determines when the configuration is written to the files. the changes made to the configuration files are automatically saved to disk after each command.conf on page 206. Entering autocommit without parameters displays the current setting of autocommit (on or off). autocommit autocommit [on|off] When autocommit is set to on. Destination (topic and queue) properties must be separated by commas but properties of routes and factories are separated with spaces.. see routes.conf. you must manually use the commit command to save configuration changes to the disk. TIBCO Enterprise Message Service User’s Guide . Adds properties to the topic.. Regardless of the autocommit setting. By default. autocommit is set to on when interactively issuing commands..] Adds properties to the route. You can set the zone_name and zone_type parameters when creating a route. addprop topic addprop topic topic_name properties. but you cannot subsequently change them. Property names are separated by commas. For the configuration file routes. When autocommit is set to off.Command Listing 107 | addprop route addprop route route-name prop=value[ prop-value. or asynchronous. which specifies no time limit.108 | Chapter 6 Using the EMS Administration Tool compact compact store_type [max_time] Compacts the database store files. Any administrator can connect. connect connect [server-url {admin|user_name} password] Connects the administration tool to the server. server-url is usually in the form: protocol://host-name:port-number for example: tcp://myhost:7222 The protocol can be tcp or ssl. • • To compact the asynchronous file. you may specify a time limit (in seconds). the user is prompted to enter a user name and password. sync. the default is zero. or any user that has administrator permissions enabled. and the administration tool asks for confirmation. or only the password. any user in the $admin group. When the time limit is absent. async. See Administrator Permissions on page 223 for more information about administrator permissions. specify either a. and it blocks other database operations. If a user name or password are not provided. TIBCO Enterprise Message Service User’s Guide . You can enter connect with no other options and the administrative tool tries to connect to the local server on the default port. or synchronous. if the user name was already specified in the command. To compact the synchronous file. Since compaction can be a lengthy operation. Zero is a special value. We recommend compacting the database store files only when the database Used Space usage is 30% or less (see show db on page 137). which is 7222. specify either s. An administrator is either the admin user. the group is empty. or creates an alternate JNDI name for a topic that already has a JNDI name.. For descriptions of factory parameters. You can use the add to the group. For descriptions of parameters and properties. create factory create factory factory_name factory_parameters Creates a new connection factory. see durables. Initially.. and information about conflict situations.conf on page 216. see bridges.Command Listing 109 | create bridge create bridge source=type:dest_name target=type:dest_name [selector=selector] Creates a bridge between destinations. For further information. create group create group group_name "description" Creates a new group of users. type is either topic or queue. member command to add users create jndiname create jndiname new_jndiname topic|queue|jndiname name Creates a JNDI name for a topic or queue.conf on page 205. create durable create durable topic-name durable-name [property. see factories.property] Creates a static durable subscriber. For example: create FOO jndiname BAR will create new JNDI name FOO referring the same object referred by JNDI name BAR TIBCO Enterprise Message Service User’s Guide . .conf on page 208. . ] Creates a route. but you cannot subsequently change them. The route properties are listed in routes. TIBCO Enterprise Message Service User’s Guide . Properties are listed in a comma-separated list. The local server connects to the destination server at the specified URL. create route create route name url=URL [properties . The possible queue properties are described in Destination Properties on page 46.conf on page 203. You can set the zone_name and zone_type parameters when creating a route.conf on page 206 and are specified as a space-separated list of parameter name and value pairs. this command promotes it to an active-active route.. The name must be the name of the other server to which the route connects. If a passive route with the specified name already exists.. you may specify the URL as a comma-separated list of URLs. If you have configured fault-tolerant servers. as described in queues.110 | Chapter 6 Using the EMS Administration Tool create queue create queue queue_name [properties] Creates a queue with the specified name and properties. see Active and Passive Routes on page 409. For additional information on route parameters. see Configuring Routes and Zones on page 410. The password is optional and can be added later using the set password command. they must be included around the name. as described in topics. Properties are listed in a comma-separated list. name — the name of the RVCM listener to which topic messages are to be exported. create topic create topic topic_name [properties] Creates a topic with specified name and properties. you can add an optional description of the user in quotes. The parameters are: • transportName — the name of the transport to which this RVCM listener applies.conf on page 215 and Rendezvous Certified Messaging (RVCM) Parameters on page 303. User names cannot contain colon (:) characters. create user create user user_name ["user_description"] [password=password] Creates a new user. See Destination Properties on page 46 for the list of properties. This causes the server to perform the TIBCO Rendezvous call tibrvcmTransport_AddListener.Command Listing 111 | create rvcmlistener create rvcmlistener [transportName] name subject Registers an RVCM listener with the server so that any messages forwarded through a tibrvcm transport (including the first message sent) are guaranteed for the specified listener. TIBCO Enterprise Message Service User’s Guide .conf on page 202. subject — the RVCM subject name that messages are published to. see tibrvcm. Note that the square brackets [ ] DO NOT indicate that the transport name is an option. This should be the same name as the topic names that specify the export property. • • For more information. Following the user name. 112 | Chapter 6 Using the EMS Administration Tool delete all delete all users|groups|topics|queues|durables [topic-name-pattern|queue-name-pattern] If used as delete all users|groups|topics|queues|durables without the optional parameters. delete factory delete factory factory-name Delete the named connection factory. If used with a topic or queue. topics. The connection ID is shown in the first column of the connection description printed by show connection. delete connection delete connection connection-id Delete the named connection for the client. type is either topic or queue. or queues (as chosen). delete durable delete durable durable-name Delete the named durable subscriber. See Destination Bridges on page 68 for more information on bridges. Conflicting Specifications on page 217. such as: delete all topics|queues topic-name-pattern|queue-name-pattern the command deletes all topics and queues that match the topic or queue name pattern. the command deletes all users. TIBCO Enterprise Message Service User’s Guide . and the optional parameters. delete bridge delete bridge source=type:dest_name target=type:dest_name Delete the bridge between the specified source and target destinations. See also. groups. delete jndiname delete jndiname jndiname Delete the named JNDI name. Using the EMS Implementation of JNDI. delete message delete message messageID Delete the message with the specified message ID. delete route delete route route-name Delete the named route. TIBCO Enterprise Message Service User’s Guide .Command Listing 113 | delete group delete group group-name Delete the named group. delete queue delete queue queue-name Delete the named queue. Notice that deleting the last JNDI name of a connection factory object will remove the connection factory object as well. on page 287 for more information. See Chapter 10. • • For more information. This causes the server to perform the TIBCO Rendezvous call tibrvcmTransport_RemoveListener. Note that the square brackets [ ] DO NOT indicate that the transport name is an option. The parameters are: • transportName — the name of the transport to which this RVCM listener applies. they must be included around the name. delete topic delete topic topic-name Delete the named topic. TIBCO Enterprise Message Service User’s Guide . disconnect disconnect Disconnect the administrative tool from the server. delete user delete user user-name Delete the named user. subject — the RVCM subject name that messages are published to. name — the name of the RVCM listener to which topic messages are exported.conf on page 215 and Rendezvous Certified Messaging (RVCM) Parameters on page 303.114 | Chapter 6 Using the EMS Administration Tool delete rvcmlistener delete rvcmlistener [transport] name subject Unregister an RVCM listener with the server so that any messages being held for the specified listener in the RVCM ledger are released. see tibrvcm. This should be the same name as the topic names that specify the export property. Choosing the parameter on or off in this command controls echo. it displays the current echo setting (on or off). In this case. the administrative tool report also contains a record of successful command execution. If echo is entered in the command line without a parameter. q. end) Exit the administration tool. bye. The administrator may choose the exit command when there are changes in the configuration have which have not been committed to disk. the system will prompt the administrator to use the commit command before exiting. The default setting for echo is on. When echo is on. TIBCO Enterprise Message Service User’s Guide . This command is used primarily for scripts. exit exit (aliases: quit.Command Listing 115 | echo echo [on|off] Echo controls the reports that are printed into the standard output. When echo is off the administrative tool only prints errors and the output of queries. User permissions are: • • • receive send browse For more information on queue permissions.116 | Chapter 6 Using the EMS Administration Tool grant queue grant queue queue-name user=name | group=name permissions Grants specified permissions to specified user or group on specified queue. then a user name. Multiple permissions are separated by commas. Enter all in the permissions string if you choose to grant all possible user permissions. TIBCO Enterprise Message Service User’s Guide . see Destination-Level Permissions on page 228. see Table 40 in User Permissions on page 239. The name following the topic name is first checked to be a group name. The following are administrator permissions for queues. Destination-level administrator permissions can also be granted with this command. • • • • • view create delete modify purge For more information on destination permissions. Specified permissions are added to any existing permissions. Specified permissions are added to any existing permissions. For a complete listing of global administrator permissions. see Destination-Level Permissions on page 228. • • • • • view create delete modify purge For more information on destination permissions.Command Listing 117 | grant topic grant topic topic-name user=name | group=name permissions Grants specified permissions to specified user or group on specified topic. The name following the topic name is first checked to be a group name. see Table 41 in User Permissions on page 239. see Global Administrator Permissions on page 226. grant admin grant admin user=name | group=name admin_permissions Grant the named global administrator permissions to the named user or group. Multiple permissions are separated by commas. Topic permissions are: • • • • subscribe publish durable use_durable For more information on topic permissions. Enter all in the permissions string if you choose to grant all possible permissions. The following are administrator permissions for topics. Destination-level administrator permissions can also be granted with this command. then a user name. TIBCO Enterprise Message Service User’s Guide . When used with the pattern parameter.*). Enter help commands for a command summary. When used with the pattern parameter. purge all queues purge all queues [pattern] Purge all or selected queues.*). purge durable purge durable durable-name Purge all messages in the topic for the named durable subscriber TIBCO Enterprise Message Service User’s Guide . Enter help command for help on a specific command. When used without the optional pattern parameter. When used without the optional pattern parameter. this command erases all messages in all queues for all receivers. this command erases all messages in all queues that fit the pattern (for example: foo. this command erases all messages in all topics for all subscribers. info info (alias: i) Shows server name and information about the connected server. purge all topics purge all topics [pattern] Purge all or selected topics.118 | Chapter 6 help Using the EMS Administration Tool help (aliases: h. ?) Display help information. this command erases all messages in all topics that fit the pattern (for example: foo. TIBCO Enterprise Message Service User’s Guide .. see Configuring Routes and Zones on page 410.conf.conf on page 206.. see routes..Command Listing 119 | purge queue purge queue queue-name Purge all messages in the named queue. You can set the zone_name and zone_type parameters when creating a route. remove member remove member group-name user-name[. For the configuration file routes. removeprop route removeprop route route-name properties Remove the named properties from the named route. but you cannot subsequently change them. For route parameters.user3.] Remove one or more named users from the named group. You cannot remove the URL.user2. removeprop queue removeprop queue queue-name properties Remove the named properties from the named queue. purge topic purge topic topic-name Purge all messages for all subscribers on the named topic. removeprop factory removeprop factory factory-name properties Remove the named properties from the named factory. revoke admin revoke admin user=name | group=name permissions Revoke the specified global administrator permissions from the named user or group. Administrator permissions for queues are view. all user-level permissions on this queue are removed. You can use the optional admin parameter to revoke all administrative permissions. and all. delete. TIBCO Enterprise Message Service User’s Guide . or the both parameter to revoke all user-level and administrative permissions on the queue. modify. See Chapter 8.120 | Chapter 6 Using the EMS Administration Tool removeprop topic removeprop topic topic-name properties Remove the named properties from the named topic. User and group permissions for queues are receive. For more information. see Chapter 8. on page 221 for more information about administrator permissions. Authentication and Permissions. browse. If you specify an asterisk (*). create. and purge. revoke queue revoke queue queue-name user=name | group=name permissions revoke queue queue-name * [user | admin | both] Revoke the specified permissions from a user or group for the named queue. Authentication and Permissions. send. on page 221. and all. if the log file name is tibems. User and group permissions for topics are subscribe. publish. For more information.1 and tibems. use_durable. If you specify an asterisk (*). create. or the both parameter to revoke all user-level and administrative permissions on the topic.log and there is already a tibems. For example. rotatelog rotatelog Force the current log file to be backed up and truncated. The backup file name is the same as the current log file name with a sequence number appended to the filename. all user-level permissions on this topic are removed.log. see Chapter 8.log.log. modify. The server queries the current log file directory and determines what the highest sequence number is. The server starts writing entries to the newly empty log file. the server names the next backup tibems. on page 221. Administrator permissions for topics are view. Authentication and Permissions. TIBCO Enterprise Message Service User’s Guide . durable. and purge. then chooses the next highest sequence number for the new backup name.2. delete.3. You can use the optional admin parameter to revoke all administrative permissions.Command Listing 121 | revoke topic revoke topic topic-name user=name | group=name permissions revoke topic topic-name * [user | admin | both] Revoke the specified permissions from a user or group for the named topic. type: set password user-name Type a new password at the prompt. security experts recommend passwords that contain 8–14 characters. and at least one punctuation character. use this command without supplying a password. the server prompts you to type one. and press the Enter key at the prompt (without typing a password). If you do not supply a password in the command. TIBCO Enterprise Message Service User’s Guide . with at least one upper case character. For security equivalent to single DES (an industry minimum). at least one numeric character. Passwords are a significant point of vulnerability for any enterprise. • To remove a password.122 | Chapter 6 Using the EMS Administration Tool set password set password user-name [password] Set the password for the named user. • To reset a password. We recommend enforcing strong standards for passwords. After a transition from disabled to enabled.. While the server requires valid authentication for existing producers and consumers. it denies access to users without valid prior authentication. Table 12 Set server parameters (Sheet 1 of 6) Parameter password[=string] Description Sets server password used by the server to connect to other routed servers. the server checks ACL permissions for all subsequent requests. it does not retroactively reauthenticate them. Entered value will be stored in the main server configuration file in mangled form (but not encrypted). enter the empty string twice at the prompt.conf file. Multiple parameters are separated by spaces. Table 12 describes the parameters you can set with this command. If the value is omitted it is prompted for by the administration tool. TIBCO Enterprise Message Service User’s Guide .Command Listing 123 | set server set server parameter=value [parameter=value .. authorization=enabled|disabled Sets the authorization mode in the tibemsd.] The set server command can control many parameters. To reset this password. see Table 61. log_trace=ACL The next example sets the trace log to show all default trace messages. on page 350. - Examples The following example sets the trace log to only show messages about access control violations. You may specify trace options in three forms: • plain A trace option without a prefix character replaces any existing trace options. the values are stored but have no effect.removes the option from the current set of trace options. log_trace=DEFAULT. For a list of trace options and their meanings. but ADMIN messages are not shown.124 | Chapter 6 Using the EMS Administration Tool Table 12 Set server parameters (Sheet 2 of 6) Parameter log_trace=trace-items Description Sets the trace preference on the file defined by the logfile parameter. + • • A trace option preceded by + adds the option to the current set of trace options. Server tracing options. If logfile is not set. The value of this parameter is a comma-separated list of trace options. in addition to SSL messages.-ADMIN.+SSL TIBCO Enterprise Message Service User’s Guide . A trace option preceded by . The values are the same as for log_trace. Setting this parameter using the administration tool does not change its value in the configuration file tibemsd. This type of tracing does not require restarting the client program. When the filter and value clause is absent. The server sends trace output to location. which may be either stderr (the default) or stdout. When this property is enabled. the server generates trace output for opening or closing a connection. message activity. You can specify a filter to selectively trace specific connections.Command Listing 125 | Table 12 Set server parameters (Sheet 3 of 6) Parameter console_trace=console-trace-items Description Sets trace options for output to stderr. The filter can be user. Examples This example sends a trace message to the console when a TIBCO Rendezvous advisory message arrives. console_trace=RVADV client_trace={enabled|disabled} [target=location] [filter=value] Administrators can trace a connection or group of connections. connid or clientid.conf. TIBCO Enterprise Message Service User’s Guide . the default behavior is to trace all connections. and transaction activity. The value can be a user name or ID (as appropriate to the filter). However. console tracing is independent of log file tracing. overriding the trace settings. you can stop console output by specifying: console_trace=-DEFAULT Note that important error messages (and some other messages) are always output. If logfile is defined. Enables or disables tracking messages by MessageID. Sets private key or PKCS#12 file password used by the server to decrypt the content of the server identity file. Password stored in mangled form. Specify units as KB. Sets private key or PKCS#12 file password used by the server to decrypt the content of the FT identity file. track_message_ids=enabled|disabled track_correlation_ids=enabled|disabled ssl_password[=string] ft_ssl_password[=string] This sets a password for SSL use with Fault Tolerance. see max_msg_memory in tibemsd. TIBCO Enterprise Message Service User’s Guide . Enables or disables tracking messages by CorrelationID. msg_swapping=enabled|disabled Enables or disables the ability to swap messages to disk. Lowering this value will not immediately free memory occupied by messages. This sets a password for SSL use only. Password stored in mangled form. MB or GB.conf on page 157.126 | Chapter 6 Using the EMS Administration Tool Table 12 Set server parameters (Sheet 4 of 6) Parameter max_msg_memory=value Description Maximum memory the server can use for messages. indicating no limit. For a complete description. Zero is a special value. The minimum value is 8MB. destinations. destinations. statistics=enabled|disabled Enables or disables statistic gathering for producers. Detailed statistic tracking is only appropriate for routes. By default. consumers. This parameter can be set to any positive integer greater than zero. statistics for each destination are kept for the object. Specifies which objects should have detailed statistic tracking. and routes. Setting this parameter to zero disables the average calculation. When detailed tracking is enabled. this parameter is set to 1. this parameter is set to 3 seconds. producers that specify no destination. Overall server statistics are always gathered. or consumers that specify wildcard destinations. You can specify any combination of PRODUCERS.CONSUMERS. CONSUMERS. By default this parameter is set to disabled.Command Listing 127 | Table 12 Set server parameters (Sheet 5 of 6) Parameter server_rate_interval=num Description Sets the interval (in seconds) over which overall server statistics are averaged. rate_interval=num Sets the interval (in seconds) over which statistics for routes.ROUTES TIBCO Enterprise Message Service User’s Guide . and consumers are averaged. or ROUTES to enable tracking for each object. so this parameter cannot be set to zero. Setting this parameter allows you to average message rates and message size over the specified interval. Setting this parameter to NONE disabled detailed statistic tracking. detailed_statistics=NONE | PRODUCERS. By default. If you specify more than one type of detailed tracking. producers. separate each item with a comma. Disabling statistic gathering resets the total statistics for each object to zero. Multiple properties are separated by commas. If no units are specified.. If statistics are deleted and memory becomes available... overriding any existing properties. Any properties on a queue that are not explicitly specified by this command are removed. the server resumes detailed statistic gathering. or GB as the units.128 | Chapter 6 Using the EMS Administration Tool Table 12 Set server parameters (Sheet 6 of 6) Parameter statistics_cleanup_interval=num Description Specifies how long (in seconds) the server should keep detailed statistics if the destination has no activity. setprop queue setprop queue queue-name properties. Set the properties for a queue. Multiple properties are separated by spaces. When the specified interval is reached. . overriding any existing properties.. See Destination Properties on page 46 for the list of the properties that can be set for a queue. TIBCO Enterprise Message Service User’s Guide . Set the properties for a connection factory. max_stat_memory=num setprop factory setprop factory factory-name properties . MB. Once the maximum memory limit is reached. otherwise you can specify the amount using KB. See Connection Factory Properties on page 210 for the list of the properties that can be set for a connection factory. This is useful for controlling the amount of memory used by detailed statistic tracking. statistics for destinations with no activity are deleted. Specifies the maximum amount of memory to use for detailed statistic gathering. the server stops collecting detailed statistics. the amount is in bytes. . 'medium')" T The names of the destinations to which the specified destination has configured bridges are listed in the Target Name column. Any properties on a topic that are not explicitly specified by this command are removed.2 Type Selector Q T "urgency in ('high'.dest topic.dest. overriding any existing properties. You can set the zone_name and zone_type parameters when creating a route. The bridge_source is the name of the topic or queue established as the source of the bridge. For route parameters. but you cannot subsequently change them. overriding any existing properties. The following is example output for this command: Target Name queue. see routes. Any properties on a route that are not explicitly specified by this command are removed. The type and the message selector (if one is defined) for the bridge are listed in the Type and Selector column.Command Listing 129 | setprop route setprop route route-name properties .1 topic. setprop topic setprop topic topic-name properties Set topic properties.. See Destination Properties on page 46 for the list of the properties that can be set for a topic. show bridge show bridge topic|queue bridge_source Display information about the configured bridges for the named topic or queue.conf on page 206 and Configuring Routes and Zones on page 410. TIBCO Enterprise Message Service User’s Guide .dest. Multiple properties are separated by spaces. Multiple properties are separated by commas. Set the properties for a route. For example. The output includes: • • • • • • • • • • • configuration files server database listen ports configuration settings message tracking server tracing parameters statistics settings fault-tolerant setup external transport setup server SSL setup server LDAP parameters TIBCO Enterprise Message Service User’s Guide .130 | Chapter 6 Using the EMS Administration Tool show bridges show bridges [type=topic|queue] [pattern] Shows a summary of the destination bridges that are currently configured.source Queue Targets 1 1 Topic Targets 1 2 Destinations that match the specified pattern and/or type are listed in the Source Name column. The type option specifies the type of destination established as the bridge source. The number of bridges to topics for each destination is listed in the Topic Targets column. The number of bridges to queues for each destination is listed in the Queue Targets column. show bridges topic shows a summary of configured bridges for all topics that are established as a bridge source. The type and pattern are optional. For example show bridges foo.* returns a summary of configured bridges for all source destinations that match the name foo. The pattern specifies a pattern to match for source destination names. show config show config Shows the configuration parameters for the connected server.*. The following is example output for this command: Source Name Q queue.source T topic. Consumer's connection ID or '-' if this is a disconnected durable topic subscriber. then only consumers on destinations matching specified queue or topic are shown. If the topic or queue parameter is specified. user name. destination name.Command Listing 131 | show consumer show consumer consumerID Shows details about a specific consumer. The consumerID can be obtained from the show consumers output. The durable parameter shows only durable topic subscribers and queue receivers. TIBCO Enterprise Message Service User’s Guide . or number of pending messages. show consumers show consumers [topic=name | queue=name] [durable] [user=name] [connection=id] [sort=conn|user|dest|msgs] [full] Shows information about all consumers or only consumers matching specified filters. Consumer's session ID or '-' if this is a disconnected durable topic subscriber. The full parameter shows all columns listed below and can be as wide as 120-140 characters or wider. Table 13 Description of output fields Heading Id Conn Sess Description Consumer ID. Output of the command can be controlled by specifying the sort or full parameter. first the topic consumers and then the queue consumers. but it does not prevent queue consumers to be shown. The user and/or connection parameters show consumers only for the specified user or connection. Both topic and queue consumers are shown in separate tables. use: show consumers topic=> durable The sort parameter sorts the consumers by either connection ID. To see only durable topic consumers. ) Durable subscription name. Description of columns: • • S . For queue consumer: • • • Topic/Queue Name Q .dups_ok acknowledge — C . R .non-durable topic subscriber.acknowledge mode of consumer's session. P .'+' if consumer's connection started. (Topics Only.'+' if consumer has a selector. TIBCO Enterprise Message Service User’s Guide . values are: — N .no acknowledge — A .proxy subscriber on route's temporary topic.system-created durable for a routed topic.inactive queue receiver. '-' otherwise.(TOPICS ONLY) '+' if subscriber is "NoLocal.auto acknowledge — D .system-created receiver on global queue for user receiver created in one of routes.connection consumer • • S . q . Name of the subscription topic or queue. This column is shown if at least one topic subscriber is a durable subscriber.XA session — Z . '-' otherwise.durable topic subscriber.132 | Chapter 6 Using the EMS Administration Tool Table 13 Description of output fields Heading T Description Consumer type character which can be one of: For topic consumer: • • • • T .session is transactional — X . D .regular queue receiver. N ." SAS[N] Pre Prefetch value of the consumer's destination. P . A .client acknowledge — T . Command Listing 133 | Table 13 Description of output fields Heading Pre Dlv Msgs Sent Size Sent Pend Msgs Pend Size Uptime Last Sent Last Akcd Description Number of prefetch window messages delivered to consumer Current number of messages sent to consumer which are not yet acknowledged by consumer's session.) Total number of messages pending for the topic consumer. Value is rounded and shown in bytes. Uptime of the consumer. Value is approximate with precision of 1 second. Total number of messages sent to consumer since it was created. (M)egabytes or (G)igabytes. Total number of messages sent to the consumer and acknowledged by consumer's session since consumer created. (M)egabytes or (G)igabytes. Total Sent Total Acked TIBCO Enterprise Message Service User’s Guide . Combined size of unacknowledged messages currently sent to consumer. Approximate time elapsed since last message was sent by the server to the consumer. (K)ilobytes. Value is rounded and shown in bytes. Value is approximate with precision of 1 second. (K)ilobytes. (Topics Only.) Combined size of messages pending for the topic consumer. (Topics Only. This includes resends due to session recover or rollback. Approximate time elapsed since last time any message sent to the consumer was acknowledged by consumer's session. When the version flag is present. Table 14 show connections: type Parameter Type type=q type=t type=s Description Show queue connections only. If the address parameter is specified. the display includes the client’s version number. Unique connection ID. Specifying the full parameter prints all of the available information. Show topic connections only. absent Table 15 Description of output fields Heading L Description The type of client. consumers and temporary destinations are printed.134 | Chapter 6 Using the EMS Administration Tool show connections show connections [type=q|t|s] [host=hostname] [user=username] [version] [address] [counts] [full] Show connections between clients and server. TIBCO Enterprise Message Service User’s Guide . Table 15 describes the output. Show queue and topic connections. then number of producers. Each connection is assigned a unique. The type parameter selects the subset of connections to display as shown in Table 14. If the counts parameter is specified. but not system connections. numeric ID that can be used to delete the connection. Can be one of the following: • • • • J C # - — Java client — C client — C# client — unknown system connection Version ID The EMS version of the client. Show system connections only. The host and user parameters can further narrow the output to only those connections involving a specific host or user. then the IP address is printed in the output table. The F column displays whether the connection is fault-tolerant. Host Connection's host name.— not a fault-tolerant connection. that is. The address or full parameter must be specified to display this field. this connection has alternative URLs The S column displays whether the connection is using the SSL protocol. • • .if stopped. this column displays the host’s IP address. • • • • • • S IP Address C T Q A R F — generic user connection — user TopicConnection — user QueueConnection — administrative connection — system connection to another route server — system connection to the fault-tolerant server Connection started status. that is. • • • + — connection is not SSL — connection is SSL / — the client uses SSL. + if started. • • + — connection is not XA — connection is an XA connection The T column displays the connection type. this connection has no alternative URLs + — fault-tolerant connection. but connects by way of an external SSL accelerator to one of the server's TCP ports The X column displays whether the connection is XA. Shows client IP address. .) TIBCO Enterprise Message Service User’s Guide .Command Listing 135 | Table 15 Description of output fields Heading FSXT Description Connection type information. (If the name is not available. " The counts or full parameter must be specified to display this field. For clients prior to 4. then the table includes this column. The counts or full parameter must be specified to display this field." The counts or full parameter must be specified to display this field.136 | Chapter 6 Using the EMS Administration Tool Table 15 Description of output fields Heading Address Description Connection's IP address. TmpQ Number of temporary queues created by this connection. If you supply the keyword address. If a user name was not provided when the connection was created. Number of producers on this connection. Uptime Time that the connection has been in effect. ClientID Sess Prod Cons Number of consumers on this connection. it is assigned the default user name anonymous.4 this is not known and shows "?. Number of sessions on this connection. TIBCO Enterprise Message Service User’s Guide .4 this is not known and shows "?. The counts or full parameter must be specified to display this field. TmpT Number of temporary topics created by this connection. User Connection user name. Client ID of the connection. For clients prior to 4. This name concatenates the client ID (if any) and the subscription name (separated by a colon). specify either a. specify either s. dynamic—created by a client by an administrator static—configured Status online offline Username Username of the durable subscriber (that is. Full name of the durable subscriber. To summarize both files. of the client’s connection). or asynchronous. If the durable subscriber is currently offline.Command Listing 137 | show db show db [sync|async] Print a summary of the server’s databases. • • • To summarize only the asynchronous file. the value in this column is offline. show durable show durable durable-name Show information about a durable subscriber. async. Client ID of the subscriber’s connection. To summarize only the synchronous file. or synchronous. omit the sync or async parameter. The topic from which the durable subscription receives messages. Table 16 show durable Table Information Heading Durable Subscriber Subscription name Client ID Topic Type Description Fully qualified name of the durable subscriber. sync. TIBCO Enterprise Message Service User’s Guide . ) Number of messages in the topic that have been delivered to the durable subscriber. enabled—the subscriber does not receive messages sent from its local connection (that is. Selector Pending Msgs Delivered Msgs Pending Msgs Size The subscriber receives only those messages that match this selector. but not yet acknowledged. the same connection as the subscriber). Number of all messages in the topic. disabled—the subscriber receives messages from all connections. Total size of all pending messages TIBCO Enterprise Message Service User’s Guide .138 | Chapter 6 Using the EMS Administration Tool Table 16 show durable Table Information (Cont’d) Heading Consumer ID No Local Description This internal ID number is not otherwise available outside the server. (This count includes the number of delivered messages. Otherwise the subscriber is static (configured by an administrator). Table 17 show durables Table Information Heading Topic Name Description Name of the topic. the value in this column is offline. there is an asterisk in front of the user name. An asterisk preceding this name indicates a dynamic durable subscriber. Durable User Full name of the durable subscriber. show factory show factory factory-name Shows properties of specified factory.Command Listing 139 | show durables show durables [pattern] If a pattern is not entered. If the durable subscriber is currently offline. Msgs Size Number of pending messages Total size of pending messages For more information. see Destination Properties on page 46. For users defined externally. Name of the user of this durable subscriber. If a pattern is entered (for example foo. this command shows a list of all durable subscribers on all topics. TIBCO Enterprise Message Service User’s Guide . This command prints a table of information described in Table 17.*) this command shows a list of durable subscribers on topics that match that pattern. all JNDI names are shown. For groups defined externally. show group show group group-name Shows group name.140 | Chapter 6 Using the EMS Administration Tool show factories show factories [generic|topic|queue] Shows all factories. or queue factories be listed. and number of members in the group. When type is not specified. show jndinames show jndinames [type] The optional parameter type can be: • • • • • • destination topic queue factory topicConnectionFactory queueConnectionFactory When type is specified only JNDI names bound to objects of the specified type are shown. description. topic. show jndiname show jndiname jndi-name Shows the object that the specified name is bound to by the JNDI server. TIBCO Enterprise Message Service User’s Guide . You can refine the listed output by specifying only generic. Only groups with at least one currently connected user are shown. there is an asterisk in front of the group name. show members show members group-name Shows all user members of specified user group. This command requires that tracking by correlation ID be turned on using the track_correlation_ids configuration parameter.Command Listing 141 | show groups show groups Shows all user groups. This command requires that tracking by message ID be turned on using the track_message_ids configuration parameter. TIBCO Enterprise Message Service User’s Guide . show messages show messages correlationID Shows the message IDs of all messages with the specified correlation ID set as JMSCorrelationID message header field. show parents show parents user-name Shows the user’s parent groups. For groups defined externally. show message show message messageID Shows the message for the specified message id. there is an asterisk in front of the group name. You can display the message for each ID returned by this command by using the show message messageID command. This command can help you to understand the user’s permissions. 142 | Chapter 6 Using the EMS Administration Tool show queue show queue queue-name Shows the details for the specified queue. Table 18 show queue Table Information Heading Queue Type Description Full name of the queue. Number of all messages in the queue. but not yet acknowledged. dynamic—created by a client by an administrator static—configured Properties A list of property names that are set on the queue. A list of explicitly assigned JNDI names that refer to this queue. A list of bridges from this queue to other destinations. (This count includes the number of delivered messages.) Number of messages in the queue that have been delivered to a consumer. and their values. specify only the name of the queue (do not specify the server using the queue-name@server form). If the queue is a routed queue. For an index list of property names. Total size of all pending messages JNDI Names Bridges Receivers Pending Msgs Delivered Msgs Pending Msgs Size TIBCO Enterprise Message Service User’s Guide . Number of consumers on this queue. see Destination Properties on page 46. Pre Prefetch value. If a pattern-name is entered (for example foo. Number of currently active receivers Number of pending messages SNFGXIBCT Rcvrs Msgs TIBCO Enterprise Message Service User’s Guide .show only static queues . then it is inherited from another queue or is the default value.show only dynamic queues A * appearing before the queue name indicates a dynamic queue. this command shows a list of all queues.Command Listing 143 | show queues show queues [pattern-name [notemp|static|dynamic]] If a pattern-name is not entered.Property not present + Property is present. Properties of dynamic and temporary queues cannot be changed. If the value is followed by an asterisk (*). and was set on the topic itself * Property is present. You can further refine the list of queues that match the pattern by using one of the following parameters: • • • notemp static dynamic . If the name is prefixed with an asterisk (*). then the queue is temporary or was created dynamically.do not show temporary queues . This command prints a table of information described in Table 19. and was inherited from another queue Note that inherited properties cannot be removed.*) this command shows a list of queues that match that pattern. Prints information on the topic properties in the order (S)ecure (N)sender_name or sender_name_enforced (F)ailsafe (G)lobal e(X)clusive (I)mport (B)ridge (C)flowControl (T)race The characters in the value section show: . Table 19 show queues Table Information Heading Queue Name Description Name of the queue. Table 20 show routes Table Information Heading Route T Description Name of the route. Name of the zone for the route. A hyphen (-) in this column indicates that the other server is not connected. Type of route: • • ConnID A P indicates an active route.144 | Chapter 6 Using the EMS Administration Tool Table 19 show queues Table Information (Cont’d) Heading Size Description Total size of pending messages For more information. show routes show routes Shows the properties (URL and SSL properties) of all created routes. Type of the zone: • • m 1 indicates a multi-hop zone. see Destination Properties on page 46. TIBCO Enterprise Message Service User’s Guide . indicates a one-hop zone. indicates a passive route. Unique ID number of the connection from this server to the server at the other end of the route. URL ZoneName ZoneType URL of the server at the other end of the route. These commands print the information described in Table 20. show route show route route-name Shows the properties (URL and SSL properties) of a route. Statistic gathering must be enabled for statistics to be displayed. show server show server (aliases: info. i) Shows server name and information about the connected server. Averages for inbound/outbound messages and message size are available if an interval is specified in the rate_interval configuration parameter. For more information about ledger files and the format of ledger file entries. or destinations.Command Listing 145 | show rvcmtransportledger show rvcmtransportledger transport [subject-or-wildcard] Displays the TIBCO Rendezvous certified messaging (RVCM) ledger file entries for the specified transport and the specified subject. You can specify a subject name. The wide keyword displays inbound and outbound message statistics on the same line. You can display statistics for consumers. use wildcards to retrieve all matching subjects. Also. show rvcmlisteners show rvcmlisteners Shows all RVCM listeners that have been created using the create rvcmlistener command or by editing the tibrvcm. or omit the subject name to retrieve all ledger file entries. show stat show stat consumers [topic=name|queue=name] [user=name] [connection=id] [total] show stat producers [topic=name|queue=name] [user=name] [connection=id] [total] show stat route [topic=name|queue=name] [total] [wide] show stat topic name [total] [wide] show stat queue name [total] [wide] Displays statistics for the specified item. detailed statistics for each item can be displayed if detailed statistic tracking is enabled. producers. see TIBCO Rendezvous documentation. routes. TIBCO Enterprise Message Service User’s Guide .conf file. The total keyword specifies that only total number of messages and total message size for the item should be displayed. and their values.) Number of durable consumers on this topic. Total Inbound Msgs Total Inbound Bytes Cumulative count of all messages delivered to the topic. Number of consumers on this topic.146 | Chapter 6 Using the EMS Administration Tool See Working with Server Statistics on page 360 for a complete description of statistics and how to enable/disable statistic gathering options. Number of all messages in the topic. A list of bridges from this topic to other destinations. (This count also includes durable consumers. TIBCO Enterprise Message Service User’s Guide . dynamic—created by a client by an administrator static—configured Properties A list of property names that are set on the topic. (This count includes the number of delivered messages. A list of explicitly assigned JNDI names that refer to this topic. see Destination Properties on page 46. show topic show topic topic-name Table 21 show topic Table Information Heading Topic Type Description Full name of the topic. For an index list of property names. Otherwise these items are zero.) Total size of all pending messages JNDI Names Bridges Consumers Durable Consumers Pending Msgs Pending Msgs Size The server accumulates the following statistics only when the administrator has enabled statistics. Cumulative total of message size over all messages delivered to the topic. Command Listing 147 | Table 21 show topic Table Information (Cont’d) Heading Total Outbound Msgs Description Cumulative count of messages consumed from the topic by consumers. Total Outbound Bytes TIBCO Enterprise Message Service User’s Guide . Cumulative total of message size over all messages consumed from the topic by consumers. Each consumer of a message contributes this total independently of other consumers. Each consumer of a message increments this count independently of other consumers. so one inbound message results in n outbound messages (one per consumer). Subs Durs Msgs Size Number of current subscribers on the topic. including messages to durable receivers Total size of pending messages SNFGEIBCT TIBCO Enterprise Message Service User’s Guide . and was inherited from another topic Note that inherited properties cannot be removed. including durable subscribers Number of durable subscribers on the topic Number of pending messages. If a pattern-name is entered (for example foo. and was set on the topic itself * Property is present. then the topic is temporary or was created dynamically. You can further refine the list of queues that match the pattern by using one of the following parameters: • • • notemp static dynamic . this command shows a list of all topics. Table 22 Show topics table information Heading Topic Name Description Name of the topic.148 | Chapter 6 Using the EMS Administration Tool show topics show topics [pattern-name [notemp|static|dynamic]] If a pattern-name is not entered.show only dynamic queues This command prints a table of information described in Table 22.Property not present + Property is present.show only static queues . If the name is prefixed with an asterisk (*).*) this command shows a list of topics that match that pattern. Prints information on the topic properties in the order (S)ecure (N)sender_name or sender_name_enforced (F)ailsafe (G)lobal (E)xport (I)mport (B)ridge (C)flowControl (T)race The characters in the value section show: .do not show temporary queues . Properties of dynamic and temporary topics cannot be changed. Each row presents information about one transaction. TIBCO Enterprise Message Service User’s Guide . 0 = OSI CCR naming is used >0 = some other format is used -1 = NULL GTrid Len Bqual Len Data The number of bytes that constitute the global transaction ID. see Destination Properties on page 46. Table 23 Show transactions table information Heading State Description Transaction state: • • • • • A active E ended R rollback only P prepared S suspended Suspended transactions can be rolled back.Command Listing 149 | For more information. The global transaction identifier (gtrid) and the branch qualifier (bqual). Table 23 describes the information shown in each column. The number of bytes that constitute the branch qualifier. but cannot be rolled forward (committed). Format ID The XA transaction format identifier. show transactions show transactions Shows the XID for all client transactions that were created using the XA interface. show user show user user-name Shows user name and description.conf. See Configuring Transports for Rendezvous on page 302 and Configuring Transports for SmartSockets on page 327 for details. If no user name is specified. For users defined externally. there is an asterisk in front of the user name.conf. this command displays the currently logged in user. For users defined externally. showacl admin showacl admin Shows all administrative permissions for all users and groups. show transports show transports Lists all configured transport names in transports. there is an asterisk in front of the user name. but does not include administrative permissions on destinations.150 | Chapter 6 Using the EMS Administration Tool show transport show transport transport Displays the configuration for the specified transport defined in transports. TIBCO Enterprise Message Service User’s Guide . Only currently connected external users are shown. show users show users Shows all users. Command Listing 151 | showacl group showacl group group-name [admin] Shows all permissions set for a given group. Specifying showacl admin shows all administrative permissions for all users and groups (not including administrative permissions on destinations). You can optionally specify admin to show only the administrative permissions for destinations or principals. Each entry shows the “grantee” (user or group) and the set of permissions. Specifying showacl admin shows all administrative permissions for all users and groups (not including administrative permissions on destinations). Shows the group and the set of permissions. Each entry shows the “grantee” (user or group) and the set of permissions. You can optionally specify admin to show only the administrative permissions for destinations or principals. You can optionally specify admin to show only the administrative permissions for destinations or principals. showacl queue showacl queue queue-name [admin] Shows all permissions set for a queue. Specifying showacl admin shows all administrative permissions for all users and groups (not including administrative permissions on destinations). showacl topic showacl topic topic-name [admin] Shows all permissions set for a topic. Lists all entries from the acl file. TIBCO Enterprise Message Service User’s Guide . Lists all entries from the acl file. even without permissions to view any other user permissions. (An administrator can use this form of the command to view own permissions. An attempt to revoke an inherited permission for the principal user will not change the permission. Inherited permissions cannot be changed. time time [on | off] Specifying on places a timestamp before each command’s output. shutdown shutdown Shuts down currently connected server. showacl user username — displays permissions granted directly to the user. By default. the timestamp is off. username admin-all — displays all administrative permissions for showacl user a given user (direct and inherited) The output from this command displays inherited permissions prefixed with a '*'.152 | Chapter 6 Using the EMS Administration Tool showacl user showacl user user-name [admin | all | admin-all] Shows the user and the set of permissions granted to the user for destinations and principals.) username admin — displays administrative permissions granted showacl user directly to the user. TIBCO Enterprise Message Service User’s Guide . showacl user username all — displays direct and inherited (from groups to which the user belongs) permissions. updatecrl updatecrl Immediately update the server’s certificate revocation list (CRL). The timeout value is the number of seconds the Administration Tool will wait for a response from the server after sending a command.Command Listing 153 | timeout timeout [seconds] Show or change the current command timeout value. transaction rollback transaction rollback XID Rolls back the transaction identified by the transaction ID. To obtain a transaction ID. When timeout is entered with the optional seconds parameter. To obtain a transaction ID. When entered without parameter. issue the show transactions command. the timeout value is reset to the specified number of seconds. rollback only. issue the show transactions command. whoami whoami Alias for the show user command to display the currently logged in user. and cut and paste the XID into this command. TIBCO Enterprise Message Service User’s Guide . or the prepared state. The transaction must be in the ended or prepared state. By default. transaction commit transaction commit XID Commits the transaction identified by the transaction ID. the timeout is 30 seconds. Messages sent to a queue with prefetch=none and maxRedelivery=number properties are not received number times by an EMS application that receives in a loop and does an XA rollback after the XA prepare phase. the current timeout value is returned. The transaction must be in the ended. and cut and paste the XID into this command. 154 | Chapter 6 Using the EMS Administration Tool TIBCO Enterprise Message Service User’s Guide . page 156 Mechanics of Configuration. page 157 Using Other Configuration Files.conf. Topics • • • • Location of Configuration Files. page 200 TIBCO Enterprise Message Service User’s Guide . page 156 tibemsd.| 155 Chapter 7 Using the Configuration Files This chapter describes configuring TIBCO Enterprise Message Service. TIBCO Enterprise Message Service User’s Guide . When the server validates and accepts an administrative request. use the shutdown command from the EMS Administration Tool to shutdown the server and then restart the server as described in Running the EMS Server on page 89. It is essential that the EMS server have both read and write privileges in the configuration directory. using either tibemsadmin (a command line tool). and modifying those copies. It ignores subsequent changes to the configuration files. or TIBCO Administrator™ (a separate TIBCO product). If you change a configuration file. contains the more complete set of sample configuration files.NET administrative APIs. This policy keeps configuration files current in case the server restarts (for example. when the server starts. samples/config/ Administrative Requests Re-installing or updating EMS overwrites the files in the bin/ and directories. in a fault-tolerant situation. we recommend using a file system with regular backup commensurate with your need for reliability and disaster recovery. it writes the change to the appropriate configuration file as well (overwriting any manual changes to that file). samples/config/ When selecting a production configuration directory. For deployment. Do not use these directories to configure your deployment. Mechanics of Configuration Configuration Files The EMS server reads configuration files only once. or after a hardware failure).156 | Chapter 7 Using the Configuration Files Location of Configuration Files The installation process places configuration files in two directories: • • bin/ contains a subset of configuration files suitable for quickly testing the installation. the Java or . we recommend copying files from this directory to a production configuration directory. You can also change the server configuration with administrative requests. tibemsd.conf 157 | tibemsd.conf The main configuration file controls the characteristics of the EMS server. This file is usually named tibemsd.conf, but you can specify another file name when starting the server. You can find more information about starting the server in Running the EMS Server on page 89. An example of the tibemsd.conf file is included in the bin directory of TIBCO Enterprise Message Service. You can edit this configuration file with a text editor. There are a few configuration items in this file that can be altered using the administration tool, but most configuration parameters must be set by editing the file (that is, the server does not accept changes to those parameters). See Chapter 6, Using the EMS Administration Tool, on page 101 for more information about using the administration tool. Several parameters accept boolean values. In the description of the parameter, one specific set of values is given (for example, enable and disable), but all parameters that accept booleans can have the following values: • • enable, enabled, true, yes, on disable, disabled, false, no, off The following tables summarize the parameters in tibemsd.conf according to category. The sections that follow provide more detail on each parameter. TIBCO Enterprise Message Service User’s Guide 158 | Chapter 7 Using the Configuration Files Table 24 Global System Parameters Parameter Name authorization flow_control listen Description Enable or disable server authorization. Enable or disable flow control for destinations. Specifies the port on which the server is to listen for connections from clients. Specifies when the server is to provide confirmation upon receiving a NON_PERSISTENT message from a producer. Password used to authenticate with other routed servers that have authorization enabled. Enable or disable routing functionality for this server. Name of server. Specifies conditions under which the server is to exit during its initialization sequence. Specifies the source of authentication information used to authenticate users attempting to access the EMS server. See Page 167 167 168 169 170 170 170 170 172 npsend_check_mode password routing server startup_abort_list user_auth Table 25 Storage File Parameters Parameter Name store store_crc Description Specifies the directory in which the server stores data. Specifies whether the EMS server validates CRC checksum data when reading the store files. Specifies the amount of disk space to preallocate for EMS store files. Specifies whether the EMS server is to periodically truncate the storage files to relinquish unused disk space. See Page 173 173 173 173 store_minimum store_truncate TIBCO Enterprise Message Service User’s Guide tibemsd.conf 159 | Table 26 Connection and Memory Parameters Parameter Name max_connections Description Specifies the maximum number of simultaneous client connections to the server. Specifies the maximum memory the server can use for messages. Enable or disable message swapping. Specifies the amount of memory to reserve for use in emergency situations. Specifies the size of the pool to be pre-allocated by the server to store messages. See Page 174 174 174 175 175 max_msg_memory msg_swapping reserve_memory msg_pool_block_size msg_pool_size Table 27 Detecting Network Connection Failure Parameters Parameter Name client_heartbeat_server Description Specifies the interval clients are to send heartbeats to the server. Specifies the period of time server will wait for a client heartbeat before terminating the client connection. Specifies the interval this server is to send heartbeats to another server. Specifies the period of time this server will wait for a heartbeat from another server before terminating the connection to that server. Specifies the interval this server is to send heartbeats to all of its clients. Specifies the period of time a client will wait for a heartbeat from the server before terminating the connection. See Page 176 176 server_timeout_client_connection server_heartbeat_server 177 177 server_timeout_server_connection server_heartbeat_client 177 177 client_timeout_server_connection TIBCO Enterprise Message Service User’s Guide 160 | Chapter 7 Using the Configuration Files Table 28 Fault Tolerance Parameters Parameter Name ft_active ft_heartbeat Description Specifies the URL of the active server. Specifies the interval the active server is to send a heartbeat signal to the backup server to indicate that it is still operating. Specifies the maximum length of time between heartbeat signals the backup server is to wait before assuming the active server has failed. Specifies the maximum length of time the backup server is to wait for clients to reconnect after assuming the role of primary server in a failover situation. Specifies the server’s digital certificate. Specifies the certificate chain member for the server. Specifies the server’s private key. Specifies the password for private keys. Specifies the list of trusted certificates. Specifies the path for the installed entropy gathering daemon (EGD). Specifies whether the fault-tolerant server should verify the other server’s certificate. Specifies whether the fault-tolerant server should verify the name in the CN field of the other server’s certificate. Specifies the name the server is expected to have in the CN field of the fault-tolerant server’s certificate. Specifies the cipher suites used by the server. See Page 178 178 ft_activation 178 ft_reconnect_timeout 178 ft_ssl_identity ft_ssl_issuer ft_ssl_private_key ft_ssl_password ft_ssl_trusted ft_ssl_rand_egd 179 179 179 179 180 180 180 180 ft_ssl_verify_host ft_ssl_verify_hostname ft_ssl_expected_hostname 181 181 ft_ssl_ciphers TIBCO Enterprise Message Service User’s Guide tibemsd.conf 161 | Table 29 Message Tracking Parameters Parameter Name track_message_ids track_correlation_ids Description Enable or disable message tracking by message ID. Enable or disable message tracking by correlation ID. See Page 181 181 Table 30 TIBCO Rendezvous Parameters Parameter Name tibrv_transports Description Enable or disable the TIBCO Rendezvous transports defined in transports.conf file. Enable or disable the translation of XML fields to byte arrays when importing messages from Rendezvous. See Page 182 182 tibrv_xml_import_as_string Table 31 TIBCO SmartSockets Parameters Parameter Name tibss_transports Description Enable or disable the TIBCO SmartSockets transports defined in transports.conf file. Specifies the directory for SmartSockets configuration and message files. See Page 182 183 tibss_config_dir TIBCO Enterprise Message Service User’s Guide 162 | Chapter 7 Using the Configuration Files Table 32 Tracing and Log File Parameters Parameter Name logfile log_trace Description Name and location of the server log file. Specifies the trace options on the file defined by the logfile parameter. Specifies the maximum log file size before the log file is copied to a backup and then emptied. Specifies the trace options for output to stderr. Enable or disable client generation of trace output for opening or closing a connection, message activity, and transaction activity. Specifies whether the trace statements related to connections identify the host by its hostname, its IP address, or both. See Page 183 183 184 184 185 logfile_max_size console_trace client_trace trace_client_host 185 Table 33 Statistic Gathering Parameters Parameter Name server_rate_interval Description Specifies the interval at which overall server statistics are averaged. Enables or disables statistic gathering for producers, consumers, destinations, and routes. Specifies the interval at which statistics for routes, destinations, producers, and consumers are averaged. Specifies which objects should have detailed statistic tracking. Specifies how long the server should keep detailed statistics if the destination has no activity. Specifies the maximum amount of memory to use for detailed statistic gathering. See Page 186 186 186 statistics rate_interval detailed_statistics 187 187 187 statistics_cleanup_interval max_stat_memory TIBCO Enterprise Message Service User’s Guide tibemsd.conf 163 | Table 34 SSL Server Parameters Parameter Name ssl_dh_size ssl_server_ciphers ssl_require_client_cert Description Specifies the size of the Diffie-Hellman key. Specifies the cipher suites used by the server. Specifies if the server is to only accept SSL connections from clients that have digital certificates. Specifies if a client’s user name is to always be extracted from the CN field of the client’s digital certificate. Specifies a special username to identify which clients are to have their usernames taken from their digital certificates. Specifies the server’s digital certificate. Specifies the server’s private key. Specifies the password for private keys. Specifies the certificate chain member for the server. Specifies the list of CA root certificates the server trusts as issuers of client certificates. Specifies the path for the installed entropy gathering daemon (EGD). Specifies the file containing random numbers or other random data. Specifies the pathname to the certificate revocation list (CRL) files. Specifies the interval at which the server is to update its CRLs. Specifies whether the server allows clients to request the use of SSL only for authentication. See Page 188 188 188 ssl_use_cert_username 188 ssl_cert_user_specname 189 ssl_server_identity ssl_server_key ssl_password ssl_server_issuer 189 190 190 190 191 191 191 191 191 192 ssl_server_trusted ssl_rand_egd ssl_rand_file ssl_crl_path ssl_crl_update_interval ssl_auth_only TIBCO Enterprise Message Service User’s Guide 164 | Chapter 7 Using the Configuration Files Table 35 LDAP Parameters Parameter Name ldap_url Description Specifies the URL of the external directory server. Specifies the distinguished name (DN) of the LDAP administrator. Specifies the password associated with the user defined in the ldap_principal property. Enables or disables caching of LDAP data. Specifies the maximum time that cached LDAP data is retained before it is refreshed. Specifies the type of connection that the server uses to get LDAP information. Specifies the file that contains the CA certificate the EMS server trusts to sign the LDAP server’s certificate. When there are two or more CA certificates in the verify chain, use this parameter to specify the directory containing the CA certificates. Specifies the cipher suite to use for encryption on secure LDAP connections. Specifies the file containing random data for encryption. Specifies the file containing the certificate that identifies the EMS server to the LDAP server. Specifies the file containing the private key required by the LDAP server to authenticate the client. Specifies the name of the LDAP object class that stores users. See Page 192 192 192 ldap_principal ldap_credential ldap_cache_enabled ldap_cache_ttl 193 193 193 193 ldap_conn_type ldap_tls_cacert_file ldap_tls_cacert_dir 193 ldap_tls_cipher_suite 194 194 194 ldap_tls_rand_file ldap_tls_cert_file ldap_tls_key_file 194 ldap_user_class 194 TIBCO Enterprise Message Service User’s Guide tibemsd.conf 165 | Parameter Name ldap_user_attribute Description Specifies the name of the attribute on the user object class that holds the name of the user. Specifies the base distinguished name (DN) of the LDAP tree that contains the users. Specifies how deeply under the base DN to search for users. Specifies the LDAP search filter for finding a given user name. Specifies the LDAP search filter for finding all users beneath the user base DN. Specifies the base distinguished name (DN) of the LDAP tree that contains groups. Specifies how deeply under the base DN to search for groups. Specifies the LDAP search filter for finding a group with a given group name. Specifies the LDAP search filter for finding all groups beneath the group base DN. Specifies the name of the LDAP object class that stores static groups. Specifies the name of the attribute on the static group object class that holds the name of the group. Specifies the attribute of an LDAP static group object that specifies the distinguished names (DNs) of the members of the group. Specifies the name of the LDAP object class that stores dynamic groups. See Page 195 ldap_user_base_dn 195 195 195 196 196 196 196 197 197 197 ldap_user_scope ldap_user_filter ldap_all_users_filter ldap_group_base_dn ldap_group_scope ldap_group_filter ldap_all_groups_filter ldap_static_group_class ldap_static_group_attribute ldap_static_member_attribute 197 ldap_dynamic_group_class 197 TIBCO Enterprise Message Service User’s Guide 166 | Chapter 7 Using the Configuration Files Parameter Name ldap_dynamic_group_attribute Description Specifies the name of the attribute on the dynamic group object class that holds the name of the group. Specifies the attribute of the dynamic LDAP group object that specifies the URLs of the members of the dynamic group. See Page 198 ldap_dynamic_member_url_attribute 198 TIBCO Enterprise Message Service User’s Guide See Enabling Access Control on page 231 for more information. the flowControl property on each destination specifies the target maximum storage for pending messages on the destination. See Flow Control on page 71 for more information about flow control. once a client successfully acknowledges a message received from a routed queue. For example: authorization = enabled See Chapter 8. If compliant queue acknowledgement is disabled and a message is redelivered. the message will not be redelivered. compliant_queue_ack compliant_queue_ack = enable | disable Guarantees that. By default. Authorization is disabled by default. flow_control flow_control = enable | disable Specifies whether flow control for destinations is enabled or disabled. the message’s JMSRedelivered indicator will be set.conf 167 | Global System Parameters authorization authorization = enabled | disabled Enable or disable server authorization. The compliant_queue_ack parameter is enabled by default. If you require that the server verify user credentials and permissions on secure destinations. When flow control is enabled. on page 221 for more information about these parameters. Authentication and Permissions.tibemsd. flow control is disabled. you can disable this feature when performance is an issue. TIBCO Enterprise Message Service User’s Guide . you must enable this parameter. Because of the extra overhead incurred with compliant queue acknowledgments. This is accomplished by the EMS server waiting until the message has been successfully acknowledged by the queue’s home EMS server before sending the response to the client. 168 | Chapter 7 listen Using the Configuration Files listen=protocol://servername:por Specifies the port on which the server is to listen for connections from clients. for example: listen=ssl://localhost:7222 You can use multiple listen entries if you have computers with multiple interfaces. For example: listen=tcp://localhost:7222 listen=tcp://localhost:7224 If the hostname is not present then the default host and interface will be used. For example: listen=tcp://7222 listen=ssl://7243 TIBCO Enterprise Message Service User’s Guide . For example: listen=tcp://localhost:7222 If you are enabling SSL. the server always provides confirmation of a NON_PERSISTENT message.3 and prior.the server provides confirmation of a NON_PERSISTENT message if sending to a temporary destination or if authorization was enabled when the connection was created. The server is out of memory or the server has encountered some other severe error. auth authorization . The circumstances in which a producer might want the server to send confirmation a NON_PERSISTENT message are: • • • • • When authorization is enabled. The possible npsend_check_mode parameter modes are: • default (no mode specified) .conf 169 | npsend_check_mode npsend_check_mode [= always | never | temp_dest | auth | temp_auth] Specifies when the server is to provide confirmation upon receiving a NON_PERSISTENT message from a producer. This means the server only provides confirmation of a NON_PERSISTENT message if authorization is enabled. temp_dest . The message exceeded queue/topic limit (requires rejectIncoming policy for topics). so the producer can take action if permission to send the message is denied by the server. The npsend_check_mode parameter applies only to producers sending messages using NON_PERSISTENT delivery mode and non-transactional sessions. temp_auth .same behavior as in EMS 4.the server provides confirmation of a NON_PERSISTENT message only when sending to a temporary destination. Message confirmation has a great deal of impact on performance and should only be enabled when necessary. When sending to a temporary destination.tibemsd. so the producer can take action if the message is sent to a temporary destination that has been destroyed. never .the server provides confirmation of a NON_PERSISTENT message only if was enabled when the connection was created.the server never provides confirmation of a NON_PERSISTENT message. always • • • • • . Bridging of the message has failed. TIBCO Enterprise Message Service User’s Guide . The default is an empty list. CONFIG_ERRORS. For example: routing = enabled See Chapter 16. server server = serverName Name of server. then exit. then exit.conf does not the server detects any errors while reading the config CONFIG_FILES—If exist. CONFIG_FILES. CONFIG_ERRORS—If files. TRANSPORTS—If any of the transports cannot be created as specified in the configuration files. Server names are limited to at most 64 characters. DB_FILES] Specifies conditions that cause the server to exit during its initialization sequence. then exit. The conditions are: • • • • SSL—If SSL initialization fails. TRANSPORTS. on page 401 for more information about routing. routing routing = enabled | disable Enables or disables routing functionality for this server.170 | Chapter 7 password Using the Configuration Files password = password Password used to log in to other routed servers that have authorization enabled. startup_abort_list startup_abort_list [= SSL. You may specify any subset of the conditions in a comma-separated list. See Routing and Authorization on page 422 for details. Working With Routes. TIBCO Enterprise Message Service User’s Guide . any configuration file listed in tibemsd. Conditions that do not appear in the list are ignored by the server. then exit. TIBCO Enterprise Message Service User’s Guide . then exit.tibemsd.conf 171 | • DB_FILES—If the server cannot find its store files. the server seeks corresponding authentication information from each of the specified locations in the order that this parameter specifies. Each time a user attempts to authenticate. TIBCO Enterprise Message Service User’s Guide . ldap] Specifies the source of user authentication information. This parameter can have one or more of the following values (separated by comma characters): • • local—obtain user authentication information from the local EMS server user configuration. ldap—obtain user authentication information from an LDAP directory server (see the LDAP-specific configuration parameters). The EMS server accepts successful authentication using any of the specified sources.172 | Chapter 7 user_auth Using the Configuration Files user_auth = [local. If store_minimum_sync or store_minimum_async are absent. the storage files may be truncated. these parameters limit truncation to minimum values. MB. You can specify units of KB. For example: store_minimum_sync = 32MB store_truncate store_truncate = enable | disable Specifies whether the EMS server occasionally attempts to truncate the storage files. Zero is a special value. or GB.tibemsd. TIBCO Enterprise Message Service User’s Guide . Preallocation occurs when the server first creates a store file. If store_truncate is enabled. Otherwise. but not below the size specified in the store_minimum parameters.conf 173 | Storage File Parameters store store = directory Directory in which the server stores data files. they default to store_minimum. When enabled. For example: store = /usr/tmp store_crc store_crc = enable | disable Specifies whether the EMS server validates CRC checksum data when reading the store files. which specifies no minimum preallocation. relinquishing unused disk space. store_minimum store_minimum = size [KB|MB|GB] store_minimum_sync = size [KB|MB|GB] store_minimum_async = size [KB|MB|GB] This set of parameters preallocates disk space for EMS store files. the value you specify must be greater than or equal to 8MB. indicating no limit. Swapping allows the server to free process memory for incoming messages. The server stops accepting new messages. then the server has no room for new incoming messages. When the server swaps a message to disk. For example: max_msg_memory = 512MB msg_swapping msg_swapping = enable | disable This parameter enables and disables the message swapping feature (described above for max_msg_memory). and messages overflow this limit. and their remains still exceed this memory limit. Zero is a special value. TIBCO Enterprise Message Service User’s Guide . MB or GB. or a very high message volume. The minimum value is 8 MB. a small record of the swapped message remains in memory. the server begins to swap messages from process memory to disk. (This situation probably indicates either a very low value for this parameter.) Specify units as KB.174 | Chapter 7 Using the Configuration Files Connection and Memory Parameters max_connections max_connections = number Maximum number of simultaneous client connections. The default value is enabled. unless you explicitly set it to disabled. max_msg_memory max_msg_memory = size [KB|MB|GB] Maximum memory the server can use for messages. Set to 0 to allow unlimited simultaneous connections. If all messages are swapped out to disk. When msg_swapping is enabled. so server memory usage cannot grow beyond the system’s memory capacity. and to process message volume in excess of this limit. This parameter lets you limit the memory that the server uses for messages. and send calls in message producers result in an error. The reserve_memory parameter only triggers when the EMS server has run out of memory and therefore is a reactive mechanism. the server increases the pool by this size. msg_pool_block_size msg_pool_size msg_pool_block_size msg_pool_size size size Consult with your TIBCO support representative before using either of these commands. Each time the server exhausts the pool. as well as destination properties such as maxbytes. the minimum block is 16MB. To lessen the overhead costs associated with malloc and free. the server pre-allocates pools of storage for messages. This allows the operating system to reclaim all the virtual memory resources that have been consumed by the EMS server. the default is zero. the daemon allocates a block of memory for use in emergency situations to prevent the EMS server from being unstable in low memory situations. as long as additional storage is available. When non-zero. which can lead to situations where the EMS server runs out of memory. The value may be in the range 32 to 64K. msg_pool_block_size instructs the server to allocate an expandable pool.conf 175 | reserve_memory reserve_memory = size When reserve_memory is non-zero. Specify size in units of MB. These limits should be used prevent the reserve_memory mechanism from triggering. such as max_msg_memory.tibemsd. When the daemon process exhausts memory resources. These include global parameters. There are a variety of limits that the user can set to prevent the EMS server from storing excessive messages. Performance varies depending on operating system platform and usage patterns. When absent. The size argument determines the approximate number of internal message structs that a block or pool can accommodate (not the number of bytes). The appropriate administrative action when an EMS server has triggered release of reserve memory is to drain the majority of the messages by consuming them and then to stop and restart the EMS server. and frees this block of memory to allow consumers to continue operation (which tends to free memory). TIBCO Enterprise Message Service User’s Guide . These parameters determine the behavior of these pools. it disables clients from producing new messages. You may specify at most one of these two parameters. 128 (an These two parameters represent two different and mutually exclusive modes for allocating storage pools. or this feature is disabled. When omitted or zero. the default is 5 seconds. it closes the connection. Detecting Network Connection Failure Parameters This feature lets servers and clients detect network connection failures quickly. the default is msg_pool_block_size expandable pool). server_timeout_client_connection server_timeout_client_connection limit In a server-to-client connection. After the server exhausts this pool. The value may be in the range 16K to 1024M. if the server does not receive a heartbeat for a period exceeding this limit (in seconds). This feature is new in release 4. it is disabled when either entity is from an earlier release. clients send heartbeats to the server at this interval (in seconds).5 times the heartbeat interval. the server calls malloc each time it requires additional storage.176 | Chapter 7 Using the Configuration Files msg_pool_size instructs the server to allocate a fixed pool. TIBCO Enterprise Message Service User’s Guide . it is illegal to set both parameters explicitly. which disables heartbeat detection in the server (although clients still send heartbeats). When neither parameter is present. client_heartbeat_server client_heartbeat_server interval In a server-to-client connection. Zero is a special value. When these parameters are absent. We recommend setting this value to approximately 3.0. tibemsd closes a connection only upon the operating system notification. the server_timeout_server_connection parameter has no effect on the backup server following a switchover. We recommend setting this value to approximately 3. server_heartbeat_client server_heartbeat_client interval In a server-to-client connection.conf 177 | server_heartbeat_server server_heartbeat_server interval In a server-to-server connection. This parameter applies to connections from other routes and to the backup server connection. it closes the connection. client_timeout_server_connection client_timeout_server_connection limit In a server-to-client connection. TIBCO Enterprise Message Service User’s Guide .5 times the heartbeat interval. if a client does not receive a heartbeat for a period exceeding this limit (in seconds). which disables heartbeat detection in the client (although the server still sends heartbeats).5 times the heartbeat interval of the other server. server_timeout_server_connection server_timeout_server_connection limit In a server-to-server connection. We recommend setting this value to approximately 3. we recommend a larger multiple. Zero is a special value. it closes the connection. the server sends heartbeats to all clients at this interval (in seconds). or when client programs send very large messages. In a fault-tolerant configuration.tibemsd. When the other server or the network are heavily loaded. The backup server activates only after the timeout set by the ft_activation parameter. or as a fault-tolerant pair. the default is 5 seconds. When omitted or zero. The two servers can be connected either by a route. this server sends heartbeats at this interval (in seconds). if this server does not receive a heartbeat for a period exceeding this limit (in seconds). For example: ft_activation = 60 The ft_activation parameter is only used by the backup server after a fault-tolerant switchover. ft_reconnect_timeout ft_reconnect_timeout = seconds The amount of time (in seconds) that a backup server waits for clients to reconnect (after it assumes the role of primary server in a failover situation). it will act as a backup server. so this value does not account for the time it takes to recover the store files. The active server uses the server_timeout_server_connection to detect a failed server. on page 383 for more information about these parameters. The ft_reconnect_timeout time starts once the server has fully recovered the shared state. ft_active ft_active = URL Specifies the URL of the active server. Set in seconds: default is 10. If a client does not reconnect within this time period. it will become the active server. Fault Tolerance. If this server can connect to the active server. The default value of this parameter is 60.178 | Chapter 7 Using the Configuration Files Fault Tolerance Parameters See Chapter 15. ft_heartbeat ft_heartbeat = seconds Specifies the interval (in seconds) the active server is to send a heartbeat signal to the backup server to indicate that it is still operating. ft_activation ft_activation = seconds Activation interval (maximum length of time between heartbeat signals) which indicates that active server has failed. This interval should be set to at least twice the heartbeat interval. the server removes its state from the shared state files. TIBCO Enterprise Message Service User’s Guide . Default is 3 seconds. If this server cannot connect to the active server. PKCS#7. Using the EMS Administration Tool. When passwords are set with this tool. You can copy the digital certificate into the specification for this parameter. or you can specify the path to a file that contains the certificate in one of the supported formats. If it is included in the digital certificate in ft_ssl_identity. on page 101 for more information about using tibemsadmin to set passwords. TIBCO Enterprise Message Service User’s Guide . The certificates must be in PEM. See File Names for Certificates and Keys on page 369 for more information on file types for digital certificates. DER. Supply the entire chain. including the CA root certificate. You can specify the actual key in this parameter. DER.tibemsd. ft_ssl_issuer ft_ssl_issuer = chain_member Certificate chain member for the server. See File Names for Certificates and Keys on page 369 for more information on file types for digital certificates. The server reads the certificates in the chain in the order they are presented in this parameter.conf 179 | ft_ssl_identity ft_ssl_identity = certificate The server’s digital certificate in PEM. then this parameter is not needed. See File Names for Certificates and Keys on page 369 for more information on file types for digital certificates. the password is obfuscated in the configuration file. ft_ssl_password ft_ssl_password = password Private key or password for private keys. or PKCS#12 format. or you can specify a path to a file that contains the key. See Chapter 6. PKCS#12. You can set passwords by way of the tibemsadmin tool. ft_ssl_private_key ft_ssl_private_key = key The server’s private key. or PKCS#12 format. This parameter supports private keys in the following formats: PEM. DER. signifying the server should verify the other server’s certificate. if one is installed. ft_ssl_verify_hostname ft_ssl_verify_hostname = enabled | disabled Specifies whether the fault-tolerant server should verify the name in the CN field of the other server’s certificate. the fault-tolerant server establishes secure communication with the other server. the server establishes secure communication with the other fault-tolerant server. When this parameter is set to disabled.180 | Chapter 7 Using the Configuration Files ft_ssl_trusted ft_ssl_trusted = trusted_certificates List of trusted certificates. You can either provide the actual certificates. but does not verify the server’s name. this parameter is enabled. The values for this parameter are enabled or disabled. If the names do not match. DER. By default. This daemon is used to generate random numbers for the EMS server. but does not verify the server’s identity. See File Names for Certificates and Keys on page 369 for more information on file types for digital certificates. This sets which Certificate Authority certificates should be trusted as issuers of the client certificates. ft_ssl_rand_egd ft_ssl_rand_egd = pathname The path for the installed entropy gathering daemon (EGD). this parameter is enabled. The values for this parameter are enabled and disabled. or PKCS#7 format. the connection is rejected. signifying the fault-tolerant server should verify the name of the connected host or the name specified in the ft_ssl_expected_hostname parameter against the value in the server’s certificate. When this parameter is set to disabled. The certificates must be in PEM. TIBCO Enterprise Message Service User’s Guide . or you can specify a path to a file containing the certificate chain. By default. ft_ssl_verify_host ft_ssl_verify_host = enabled | disabled Specifies whether the fault-tolerant server should verify the other server’s certificate. each suite in the list is separated by a colon (:). This parameter is used when the ft_ssl_verify_hostname parameter is set to enabled. This parameter can use the OpenSSL name for cipher suites or the longer. ft_ssl_ciphers ft_ssl_ciphers = cipherSuite Specifies the cipher suites used by the server.conf 181 | ft_ssl_expected_hostname ft_ssl_expected_hostname = serverName Specifies the name the server is expected to have in the CN field of the fault-tolerant server’s certificate. Enabling this parameter allows you to display messages using the show messageID command in the administration tool.tibemsd. If this parameter is not set. Default is disabled. more descriptive names. messages Enabling this parameter allows you to display messages using the show correlationID command in the administration tool. See Specifying Cipher Suites on page 376 for more information about the cipher suites available in EMS and the OpenSSL names and longer names for the cipher suites. the expected name is the hostname of the server. TIBCO Enterprise Message Service User’s Guide . track_correlation_ids track_correlation_ids = enabled | disabled message Tracks messages by correlation ID. Message Tracking Parameters track_message_ids track_message_ids = enabled | disabled Tracks messages by message ID. Disabled by default. then enable this parameter to revert to the earlier behavior (strings). Chapter 12. tibrv_transports tibrv_transports = enabled | disabled Specifies whether TIBCO Rendezvous transports defined in transports.) TIBCO SmartSockets Parameters See also. Working With TIBCO SmartSockets. XML fields translate to strings.0 erroneously translated them to strings. all transports are disabled and will neither send messages to external systems nor receive message from them. on page 325. If your client programs process XML as strings. (When importing from SmartSockets. This behavior is correct for SmartSockets. disabled—that tibrv_xml_import_as_string tibrv_xml_import_as_string = enabled | disabled When importing messages from Rendezvous. Releases earlier than 4.conf are enabled or disabled. Chapter 11. Working With TIBCO Rendezvous. Unless you explicitly set this parameter to enabled. tibss_transports tibss_transports = enabled | disabled Specifies whether TIBCO SmartSockets transports defined in transports. When absent. even though it differs from the correct behavior for Rendezvous. TIBCO Enterprise Message Service User’s Guide . on page 299. Unless you explicitly set this parameter to enabled.conf are enabled or disabled.182 | Chapter 7 Using the Configuration Files TIBCO Rendezvous Parameters See also. the default value is disabled—that is. the default value is disabled (byte arrays). all transports are disabled and will neither send messages to external systems nor receive message from them. tibemsd translates XML fields to byte arrays. the default value is is. Monitoring Server Activity. TIBCO Enterprise Message Service User’s Guide . When this parameter is absent. is an optional file of SmartSockets RTclient configuration tibems_ss. see Table 61. tibemsd outputs a warning message. . The value of this parameter is a comma-separated list of trace options. If logfile is not set. For more information about these files.A trace option preceded by .tibemsd. Server tracing options. Tracing and Log File Parameters See Chapter 13. on page 347 for more information about these parameters. + A trace option preceded by + adds the option to the current set of trace options. You may specify trace options in three forms: • • • plain A trace option without a prefix character replaces any existing trace options. the values have no effect. logfile logfile = pathname Name and location of the server log file. log_trace log_trace = traceOptions Sets the trace preference on the file defined by the logfile parameter.removes the option from the current set of trace options.cm options.conf 183 | tibss_config_dir tibss_config_dir = pathname Specifies the directory for SmartSockets configuration files and message files: • • tal_ss. on page 350.cat is a required file of messages. see TIBCO SmartSockets User’s Guide. If it is missing. tibemsd searches for these files in its current working directory. For a list of trace options and their meanings. If it is greater than the specified size. This example sends a trace message to the console when a TIBCO Rendezvous advisory message arrives. If logfile is defined. or GB for units (if no units are specified. overriding the trace settings. the file is copied to a backup and then emptied. Backup log files are named sequentially and stored in the same directory as the current log. However. Use KB. log_trace=DEFAULT. log_trace=ACL The next example sets the trace log to show all default trace messages. console_trace console_trace = traceOptions Sets trace options for output to stderr. console_trace=RVADV TIBCO Enterprise Message Service User’s Guide .184 | Chapter 7 Using the Configuration Files The following example sets the trace log to only show messages about access control violations. in addition to SSL messages. The server then begins writing to the empty log file until it reaches the specified size again. The possible values are the same as for log_trace. The server periodically checks the size of the current log file. but ADMIN messages are not shown. the file size is assumed to be in bytes). console tracing is independent of log file tracing. you can stop console output by specifying: console_trace=-DEFAULT Note that important error messages (and some other messages) are always output.+SSL logfile_max_size logfile_max_size = size [KB|MB|GB] Specifies the recommended maximum log file size before the log file is rotated. Set to 0 to specify no limit. MB.-ADMIN. You can specify either user. connid The default behavior is to trace all connections. the value does not persist across server restarts unless you set it in the configuration file. Each client sends trace output to location. which may be either stderr (the default) or stdout.conf. the default is hostname. and transaction activity.conf 185 | client_trace client_trace = {enabled|disabled} [target=location] [user|connid|clientid=value] Administrators can trace a connection or group of connections.tibemsd. or clientid to selectively trace specific connections. that is. When absent. the server instructs each client to generate trace output for opening or closing a connection. The value can be a user name or ID (as appropriate). Setting this parameter using the administration tool does not change its value in the configuration file tibemsd. message activity. its IP address. trace_client_host trace_client_host = [hostname|address|both] Trace statements related to connections can identify the host by its hostname. This type of tracing does not require restarting the client program. or both. TIBCO Enterprise Message Service User’s Guide . When this property is enabled. and consumers are averaged. so this parameter cannot be set to zero. and routes. destinations. statistics statistics = enabled | disabled Enables or disables statistic gathering for producers. this parameter is set to 1. By default. server_rate_interval server_rate_interval = seconds Sets the interval (in seconds) over which overall server statistics are averaged. on page 347 for more information about these parameters. Setting this parameter allows you to average message rates and message size over the specified interval. Setting this parameter to zero disables the average calculation. producers. rate_interval rate_interval = seconds Sets the interval (in seconds) over which statistics for routes.186 | Chapter 7 Using the Configuration Files Statistic Gathering Parameters See Chapter 13. By default this parameter is set to disabled. TIBCO Enterprise Message Service User’s Guide . Overall server statistics are always gathered. This parameter can be set to any positive integer greater than zero. consumers. Monitoring Server Activity. Disabling statistic gathering resets the total statistics for each object to zero. destinations. this parameter is set to 3 seconds. By default. statistics for destinations with no activity are deleted. max_stat_memory max_stat_memory = size [KB|MB|GB] Specifies the maximum amount of memory to use for detailed statistic gathering. MB. If no units are specified. When the specified interval is reached. producers that specify no destination. Detailed statistic tracking is only appropriate for routes. the server stops collecting detailed statistics. For example: detailed_statistics = NONE Turns off detailed statistic tracking. Once the maximum memory limit is reached. When detailed tracking is enabled. the server resumes detailed statistic gathering. detailed_statistics = PRODUCERS. or ROUTES to enable tracking for each object. statistics_cleanup_interval statistics_cleanup_interval = seconds Specifies how long (in seconds) the server should keep detailed statistics if the destination has no activity. This is useful for controlling the amount of memory used by detailed statistic tracking. the amount is in bytes. statistics for each destination are kept for the object. If you specify more than one type of detailed tracking. CONSUMERS. or consumers that specify wildcard destinations.tibemsd. If statistics are deleted and memory becomes available. separate each item with a comma. TIBCO Enterprise Message Service User’s Guide .ROUTES] Specifies which objects should have detailed statistic tracking. or GB as the units. Setting this parameter to NONE disabled detailed statistic tracking. otherwise you can specify the amount using KB.ROUTES Specifies detailed statistics should be gathered for producers and routes.conf 187 | detailed_statistics detailed_statistics = NONE | [PRODUCERS.CONSUMERS. You can specify any combination of PRODUCERS. Whether this parameter is set to enable or disable. If this parameter is set to disable. 1024. or a web address. 768. ssl_dh_size ssl_dh_size = [512 | 768 | 1024 | 2048] Size of the Diffie-Hellman key. The CN field is either a username. Using the SSL Protocol. ssl_use_cert_username ssl_use_cert_username = enable | disable If this parameter is set to enable. you can enable two cipher suites with the following setting: ssl_server_ciphers = RC4-MD5:RC4-SHA See Specifying Cipher Suites on page 376 for more information about the cipher suites available in EMS and the syntax for specifying them in this parameter. a client’s user name is always extracted from the CN field of the client’s digital certificate. clients that do have digital certificates are always authenticated against the certificates supplied to the ssl_server_trusted parameter. if the digital certificate is specified. The default value is 1024. ssl_require_client_cert ssl_require_client_cert = enable | disable If this parameter is set to enable. Connections from clients without certificates are denied. This parameter must follow the OpenSSL cipher string syntax. then connections are accepted from clients that do not have a digital certificate. Can be 512. each suite in the list is separated by a colon (:). an email address. TIBCO Enterprise Message Service User’s Guide .188 | Chapter 7 Using the Configuration Files SSL Server Parameters See Chapter 14. or 2048 bits. the server only accepts SSL connections from clients that have digital certificates. This key is not used for cipher suites available for export. ssl_server_ciphers ssl_server_ciphers = cipherSuites Specifies the cipher suites used by the server. on page 365 for more information about these parameters. For example. but you wish to designate a special username to use when the client’s username should be taken from the client’s digital certificate. A good example of this username would be anonymous.cert.conf 189 | ssl_cert_user_specname ssl_cert_user_specname = username This parameter is useful if clients are required to supply a username. A good example of the value of this parameter would be anonymous. You can specify the path to a file that contains the certificate in one of the supported formats.pem TIBCO Enterprise Message Service User’s Guide . and not taken from the digital certificate. All clients logging in as anonymous will have their user names taken from their digital certificates. you may wish all clients to specify their username when logging in. the value of this parameter is ignored if ssl_use_cert_username is set to in which case all client usernames are taken from their certificates. ssl_server_identity ssl_server_identity = certificate The server’s digital certificate in PEM.tibemsd. This means the ssl_use_cert_username parameter would be set to disable. or PKCS#12 format. enable. However. For example. If these formats are used and the private key is part of the digital certificate. This parameter has no effect for users that have no certificate. DER. The username is supplied by the user. This parameter must be specified if any SSL ports are listed in the listen parameter. Also. then setting ssl_server_key is optional. you may wish one username to signify that the client logging in with that name should have the name taken from the certificate. For example: ssl_server_identity = certs/server. The value specified by this parameter is the username that clients will use to log in when the username should be taken from their digital certificate. PEM and PKCS#12 formats allow the digital certificate to include the private key. DER. The server reads the certificates in the chain in the order they are presented in this parameter. You must specify a path to a file that contains the key. then this parameter is not needed. You can set passwords by way of the tibemsadmin tool. See Chapter 6.190 | Chapter 7 Using the Configuration Files ssl_server_key ssl_server_key = private_key The server’s private key. See File Names for Certificates and Keys on page 369 for more information on file types for digital certificates. the password is obfuscated in the configuration file. PKCS#7. TIBCO Enterprise Message Service User’s Guide . ssl_server_issuer ssl_server_issuer = chain_member Certificate chain member for the server. PKCS#12. tibemsd will ask for the password upon startup. If SSL is enabled. and the password is not specified with this parameter or on the command line. If it is included in the digital certificate in ssl_server_identity. or PKCS#12 format. DER. This password can optionally be specified on the command line when tibemsd is started. ssl_password ssl_password = password Private key or password for private keys. The same certificate can appear in multiple places in the certificate chain. The certificates must be in PEM. This parameter supports private keys in the following formats: PEM. Using the EMS Administration Tool. on page 101 for more information about using tibemsadmin to set passwords. When passwords are set with this tool. You can either provide the actual certificates. or PKCS#7 format. Specify only CA root certificates. the default is 24 hours. This file can be used to generate random numbers. This daemon is used to generate random numbers for C clients and the EMS server. For example: ssl_rand_file = tibemsd ssl_crl_path ssl_crl_path = pathname A non-null value for this parameter activates the server’s certificate revocation list (CRL) feature. or you can specify a path to a file containing the certificate chain. When this parameter is absent. The certificates must be in PEM. The server reads CRL files from this directory. ssl_rand_egd ssl_rand_egd = pathname The path for the installed entropy gathering daemon (EGD). For example: ssl_server_trusted = certs\CA1_root. Java clients do not use this parameter. DER.tibemsd. ssl_crl_update_interval ssl_crl_update_interval = hours The server automatically updates its CRLs at this interval (in hours). TIBCO Enterprise Message Service User’s Guide . Do not include intermediate CA certificates.pem See File Names for Certificates and Keys on page 369 for more information on file types for digital certificates. if one is installed.conf 191 | ssl_server_trusted ssl_server_trusted = certificates List of CA root certificates the server trusts as issuers of client certificates. ssl_rand_file ssl_rand_file = pathname File containing random data.pem ssl_server_trusted = certs\CA2_root. the default value is disabled. Authentication and Permissions.192 | Chapter 7 Using the Configuration Files ssl_auth_only ssl_auth_only = enable | disable When enabled. This is the user that the EMS sever uses to bind to the LDAP server. TIBCO Enterprise Message Service User’s Guide . When absent. For an overview of this feature. ldap_url URL of the external directory server. the server allows clients to request the use of SSL only for authentication (to protect user passwords). This can take the following forms: LDAP://host:tcp_port or LDAPS://host:ssl_port For example: LDAP://myLdapServer:1855 ldap_principal ldap_principal = DN The distinguished name (DN) of the LDAP administrator. This value must be specified and cannot be an empty string. For example: ldap_principal = "cn=Manager" ldap_credential ldap_credential = password The password associated with the user defined in the ldap_principal property. When disabled. LDAP Parameters See Chapter 8. see SSL Authentication Only on page 381. on page 221 for more information about these parameters. the server ignores client requests for this feature. ldap_tls_cacert_dir ldap_tls_cacert_dir = pathname When there are two or more CA certificates in the verify chain.conf 193 | ldap_cache_enabled ldap_cache_enabled = enable | disable Enables caching of LDAP data. ldaps—Use SSL on the LDAP connection (secure). the startTLS extension to the LDAP version 3 protocol startTLS—Use (secure). For backward compatibility. TIBCO Enterprise Message Service User’s Guide . This file contains the CA certificate that the EMS server trusts to sign the LDAP server’s certificate. • • • When this parameter is absent. ldap_tls_cacert_file ldap_tls_cacert_file = pathname You must specify one of these two parameters for secure connections. LDAP connections use TCP (non-secure). ldap_cache_ttl ldap_cache_ttl = seconds Specifies the maximum time (in seconds) that cached LDAP data is retained before it is refreshed. this is the default setting.tibemsd. ldap_conn_type ldap_conn_type = [ldaps | startTLS] Specifies the type of connection that the server uses to get LDAP information. the server scans this directory for CA certificates. this file is the source of random data for encryption. In addition to the actual cipher names. ldap_user_class ldap_user_class = class_name Name of the LDAP object class that stores users. use the private key in this file.194 | Chapter 7 Using the Configuration Files ldap_tls_cipher_suite ldap_tls_cipher_suite = cipher_suite Optional. This parameter must follow the OpenSSL cipher string syntax. For example: ldap_user_class = person TIBCO Enterprise Message Service User’s Guide . ldap_tls_cert_file ldap_tls_cert_file = pathname When the LDAP server requires client authentication. for example: • • ldap_tls_rand_file ldap_tls_rand_file = HIGH HIGH:MEDIUM pathname When the operating system does not include a random data feature. ldap_tls_key_file ldap_tls_key_file = pathname When the LDAP server requires client authentication. you may specify cipher quality. You can specify the cipher suite to use for encryption on secure LDAP connections. on page 221 for more information about these parameters. See Chapter 8. use the certificate in this file to identify the EMS server. Authentication and Permissions. When you plan to start the server remotely. see Specifying Cipher Suites on page 376. we recommend that you do not password-encrypt the key file. For example: uid=%s The full LDAP search grammar is specified in RFC 2254 and RFC 2251. subtree specifies to search all sub-trees. onelevel specifies to search only one level below the DN. If unspecified.conf 195 | ldap_user_attribute ldap_user_attribute = attribute Name of the attribute on the user object class that holds the name of the user. TIBCO Enterprise Message Service User’s Guide .dc=Corp" ldap_user_scope ldap_user_scope = onelevel | subtree Specifies how deeply under the base DN to search for users. For example: ldap_user_scope = subtree ldap_user_filter ldap_user_filter = filter Optional LDAP search filter for finding a given user name. then a default search filter is generated based on the user object class and user name attribute. Use %s as the placeholder for the user name in the filter. For example: ldap_user_attribute = uid ldap_user_base_dn ldap_user_base_dn = DN Base distinguished name (DN) of the LDAP tree that contains the users. For example: ldap_user_base_dn = "ou=People.tibemsd. You can specify onelevel and subtree for this parameter. onelevel specifies to search only one level below the DN. Authentication and Permissions. subtree specifies to search all sub-trees. If not specified. then a default search filter is generated based on the group object class and group attribute. For example: ldap_group_filter = "(|(&(cn=%s)(objectClass=groupofUniqueNames))(&(cn=%s) (objectClass=groupOfURLs)))" TIBCO Enterprise Message Service User’s Guide . If unspecified. See Chapter 8. You can specify onelevel and subtree for this parameter. ldap_group_base_dn ldap_group_base_dn = DN Base distinguished name (DN) of the LDAP tree that contains groups. For example: ldap_group_scope = subtree ldap_group_filter ldap_group_filter = filter Optional LDAP search filter for finding a group with a given group name. then a default search filter is generated based on the user object class and user name attribute.dc=Corp" ldap_group_scope ldap_group_scope = onelevel | subtree Specifies how deeply under the base DN to search for groups. Use %s as the placeholder for the group name in the filter.196 | Chapter 7 Using the Configuration Files ldap_all_users_filter ldap_all_users_filter = filter An optional LDAP search filter for finding all users beneath the user base DN. The full LDAP search grammar is specified in RFC 2254 2251. on page 221 for more information about these parameters. For example: ldap_group_base_dn = "ou=Groups. ldap_static_group_class ldap_static_group_class = name Name of the LDAP object class that stores static groups. For example: ldap_static_member_attribute = uniquemember ldap_dynamic_group_class ldap_dynamic_group_class = class Name of the LDAP object class that stores dynamic groups.tibemsd. If unspecified. For example: ldap_static_group_class = groupofuniquenames ldap_static_group_attribute ldap_static_group_attribute = class Name of the attribute on the static group object class that holds the name of the group.conf 197 | ldap_all_groups_filter ldap_all_groups_filter = filter Optional LDAP search filter for finding all groups beneath the group base DN. For example: ldap_dynamic_group_class = groupofURLs TIBCO Enterprise Message Service User’s Guide . then a default search filter is generated based on the group object class and group attribute. For example: ldap_static_group_attribute = cn ldap_static_member_attribute ldap_static_member_attribute = attribute Attribute of an LDAP static group object that specifies the distinguished names (DNs) of the members of the group. For example: ldap_dynamic_group_attribute = cn ldap_dynamic_member_url_attribute ldap_dynamic_member_url_attribute = attribute Attribute of the dynamic LDAP group object that specifies the URLs of the members of the dynamic group. Replaced by server_timeout_client_connection on page 176. Replaced by client_heartbeat_server on page 176. the default is 5 seconds. clients send heartbeats at this interval (in seconds).5 times the heartbeat interval. if the server does not receive a heartbeat for a period exceeding this limit (in seconds). which disables heartbeat detection in the server (although clients still send heartbeats). it closes the connection. TIBCO Enterprise Message Service User’s Guide . Zero is a special value. We recommend setting this value to approximately 3.198 | Chapter 7 Using the Configuration Files ldap_dynamic_group_attribute ldap_dynamic_group_attribute = attribute Name of the attribute on the dynamic group object class that holds the name of the group. When omitted or zero. For example: ldap_dynamic_member_url_attribute = memberURL Detecting Network Connection Failure Parameters—Deprecated client_heartbeat client_heartbeat interval In a server-to-client connection. client_connection_timeout client_connection_timeout limit In a server-to-client connection. tibemsd. TIBCO Enterprise Message Service User’s Guide . When the other server or the network are heavily loaded. We recommend setting this value to approximately 3. it closes the connection. or when client programs send very large messages. Replaced by server_heartbeat_server on page 177. Replaced by server_timeout_server_connection on page 177. if this server does not receive a heartbeat for a period exceeding this limit (in seconds). or as a fault-tolerant pair.conf 199 | server_heartbeat server_heartbeat interval In a server-to-server connection. this server sends heartbeats at this interval (in seconds).5 times the heartbeat interval of the other server. server_connection_timeout server_connection_timeout limit In a server-to-server connection. we recommend a larger multiple. The two servers can be connected either by a route. conf bridges. Defines EMS groups. Defines bridges between destinations.conf 215 durables. on page 101 for more information about using the administration tool. such as Rendezvous and SmartSockets. Defines EMS Queues. Defines routes between this and other EMS servers Defines the connection factories stored as JNDI names on the EMS server.200 | Chapter 7 Using the Configuration Files Using Other Configuration Files In addition to the main configuration file.conf queues.conf transports.conf 216 These configuration files can be edited by hand. Defines EMS Topics. Using the EMS Administration Tool. there are several other configuration files used for various purposes: Table 36 Configuration Files Configuration File users.conf routes. TIBCO Enterprise Message Service User’s Guide . The following sections describe the configuration files.conf factories. Defines transports used by EMS to import messages from or export messages to external message service.conf Description Defines EMS users. Defines the TIBCO Rendezvous certified messaging (RVCM) listeners for use by topics that export messages to a tibrvcm transport.conf acl. Defines static durable subscribers.conf groups. See Page 201 202 202 203 203 205 206 208 212 tibrvcm. Defines EMS access control lists. See Chapter 6.conf topics. but you can also use the administration tool or the administration APIs to modify some of these files. the administrator. description A string describing the user.conf This file defines all users. The format of the file is: username:password:"description" Parameter Name username password Description The name of the user Leave this item blank when creating a new user. on page 104. The administrator password is not entered in this configuration file. Assign a Password to the Administrator. see . Example admin: $1$urmKVgq78:"Administrator" Bob::"Bob Smith" Bill::"Bill Jones" TIBCO Enterprise Message Service User’s Guide .Using Other Configuration Files 201 | users. and it will not be assigned by the system. It will remain empty (and therefore not secure) until you set it using the administration tool. This is assigned by the system when the user chooses a password. For example: bob::"Bob Smith" There is one predefined user. 1 and test.* has the property secure. import="RV01. . maxbytes=1MB Only topics listed in this file or topics with names that match the topics listed in this file can be created by the applications. For example. A string describing the group. see Destination Properties on page 46..baz can be created by the application. if test. The format of the file is: topic-name property1. For information on properties that can be assigned to topics.RV02".conf This file defines all topics. Example administrators: "TIBCO Enterprise Message Service administrators" admin Bob topics. One or more users that belong to the group. export="RV03".conf This file defines all groups.inventory global. For example. refer to Wildcards * and > on page 63 and Inheritance of Properties on page 66. topics foo.202 | Chapter 7 Using the Configuration Files groups. For example.bar and foo. property2. For further information on the inheritance of topic properties. you might enter: business. The format of the file is: group-name1:"description" user-name1 user-name2 group-name2:"description" user-name1 user-name2 Parameter Name group-name description user-name Description The name of the group. if topic foo. Properties of the topic are inherited by all static and dynamic topics with matching names.* is listed in this file.foo are also secure. then test. TIBCO Enterprise Message Service User’s Guide .. baz can be created by the application. For example.conf This file defines all permissions on topics and queues for all users and groups.conf This file defines all queues. a > wildcard at the beginning of the file allows the applications to create valid queues with any name. acl. Name of the queue to which you wish to add permissions. QUEUE ADMIN TIBCO Enterprise Message Service User’s Guide . A > at the beginning of the queue (or topic) configuration file means that name-matching is not required for creation of queues (or topics).. . For example.bar and foo. then test.. For example. For further information on the inheritance of queue properties. property2.Using Other Configuration Files 203 | queues.foo are also secure.1 and test.secure. if queue foo. refer to Wildcards * and > on page 63 and Inheritance of Properties on page 66. Properties of the queue are inherited by all static and dynamic queues with matching names. The format of the file is: queue-name property1.* has the property secure. queues foo. For information on properties that can be assigned to queues. see Destination Properties on page 46. The format of the file is: TOPIC=topic USER=user PERM=permissions TOPIC=topic GROUP=group PERM=permissions QUEUE=queue USER=user PERM=permissions QUEUE=queue GROUP=group PERM=permissions ADMIN USER=user PERM=permissions ADMIN GROUP=group PERM=permissions Parameter Name TOPIC Description Name of the topic to which you wish to add permissions. you might enter: test failsafe. In the sample file.* is listed in this file. if test.prefetch=2 Only queues listed in this file or topics with names that match the topics listed in this file can be created by the applications. Specifies that you wish to add administrator permissions. Administration permissions are granted to users to perform administration activities.204 | Chapter 7 Using the Configuration Files Parameter Name USER Description Name of the user to whom you wish to add permissions. refer to When Permissions Are Checked on page 242 and Inheritance of Permissions on page 67. GROUP PERM Example ADMIN USER=sys-admins PERM=all TOPIC=foo USER=user2 PERM=publish. The permissions which can be assigned to queues are send. Permissions to add.subscribe TOPIC=foo GROUP=group1 PERM=subscribe TIBCO Enterprise Message Service User’s Guide . Name of the group to which you wish to add permissions. subscribe and durable and use_durable. receive and browse. The permissions which can be assigned to topics are publish. The designation all specifies all possible permissions. The designation all specifies a predefined group that contains all users. For information about these permissions. See Administrator Permissions on page 223 for more information about administration permissions. see the ’Message Selectors’ section in description for the Message class in TIBCO Enterprise Message Service Java API Reference. See Destination Bridges on page 68 for more information about destination bridges. This optional property specifies a message selector to limit the messages received by the bridged destination.. destinationName destinationToBridgeTo selector Example [topic:myTopic1] topic=myTopic2 queue=myQueue1 TIBCO Enterprise Message Service User’s Guide .conf This file defines bridges between destinations. The destination-name can be any specific destination or a wildcard pattern to match multiple destinations. Parameter Name destinationType Description The type of the destination.Using Other Configuration Files 205 | bridges. topic or queue..include brackets destinationType=destinationToBridgeTo1 [selector="message-selector"] destinationType=destinationToBridgeTo2 [selector="message-selector"] . The format of the file is: [destinationType:destinationName] # mandatory -. For detailed information about message selector syntax. One or more names of destinations to which to create a bridge. That is. The name of the destination. see these sections: • • Zone on page 406 Configuring Routes and Zones on page 410 url zone_name TIBCO Enterprise Message Service User’s Guide . When absent. The format of the file is: [route-name] # mandatory -. The route belongs to the routing zone with this name. Note that the square brackets [ ] DO NOT indicate that the route-name is an option.0). it also becomes the name of the route.square brackets included. For further information.conf This file defines routes between this TIBCO Enterprise Message Service server and other TIBCO Enterprise Message Service servers.206 | Chapter 7 Using the Configuration Files routes. they must be included around the name. the default value is default_mhop_zone (this default yields backward compatibility with configurations from releases earlier than 4. The URL of the server to and from which messages are routed. but you cannot subsequently change it. url=url-string zone_name=zone_name zone_type=zone_type [selector]* [ssl-prop = value]* (Sheet 1 of 2) Parameter Name [route-name] Description [route-name] is the name of the passive server (at the other end of the route). You can set this parameter when creating a route. You can set this parameter when creating a route. ssl-prop SSL properties for this route. The EMS server will refuse to start up if the zone type in the routes. Example [test_route_2] url = tcp://server2:7222 ssl_verify_host = disabled TIBCO Enterprise Message Service User’s Guide . the default value is mhop. page 365. For further information on SSL.Using Other Configuration Files 207 | (Sheet 2 of 2) Parameter Name zone_type Description The zone type is either 1hop or mhop. refer to Chapter 14. For syntax and semantics. see Selectors for Routing Topic Messages on page 417. When omitted. Using the SSL Protocol.conf file does not match the zone type already created in the meta. selector Topic selectors (for incoming_topic and outgoing_topic parameters) control the flow of topics along the route. but you cannot subsequently change it.db file that holds the shared state for the primary and backup server. 2b) Queue connection (JMS 1. Type of the connection factory. Note that the square brackets [ ] DO NOT indicate that the factory-name is an option.2b) xatopic: xaqueue: TIBCO Enterprise Message Service User’s Guide .square brackets included type = generic|xageneric|topic|queue|xatopic|xaqueue| url = url-string metric = connections | byte_rate clientID = client-id [connect_attempt_count|connect_attempt_delay| connect_attempt_timeout|reconnect_attempt_count| reconnect_attempt_delay|reconnect_attempt_timeout = value] [ssl-prop = value]* (Sheet 1 of 3) Parameter Name [factory-name] Description [factory-name] is the name of the connection factory. The value can be: • • • • • • generic: type Generic connection (JMS 1.0. The file consists of factory definitions with this format: [factory-name] # mandatory -.0. they must be included around the name.0.1) xageneric: topic: queue: Topic connection (JMS 1.conf This file defines the connection factories for the internal JNDI names.208 | Chapter 7 Using the Configuration Files factories.1) Generic XA connection (JMS 1.2b) XA topic connection (JMS 1.0.2b) XA queue connection (JMS 1. see Load Balancing on page 211.tcp://a2:8222|tcp://b1:8222. For example: tcp://host1:8222. For example: tcp://host1:8222 • A pair of URLs separated by a comma specifies a pair of fault-tolerant servers. The client program checks the load on the primary a server and the primary b server. byte_rate—Connect to the server with the lowest byte rate. metric The factory uses this metric to balance the load among a group of servers: • • connections—Connect to the server with the fewest client connections.Using Other Configuration Files 209 | (Sheet 2 of 3) Parameter Name url Description This string specifies the servers to which this factory creates connections: • A single URL specifies a unique server. For example: tcp://a:8222|tcp://b:8222|tcp://c:8222 • You can combine load balancing with fault tolerance. When this parameter is absent.tcp://backup1:8222 • A set of URLs separated by vertical bars specifies a load balancing among those servers. the default metric is connections. This example defines two servers (a and b). and connects to the one that has the smaller load. see Load Balancing on page 211. TIBCO Enterprise Message Service User’s Guide . For cautionary information. Byte rate is a statistic that includes both inbound and outbound data.). For example: tcp://a1:8222. each of which has a fault-tolerant backup.tcp://b2 :8222 The load balancing operator (|) takes precedence over the fault-tolerance operator (. For cautionary information. This property determines the maximum number of iterations. Connection Factory Properties Connection factory properties override corresponding properties set using API calls. When attempting to reconnect. you can set this connection timeout period to abort the connection attempt after a specified period of time (in milliseconds). When attempting to reconnect to the EMS server. refer to Chapter 14. the default is 500 milliseconds. Using the SSL Protocol. the default is 4. When absent. a client program configured with more than one server URL attempts to reconnect. When absent. you can set this connection timeout period to abort the connection attempt after a specified period of time (in milliseconds).210 | Chapter 7 Using the Configuration Files (Sheet 3 of 3) Parameter Name clientID Description The factory associates this client ID string with the connections that it creates. the client sleeps for this interval (in milliseconds) between attempts to connect to its server (or in fault-tolerant configurations. the client sleeps for this interval (in milliseconds) between iterations through its URL list. When attempting to connect to the EMS server. the default is 2. For further information on SSL. When absent. iterations through its URL list). the default is 500 milliseconds. connect_attempt_delay connect_attempt_timeout reconnect_attempt_count reconnect_attempt_delay reconnect_attempt_timeout ssl-prop TIBCO Enterprise Message Service User’s Guide . connect_attempt_count A client program attempts to connect to its server (or in fault-tolerant configurations. When attempting a first connection. After losing its server connection. page 365. This property determines the maximum number of iterations. SSL properties for connections that this factory creates. When absent. iterating through its URL list until it re-establishes a connection with an EMS server. it iterates through its URL list) until it establishes its first connection to an EMS server. If the client program exits and restarts. pending messages on server A remain there until the client reconnects to server A. then server B creates and supports a new durable subscription— however. then server A creates and supports the durable subscription. Do not specify load balancing when your application requires strict message ordering. see create factory on page 109. If a client program that a creates durable subscriber connects to server A using a load-balanced connection factory.Using Other Configuration Files 211 | Example [north_america] type = topic url = tcp://localhost:7222. and this time connects to server B. Load balancing chooses from among multiple servers. TIBCO Enterprise Message Service User’s Guide . Load Balancing Do not specify load balancing in situations with durable subscribers.tcp://server2:7222 clientID = "Sample Client ID" ssl_verify_host = disabled Configuration To configure connection factories in this file. we recommend using the tibemsadmin tool. which inherently violates strict ordering. such as TIBCO Rendezvous and TIBCO SmartSockets. Transport type.conf This file defines transports for importing messages from or exporting messages to external message services. Note that the square brackets [ ] DO NOT indicate that the transport_name is an option. Rendezvous clients cannot set this header. However. they must be included around the name. the default is TIBEMS_NON_PERSISTENT. these two parameters determine the delivery modes for all topic messages and queue messages that tibemsd imports on this transport. TIBCO Enterprise Message Service User’s Guide .212 | Chapter 7 Using the Configuration Files transports. The format of the file is: [transport_name] # mandatory -.square brackets included type = tibrv | tibrvcm | tibss # mandatory [topic_import_dm = TIBEMS_PERSISTENT | TIBEMS_NON_PERSISTENT | TIBEMS_RELIABLE] [queue_import_dm = TIBEMS_PERSISTENT | TIBEMS_NON_PERSISTENT | TIBEMS_RELIABLE] [export_headers = true | false] [export_properties = true | false] transport-specific-parameters Parameter Name [transport_name] Description The name of the transport. • • • tibrv type identifies TIBCO Rendezvous transport tibrvcm identifies TIBCO Rendezvous Certified Messaging transport identifies TIBCO SmartSockets transport tibss Each transport includes additional transport-specific-parameters: topic_import_dm queue_import_dm EMS sending clients can set the JMSDeliveryMode header field for each message. TIBEMS_PERSISTENT | TIBEMS_NON_PERSISTENT | TIBEMS_RELIABLE When absent. Instead. When false. the extended syntax is: rv_tport = name # mandatory [cm_name = name] [ledger_file = file-name] [sync_ledger = true | false] [request_old = true | false] [explicit_config_only = true | false] [default_ttl = seconds] See Rendezvous Certified Messaging (RVCM) Parameters on page 303 for descriptions. tibemsd suppresses JMS properties in exported messages. If type = tibrvcm. tibemsd includes JMS properties in exported messages. When false. When absent. Transport-specific Parameters If type = tibrv. export_properties When true. When absent. the server will continue to traverse through the entries and attempt to create further transports. tibemsd includes JMS header fields in exported messages. tibemsd suppresses JMS header fields in exported messages. the default value is true. If you have multiple TIBCO Rendezvous transports configured in your transports. the extended syntax is: [service = service] [network = network] [daemon = daemon] [temp_destination_timeout = seconds] See Rendezvous Parameters on page 302 for descriptions. the default value is true. transport-specificparameters See Transport-specific Parameters. TIBCO Enterprise Message Service User’s Guide . and if the EMS server fails to create a transport based on the last entry.conf file.Using Other Configuration Files 213 | Parameter Name export_headers Description When true. store sync_ledger = true request_old = true default_ttl = 600 [SS01] type = tibss server_names = tcp:rtHost2A:5555. Example [RV01] type = tibrv topic_import_dm = TIBEMS_RELIABLE queue_import_dm = TIBEMS_PERSISTENT service = 7780 network = lan0 daemon = tcp:host5:7885 [RVCM01] type = tibrvcm export_headers = true export_properties = true rv_tport = RV02 cm_name = RVCMTrans1 ledger_file = ledgerFile.214 | Chapter 7 Using the Configuration Files If type = tibss. ssl:rtHost2B:5571 username = emsServer6 password = myPasswd project = mfg_process_control override_lb_mode = enable delivery_mode = gmd_some TIBCO Enterprise Message Service User’s Guide . the extended syntax is: [username = name] [password = password] [server_names = single_or_list_of_servers] [project = name] [delivery_mode = best_effort | gmd_all | gmd_some | ordered] [lb_mode = none | round_robin | weighted | sorted] [override_lb_mode = enable | disable] [gmd_file_delete = enable | disable] [import_ss_headers = none | type_num | all] [subscribe_mode = all | exact] [preserve_gmd = always | receivers | never] See SmartSockets Parameters on page 328 for descriptions. The server preregisters these listeners when the server starts up so that all messages (including the first message published) sent by way of the tibrvcm transport are guaranteed. The format of this file is transport listenerName subjectName Parameter Name transport listenerName Description The name of the transport for this RVCM listener. This should be the same name as the topic names that specify the export property.conf This file defines the TIBCO Rendezvous certified messaging (RVCM) listeners for use by topics that export messages to a tibrvcm transport. subjectName Example RVCM01 listener1 foo. The name of the RVCM listener to which topic messages are to be exported.bar TIBCO Enterprise Message Service User’s Guide .bar.Using Other Configuration Files 215 | tibrvcm. the listeners are created when the first message is published. If the server does not preregister the RVCM listeners before exporting messages. The RVCM subject name that messages are published to. but the first message is not guaranteed.bar RVCM01 listener2 foo. The file consists of lines with either of these formats: topic-name durable-name [route] [clientid=id] [nolocal] [selector="sel"] Parameter Name topic-name durable-name route Description The topic of the durable subscription. and the durable-name is the name of that server. For detailed information about message selector syntax.nonlocal dName3 selector="urgency in (’high. see the ’Message Selectors’ section in description for the Message class in TIBCO Enterprise Message Service Java API Reference.216 | Chapter 7 Using the Configuration Files durables. no other properties are permitted. clientid=id nolocal The client ID of the subscriber’s connection. selector="string" Example topic1 topic2 topic3 topic4 dName1 dName2 clientid=myId. When present. When present. When this property is present. the subscriber is another server. When present. The name of the durable subscriber.’medium’)" Paris route TIBCO Enterprise Message Service User’s Guide . this selector narrows the set of messages that the durable subscriber receives. the subscriber does not receive messages published from its own connection.conf This file defines static durable subscribers. An existing durable dynamically created by a client takes precedence over a new static durable defined by an administrator.*. if a client dynamically creates a durable subscriber for topic foo. For example. we recommend using the create command in the tibemsadmin tool. A static durable subscription takes precedence over a client attempting to dynamically unsubscribe (from the same topic and durable name). Consider these examples: • • • A static specification in this file takes precedence over a new durable dynamically created by a client. Configuration durable To configure durable subscriptions in this file. and writes a specification to the file durables. it maintains the earliest specification. then the server detects this conflict and warns the administrator. If the create durable command detects an existing dynamic durable subscription with the same topic and name. see create durable on page 109.1. it promotes it to a static subscription. and outputs a warning.conf.Using Other Configuration Files 217 | Conflicting Specifications When the server detects an conflict between durable subscribers. TIBCO Enterprise Message Service User’s Guide . and an administrator later attempts to define a static durable for topic foo. Conflict can also arise because of wildcards. 218 | Chapter 7 Using the Configuration Files TIBCO Enterprise Message Service User’s Guide . | 219 TIBCO Enterprise Message Service User’s Guide . 220 | Chapter 7 Using the Configuration Files TIBCO Enterprise Message Service User’s Guide . page 231 Users and Groups. EMS can also be configured to use an external directory (such as an LDAP server) to control access to the server. page 222 Administrator Permissions. page 223 Enabling Access Control. Topics • • • • • • EMS Access Control. You can also assign permissions to users and groups to control actions that can be performed on destinations. This chapter describes authentication and permissions in EMS. page 242 TIBCO Enterprise Message Service User’s Guide .| 221 Chapter 8 Authentication and Permissions You can create users and assign passwords to the users to control access to the EMS server. page 233 User Permissions. page 239 When Permissions Are Checked. Enable access control for the system. 5. See Users and Groups on page 233. and enable access control for those destinations. See Enabling Access Control on page 231. 1. Determine which destinations require access control. delete. 2. connections. assigning passwords. See Configuring an External Directory on page 235. 7. Determine the names of the authorized users of the system and create usernames and passwords for these users. 3. See Administrator Permissions on page 223 for more information. factories. Administrator permissions control the ability of a user to login as an administrator to create. Create the access control list by granting specific permissions to users (or groups) for destinations that need to be secure. 4. The following procedure describes the general process for administrators to configure users. TIBCO Enterprise Message Service User’s Guide . set up groups and assign users to groups. or view the status of users. and so on. Optionally enable an external directory for storing users and group information. and decide whether administrators can perform actions globally or be restricted to a subset of actions. Optionally. See Destination Control on page 232. groups. and permissions and where to find more information on performing each step. destinations. See User Permissions on page 239. Determine which users need administration permissions. 6. See Users and Groups on page 233. and setting permissions. Administrators with the correct permissions can control user access to the EMS server by creating users.222 | Chapter 8 Authentication and Permissions EMS Access Control EMS supports two basic access levels: administrative and user. purging a queue. Administrator permissions control what administrators can view and change in the server only when using the administration tool or API. administrators must be granted permission to perform administration activities when using the administration tool or API. routes. destinations. Use the facilities provided by your Operating System to control access to the server’s configuration files. and delete users. factories. When a user becomes a member of this group. predefined user named admin that can perform any administrative action. For more information about changing the admin password. In general. and so on). permission to create users or to view all queues).conf. and administrators can be granted permissions to perform operations on specific destinations (for example. or in the configuration files. If a user can view or modify the configuration files. the administration APIs. modify. Administrators must be created using the administration tool. Administrator commands create entries in each of the configuration files (for example. routes. Administrators create. You cannot grant or revoke any permissions to admin. tibemsd. There is also a special group named $admin for system administrator users. that user receives the same permissions as the admin user.Administrator Permissions 223 | Administrator Permissions Administrators are a special class of users that can manage the EMS server. You cannot grant or revoke administrator permissions from any user that is a member of the $admin group. see When You First Start tibemsadmin on page 104.conf. You should only assign the overall system administrator(s) to the $admin group. Administrators can be granted global permissions (for example. setting permissions to control which destination that user can manage would not be enforced when the user manually edits the files. and other items. acl.conf. TIBCO Enterprise Message Service User’s Guide . You must assign a password for admin immediately after installation. You should control access to the configuration files so that only certain system administrators can view or modify the configuration files. Predefined Administrative User and Group There is a special. or viewing properties for a particular topic). For example. You can either grant global administrator permissions or permissions on specific destinations. See Global Administrator Permissions on page 226 for a complete list of global administrator permissions. See Command Listing on page 106 for the syntax of the grant and revoke commands. The users will be able to perform any administrative action that is allowed by the permissions granted to the group to which the user belongs. administrators can only grant or revoke permissions to other users that have the same protection permission as the administrator. or by means of the Java or . If a user has both global and destination-level administrator permissions. If a user has the change-admin-acl permission. that administrator can view information about all destinations. Global and destination-level permissions are granted and revoked separately using different administrator commands. Users have all administrator permissions that are granted to any group to which they belong. All other users must be granted the change-admin-acl permission and the view-user and/or the view-group permissions before they can grant or revoke administrator permissions to other users. The admin user or all users in the $admin group can grant or revoke any administrator permission to any user. that user can only grant or revoke permissions that have been granted to the user. grant administrator permissions to those groups. For example. Any destination-level permission granted to a user or group for a wildcard destination is inherited for all child destinations that match the parent destination.NET admin API. You can create administrator groups. TIBCO Enterprise Message Service User’s Guide . the actions that user can perform are determined by combining all global and destination-level administrator permissions granted to the user. See Protection Permissions on page 230 for more information about protection permissions. even if the view permission is not granted to the administrator for specific destinations.224 | Chapter 8 Authentication and Permissions Granting and Revoking Administration Permissions You grant and revoke administrator permissions to users using the grant and revoke commands in tibemsadmin. See Destination-Level Permissions on page 228 for a description of administrator permissions for destinations. If protection permissions are set up. if user BOB is not part of the $admin group and he has only been granted the change-admin-acl and view-user permissions. BOB cannot grant any administrator permissions except the view-user or change-admin-acl permissions to other users. if an administrator is granted the view-destination permission. and then add users to each administrator group. For example. If the administrative user attempts to execute a command without permission. an administrator has been granted the view permission on the foo.foo command.*. TIBCO Enterprise Message Service User’s Guide . the administrator is only able to view the access control list for destinations that match the foo. Any access control lists for other destinations are not displayed when the administrator performs the showacl topic or showacl queue commands. If this administrator is granted the global view-acl permission. An administrator can always view his/her own permissions by issuing the: show acl username command.* parent. the administrator receives a “Not authorized to execute command” error because the administrator is not authorized to view any destination except those that match foo.Administrator Permissions 225 | Enforcement of Administrator Permissions An administrator can only perform actions for which the administrator has been granted permission. if the administrator issues the showacl queue bar. This administrator has not been granted the global view-destination permission. the user may either receive an error or simply see no output. even if the administrator is not granted the change-user permission. even if the administrator is not granted the view-acl permission.* parent destination. Any action that an administrator performs may be limited by the set of permissions granted to that administrator.* destination. An administrator can always change his/her own password. For example. The administrator is only able to view destinations that match the foo. and modify routes Modify server parameters. Create and delete destination bridges. Delete messages stored in the server. Create any destination. Perform all administrative commands.. topics. groups. delete. Grant and revoke administrative permissions. Create. and modify users. and modify factories. Table 37 describes the global administrator permissions. Delete durable subscribers. users. Grant and revoke user-level permissions.226 | Chapter 8 Authentication and Permissions Global Administrator Permissions Certain permissions allow administrators to perform global actions.. and modify groups. such as creating users or viewing all queues. delete. delete. Create. delete. Create. Delete any destination. Delete connections. Table 37 Global administrator permissions (Sheet 1 of 2) Permission all view-all Allows Administrator To. Purge destinations. change-acl change-admin-acl change-bridge change-connection create-destination modify-destination delete-destination change-durable change-factory change-group change-message change-route change-server change-user purge-destination TIBCO Enterprise Message Service User’s Guide . View any item that can be administered (for example. Modify any destination. Create. and so on). ) view-bridge view-destination view-durable view-factory view-group View factories. Purge durable subscribers. view-message view-route view-server View messages stored in the server. producers and consumers. View server configuration and information. View all groups. View connections. View any user. you must also have view-destination permission (because information about a durable subscriber includes information about the destination to which it subscribes. View administrative permissions. View user-level permissions. To view a durable subscriber.Administrator Permissions 227 | Table 37 Global administrator permissions (Sheet 2 of 2) Permission purge-durable shutdown view-acl view-admin-acl view-connection Allows Administrator To. Shutdown the server.. View durable subscribers. View routes.. View destination properties and information. view-user TIBCO Enterprise Message Service User’s Guide . Granting this permission implicitly grants view-user as well. View destination bridges. if a user named BOB is granted the view-user global administration permission and the group sys-admins is granted the change-acl permission. granting any create.* topics. This allows you to specify particular destinations over which a group of users has administrative control. The typical use of destination-level administration permissions is to specify permissions on wildcard destinations for different groups of users. TIBCO Enterprise Message Service User’s Guide . Global permissions granted to a user override any destination-level permissions. change. and another group to control all PAYROLL. Therefore. modify. Destination-level permissions control the administration functions a user can perform on a specific destination. For example. the following entries are added to the acl. Global permissions in this file have the following syntax: ADMIN USER=<username> PERM=<permission> or ADMIN GROUP=<groupname> PERM=<permission> For example. delete. Granting the view permissions is useful when you want specific users to only be able to view items. or purge permission implicitly grants the permission to view the associated item.* queues. It is not necessary to grant the view permission if a user already has a permission that allows the user to modify the item.conf file: ADMIN USER=BOB PERM=view-user ADMIN GROUP=sys-admins PERM=change-acl Destination-Level Permissions Administrators can be granted permissions on each destination. Global permissions are stored in the acl. you may allow one group to control all ACCOUNTING.228 | Chapter 8 Authentication and Permissions Any type of modification to an item requires that the user can view that item. along with all other permissions.conf file. and so on).view Both user and administrator permissions for a destination are stored in the same entry in the acl. This is for convenience rather than for clarity. if the destination is a topic with durable subscriptions. TIBCO Enterprise Message Service User’s Guide . Either purge this queue. if user BOB has publish and subscribe permissions on topic foo. or purge implicitly grants the permission to view the associated item. change. modify. granting create.. delete modify purge Any type of modification to an item requires that the user can view that item.. send.conf file. For example.conf file. Administration permissions for a destination are stored alongside all other permissions for the destination in the acl. Table 38 Destination-level administration permissions Permission view create Allows Administrator To. This allows the user to create any destination that matches the specified parent. or purge the durable subscribers. Granting the view permissions is useful when you want specific users to only be able to view items. Delete this destination.Administrator Permissions 229 | Table 38 describes the destination-level administration permissions. Create the specified destination. View information for this destination. the acl listing would look like the following: TOPIC=foo USER=BOB PERM=publish. if the destination is a queue. subscribe. Administrator permissions specify what administrative commands the user can perform on the destination when using the administration tool or API.subscribe. User permissions specify the actions a client application can perform on a destination (publish. It is not necessary to grant the view permission if a user already has a permission that allows the user to modify the item. and then BOB is granted view permission. Therefore. Change the properties for this destination. delete. This permission is useful when used with wildcard destination names. receive. TIBCO Enterprise Message Service User’s Guide . admin2. This signifies that the user has all administrator privileges for anyone who also has the same protection permission. Within the system administrators. add member $admin mgr grant admin sales protect1 grant admin admin1 protect1. grant the same protection permission to the administrator that can perform actions on those users. protect3. protect2. manufacturing.all grant admin finance protect3 grant admin admin3 protect3. in addition to the all permission. An administrator can only perform administrative operations on a user that has the same protection permission as the user. there is one manager and three other administrators. Then. and admin3. However. there are four departments in a company: sales. To use protection permissions. Protection permissions do not apply to the admin user or users in the $admin group — these users can perform any action on any user regardless of protection permissions. and protect4) that allow you to create four groups of administrators. For example. or to a defined group(s)). if you revoke the all permission from a user. The following commands illustrate the grants necessary for creating the example administration structure. An administrator is able to view users that have a different protection permission set. and system administrators.all You can grant a protection permission. the user names of the other system administrators are admin1. The user name of the manager is mgr. Each of the other system administrators can only perform actions on members of the groups for which they are responsible. The manager of the system administrators can perform any administrator action. There are four protection permissions (protect1.all grant admin manufacturing protect2 grant admin admin2 protect2. all permissions. grant one of the protection permissions to a set of users (either individually. each responsible for administering the resources of the other departments. but the administrator can only perform actions on users with the same protection permission. including any protection permissions are removed from the access control list for the user.230 | Chapter 8 Authentication and Permissions Protection Permissions Protection permissions allow you to group users into administrative domains so that administrators can only perform actions within their domain. Each of these departments has a defined group and a set of users assigned to the group. finance. The authorization property also enables or disables verification of user names and passwords. the server grants any connection request. Or you can use the tibemsadmin tool to dynamically enable authorization with the following set server command: set server authorization=enabled Authorization does affect connections between fault-tolerant server pairs. the administrator must explicitly set authorization to enabled. The default setting is disabled. regardless of their protection permission because mgr is a member of the $admin group. Administrators must always log in with the correct administration username and password to perform any administrative function—even when authorization is disabled. When authorization is disabled. For secure deployments. Server Control The property in the main configuration file enables or disables the checking of permissions for all destinations managed by the server. However. or perform any other administrative action on users of the manufacturing or finance groups. either edit tibemsd. see Authorization and Fault-Tolerant Servers on page 395. TIBCO Enterprise Message Service User’s Guide . and restart the server). admin1 can perform any action on any user in the sales group. Administrators can also enable and disable permission checking for specific destinations. To enable authorization. and can view any users in the manufacturing or finance groups. When authorization is enabled. delete users from. admin1 is not able to grant permissions. change passwords.conf (set the authorization property to enabled. the server grants connections only from valid authenticated users. Enabling Access Control Administrators can enable or disable access control for the server. and does not check permissions when a client accesses a destination (for example. The server checks permissions for client operations involving secure destinations. publishing a message to a topic).Enabling Access Control 231 | For example. The mgr user is able to perform any action on any user. All operations by applications on the destination with secure enabled are verified by the server according to the permissions listed in acl.con. It does not affect the security of communication between clients and server. However. See Destination Properties on page 46 for more information about destination properties. The secure property controls only basic authentication and permission verification. operations on destinations. such as sending a message or receiving a message. TIBCO Enterprise Message Service User’s Guide . Destinations with secure disabled continue to operate without any restrictions. The secure property is independent of SSL-level security. are not verified unless the destination has enabled the secure property on the destination.232 | Chapter 8 Authentication and Permissions Destination Control When server authorization is enabled. When a destination does not have the secure property set. any authenticated user can perform any actions on that topic or queue. the server checks user names and password of all connections without exceptions. groups and permissions. Users inherit any permissions from each of the groups they belong to. subscribe topic=purchase. Permissions are stored in the access control list for the server. or who can create durable subscriptions to topics.subscribe topic=all. Using permissions you can control which users have permission to send.order Users chris pat ryan Groups Accounting: chris pat ryan External Directory Users gale jean perry Groups Employees: gale jean perry TIBCO Enterprise Message Service User’s Guide . and permissions TIBCO Enterprise for EMS Server Local Configuration Access Control List topic=check. or browse messages for queues. Rather than granting and revoking permissions on destinations to individual users.request purchase. in addition to any permissions that are granted to them directly.news group=employees perm=subscribe Destinations Topics: check. Groups allow you to create classes of users and control permissions on a more global level.request user=chris perm=publish. receive.Users and Groups 233 | Users and Groups User permissions apply to the activities a user can perform on each destination (topic and queue). you can control destination access at the group level. Figure 16 Users. You can also control who can publish or subscribe to topics. Figure 16 illustrates the relationships between users. groups.order group=accounting perm=publish. In special cases. For more information on the administration APIs. For more information about specifying users using the tibemsadmin tool. admin. Users Users are specific. that performs administrative tasks. see the online documentation. the connect request should be accompanied by a username and the password associated with the username. Clients logging in anonymously are only able to perform the actions that the anonymous user has permission to perform. SSL and the access control features described in this chapter can be used together or separately to ensure secure access to your system. however. specify any access control at the destination level. on page 101. In this case. a connect request does not have to supply a username or password. When a client logs in. SSL does not. as well as the access control list. using the administration tool. SSL allows for servers to require user authentication by way of the user’s digital certificate. There is one predefined user. or by using the administration APIs. TIBCO Enterprise Message Service User’s Guide . Locally-configured users and groups.conf configuration file. Anonymous logins are not permitted unless the anonymous user exists. Using the EMS Administration Tool. see users.conf on page 201. Access control and Secure Sockets Layer (SSL) have some similar characteristics. using the tibemsadmin tool. you may wish to allow anonymous access to the server. The following sections describe users and groups in EMS. Using the SSL Protocol. See Chapter 14. or the administration APIs). named IDs that allow you to identify yourself to the server. see Chapter 6. To configure the server to allow anonymous logins. You can create and remove users and change passwords by specifying the users in the users. are configured using any of the administration interfaces (editing configuration files.234 | Chapter 8 Authentication and Permissions Externally-configured users and groups are defined and managed using the external directory. such as creating other users. on page 365 for more information about SSL. For more information about specifying users in the configuration file. you must create a user named anonymous and specify no password. conf guides the EMS server when authenticating users. see groups. External User Authentication EMS can be configured to authenticate users stored in an external directory server. or in an external directory (such as an LDAP server).conf on page 202. You can create. Groups make access control administration significantly simpler because you can grant and revoke permissions to large numbers of users with a single operation on the group. A user’s permissions are the union of the permissions of the groups the user belongs to. in addition to any permissions granted to the user directly. For more information on the administration APIs. Configuring an External Directory You can define user authentication and group information either in EMS server configuration files. such as an LDAP server. on page 101. The EMS server accepts successful authentication using any of the specified sources. using the tibemsadmin tool. Each user can belong to as many groups as necessary. or by using the administration APIs. or add users to groups by specifying the groups in groups. TIBCO Enterprise Message Service User’s Guide . Using the EMS Administration Tool. the server seeks corresponding authentication information from each of the specified locations in the order that this parameter specifies. For more information about specifying groups in the configuration file. see Chapter 6. When a user attempts to authenticate to the EMS server. remove. For more information about specifying groups using the tibemsadmin tool. Each time a user attempts to authenticate.Users and Groups 235 | Groups Groups allow you to create classes of users. This parameter can have one or more of the following values (separated by comma characters): • • local—obtain user authentication information from the local EMS server user configuration. ldap—obtain user authentication information from an LDAP directory server (see the LDAP-specific configuration parameters). The parameter user_auth in tibemsd. this parameter specifies the source of authentication information.conf. see the online documentation. this deletes the user or group from the server’s memory and deletes any permissions assigned in the access control list. not all users and groups defined in the external directory may appear when the show user/s or show group/s commands are executed. If a user or group exists in the server’s configuration and is also defined externally. The permissions assigned to the user or group are also deleted when the user or group is deleted. the local definition of the user takes precedence. Users and groups from external directories will only appear in the output of these commands in the following situations: • • • • an externally-defined user successfully authenticates a user belonging to an externally-defined group successfully authenticates an externally-defined user has been added to a locally-defined group permissions on a topic or queue have been granted to an externally-defined user or group Therefore. Only the users and groups that meet the above criteria at the time the command is issued will appear. If you delete a user or group that is defined externally. TIBCO Enterprise Message Service User’s Guide . Administration Commands and External Users and Groups You can perform administrative commands on users and groups defined either locally (in the EMS server’s local configuration files) or in an external LDAP. Combining authentication sources requires that the configuration parameter user_auth includes both ldap and local. or add LDAP-defined users to locally-defined groups). Locally-defined users and groups will not have an asterisk by their names in the show user/s or show group/s commands. You can also issue the delete user or delete group command to delete users and groups from the local server’s configuration. any users and groups that exist in external directories have an asterisk next to their names. Static and dynamic groups are supported and you can configure the EMS server to retrieve either or both. you can combine users and groups that are defined in different locations (for example. you can grant and revoke permissions for users and groups defined in an LDAP. You can create users and groups with the same names as externally-defined users and groups.236 | Chapter 8 Authentication and Permissions Group Information Group information stored in an external directory can also be retrieved by the EMS server. Furthermore. When you attempt to view users and groups using the show user/s or show group/s commands. Using LDAP Directory Servers EMS has been tested with the following external directory servers: • • Netscape/SunOne iPlanet Directory Server version 5.conf on page 157 provides the complete list of configuration parameters for configuring an external directory server. The externally-defined user can once again log in. any permissions for the user or group have been deleted and therefore must be re-granted. Table 39 Default configuration for popular LDAP servers (Sheet 1 of 2) External Directory Server iPlanet Parameter Configuration ldap_principal = cn=Directory Manager ldap_user_class = Person ldap_user_attribute = uid ldap_user_base_dn = ou=people. o=<your_organization> ldap_user_filter = (&(uid=%s)(objectclass=person)) ldap_group_base_dn = "ou=groups. Table 39 describes parameter settings for default configurations of popular LDAP servers. you should be able to use any external directory server that is compliant with LDAP V2. and the user is created in the server’s memory and any groups to which the user belongs are also created. The description for tibemsd. o=<your_organization> ldap_group_filter = (|(&(cn=%s)(objectclass=groupofUniqueNames))(& (cn=%s)(objectclass=groupOfURLs))) ldap_static_group_class = groupofuniquenames ldap_static_group_attribute = cn ldap_static_member_attribute = uniquemember ldap_dynamic_group_class = groupofURLs ldap_static_group_member_filter = (&(uniquemember=%s)(objectclass=groupofuniquen ames)) ldap_dynamic_group_class = groupofURLs ldap_dynamic_group_attribute = cn ldap_dynamic_member_url_attribute = memberURL TIBCO Enterprise Message Service User’s Guide .1 Microsoft Active Directory shipped as part of the Windows 2000 Server However.Users and Groups 237 | but it has no effect on the external directory. However. CN=Users. o=<your_organization> ldap_user_filter = (&(cn=%s)(objectclass=person)) ldap_group_base_dn = ou=groups. DC=<your_domain> ldap_user_class = user ldap_user_attribute = cn ldap_user_filter = (&(cn=%s)(objectclass=user)) ldap_group_filter = (&(cn=%s)(objectclass=group)) ldap_static_group_class = group ldap_static_group_attribute = cn ldap_static_member_attribute = member ldap_static_group_member_filter = (&(member=%s)(objectclass=group)) Open LDAP ldap_user_class = person ldap_user_attribute = cn ldap_user_base_dn = ou=people. o=<your_organization> ldap_group_filter = (&(cn=%s)(objectclass=groupofnames)) ldap_static_group_class = grouponames ldap_static_group_attribute = cn ldap_static_member_attribute = uniquemember ldap_static_group_member_filter = (&(uniquemember=%s)(objectclass=groupofnames)) TIBCO Enterprise Message Service User’s Guide . dc=<your_domain_component> ldap_group_filter = (&(cn=%s)(objectclass=groupofnames)) ldap_static_group_class = groupofnames ldap_static_group_attribute = cn ldap_static_member_attribute = member ldap_static_group_member_filter = (&(member=%s)(objectclass=groupofnames)) Novell ldap_user_class = person ldap_user_attribute = cn ldap_user_base_dn = ou=people. dc=<your_domain_component>.238 | Chapter 8 Authentication and Permissions Table 39 Default configuration for popular LDAP servers (Sheet 2 of 2) External Directory Server Active Directory Parameter Configuration ldap_principal = CN=Administrator. dc=<your_domain_component> ldap_user_filter = (&(cn=%s)(objectclass=user)) ldap_group_base_dn = ou=groups. dc=<your_domain_component>. When setting permissions for users and groups defined externally.conf file. user and group names are case-sensitive. See Inheritance of User Permissions on page 241 for more information on wildcard destination names and permissions.User Permissions 239 | User Permissions User permissions are stored in the access control list and determine the actions a user can perform on a destination. or by using the administration APIs. the name of the destination. you specify the user or group to whom you wish to grant the permission. and the secure property of the relevant destinations. however. and only for secure destinations. and the permission(s) to grant. using the tibemsadmin tool. When setting user permissions. TIBCO Enterprise Message Service User’s Guide . A user’s permissions are the union of the permissions granted explicitly to that user along with any permissions the user receives by belonging to a group. Make sure you use the correct case for the name when setting the permissions. When granting user permissions. Granting permissions is an action that is independent from both the authorization server parameter. User permissions can only be granted by an administrator with the appropriate permissions described in Administrator Permissions on page 223. The currently granted permissions are stored in the access control file. You assign permissions either by specifying them in the acl. the server enforces them only if the authorization is enabled. you can specify either explicit destination names or wildcard destination names. delete. but bob cannot create durable subscribers to foo.conf file: USER=bob TOPIC=foo PERM=subscribe. or modify durable subscribers on the topic permission to use an existing durable subscriber on the topic. If bob is a member of group engineering and the group has the following entry in the acl file: GROUP=engineering TOPIC=bar PERM=subscribe.conf file.publish This set of permissions means that bob can subscribe to topic foo and publish messages to it. delete. TIBCO Enterprise Message Service User’s Guide . If both the user bob and the group engineering have entries in the acl. the permissions to access topics are listed in Table 41. but not to create.240 | Chapter 8 Authentication and Permissions The permissions that can be granted to users to access queues are listed in Table 40. then bob has permissions that are a union of all permissions set for bob directly and the permissions of the group engineering. Table 40 Queue Permission Name receive send browse Description permission to create queue receivers permission to create queue senders permission to create queue browsers Table 41 Topic Permission Name subscribe publish durable Description permission to create non-durable subscribers on the topic permission to publish on the topic permission to create.publish then bob can publish and subscribe to topics foo and bar. or modify the durable subscriber use_durable Example of Setting User Permissions The user bob has the following permission recorded in the acl. conf file.bar queue.bar queue. but you cannot remove permissions. existing consumers of the destination continue to receive messages. Without permission. Use the administration APIs. you cannot revoke a permission from a user that the user receives from a group. The revoke command cannot remove items that are inherited from other entries. You can add permissions to a user for topics or queues that match a wildcard specification. The user Bob receives the browse permission on the foo. See Wildcards on page 63 for more information about wildcards in destination names. you cannot take away the inherited browse permission from Bob on the foo. Also.conf file. all created topics and queues that match the specification will have the same granted permissions as the permissions on the parent topic. For example. If there are multiple parent topics. The revoke command in tibemsadmin can only remove items from specific entries in the acl. Use the revoke commands in tibemsadmin. you can grant user Bob the browse permission on queue foo. However. That is.User Permissions 241 | Inheritance of User Permissions When you grant permissions to users for topics or queues with wildcard specifications. You can revoke permissions in several ways: • • • Remove or edit entries in the acl. the user receives the union of all parent topic permissions for any child topic. you cannot revoke a permission that is inherited from a parent topic.bar queue. You can only revoke a permission that is granted directly. TIBCO Enterprise Message Service User’s Guide .*. the user cannot create new consumers for a destination—however. and you can also grant Bob the send permission on the foo. see page 120. Revoking User Permissions Administrators can revoke permissions for users to create consumers on a destination. the user must have been granted the durable permission to create durable subscriptions for topic foo. before creating or sending messages to the destination.* or any child topics. then grant permission to specific topics at a later time. For example. For example. and so on.*. This allows administrators to grant users the desired permissions after the user’s application creates the subscriptions. When creating a durable subscriber. TIBCO Enterprise Message Service User’s Guide . and the secure property is set for the destination). permissions are checked when a user performs one of the following actions: • • • • creates a subscription to a topic attempts to become a consumer for a queue publishes or sends a message to a topic or queue attempts to create queue browser A user cannot create or send a message to a destination for which he or she has not explicitly been granted the appropriate permission. to create a durable subscriber to topic foo. To subscribe an existing durable subscriber to a topic. a user can create a subscription to topic foo. So. you must have either durable or use_durable permission set on that topic. You may wish to allow users to subscribe to unspecific topics. the authorization configuration property is set. Therefore.* without having explicit permission to create subscriptions to foo.242 | Chapter 8 Authentication and Permissions When Permissions Are Checked If permissions are enforced (that is. for wildcard topic names (queue consumers cannot specify wildcards).*. permissions are not checked when users create non-durable subscriptions. For specific (non-wildcard) destination names. create a subscription to a topic. Since permissions can be granted or revoked dynamically. send a message to a queue. a user must be granted permissions on the destination. Users are not able to receive messages based on their wildcard subscriptions until permissions for the wildcard topic or one or more child topics are granted. However. the server checks them each time an operation is performed on a destination (and each time a consumer or producer is created). users must have the durable permission explicitly set for the topic they are subscribing to. the server checks them when a user attempts to perform an operation on a destination. bob. This operation fails because bob has not been granted access to that topic yet. Because the same application is used by many users.news. This topic is the parent topic of each user.bob and can subscribe to topic corp.bob and corp. but the application does not receive the message because bob has not been granted access to the topic yet. 8.* to user bob. 9. These grants occur dynamically. as part of the daily maintenance for the application.bob).news still exists for user bob’s application. 3. 2.* topics. messages are sent to the topic user. A message is sent to topic corp. 5. User bob creates a subscription to user. The subscription to corp. The application receives the new message on topic user. User bob is working with a EMS application that subscribes to topics and displays any messages sent to those topics. 10. but bob cannot create any new subscriptions to children of the corp. The administrator sends a message on the topic user. 1. User bob creates a subscription to topic corp. and user bob is now able to receive messages sent to topic user.news. the application creates a subscription to the parent topic.bob and displays the message. grants access to topics for new users. so the administrator revokes the subscribe permission on topic corp.news. The administrator grants the subscribe permission to topic user. A message is sent to the topic user. The administrator. 6. The administrator notices that bob is a contractor and not an employee. User bob attempts to create a subscription for topic corp. 4.* to user bob. User bob’s application receives this message and displays it.*. and describes what happens as various operations are performed.news and succeeds. TIBCO Enterprise Message Service User’s Guide .When Permissions Are Checked 243 | Example of Permission Checking This example walks through a scenario for granting and revoking permissions to a user.bob to notify bob that access has been granted to all corp. 7.* topic. Messages are periodically sent to each user (for example. 244 | Chapter 8 Authentication and Permissions TIBCO Enterprise Message Service User’s Guide . page 250 Connection Factories. page 265 Dynamically Creating Topics and Queues. page 262 Creating a Session. Topics • • • • • • • • • • • JMS Specification.| 245 Chapter 9 Developing an EMS Client Application This chapter outlines how to develop EMS client applications in Java. page 269 Creating a Message Consumer. C and C#. page 267 Creating a Message Producer. page 246 Sample Clients. page 277 TIBCO Enterprise Message Service User’s Guide . page 249 Programmer Checklists. page 258 Connecting to the EMS Server. page 272 Working with Messages. page 264 Setting an Exception Listener. JMS 1.246 | Chapter 9 Developing an EMS Client Application JMS Specification EMS implements the JMS 1. Figure 17 illustrates the interfaces involved in the JMS API. they may be deprecated in future releases of the JMS specification.1 interfaces.2b specification for older clients. Figure 17 JMS 1.2b interfaces continue to be supported.1 interfaces.1 Programming Model Connection Factory Creates Connection Creates Session Creates Creates Message Message Producer Message Consumer Registers With (Asynch Messages) Message Listener Topic or Queue Sends To Receives From (Synch Messages) TIBCO Enterprise Message Service User’s Guide . The JMS specification refers to these interfaces as common facilities because these interfaces create objects that can be used for either topics or queues. Newly developed applications should use the JMS 1. and you should discontinue the use of the older interfaces as soon as possible.1 specification. The code examples in this chapter illustrate the use of the JMS 1.1 Specification In the JMS 1. as well as the earlier JMS 1. applications using the point to point (queues) or publish and subscribe (topics) models use the same interfaces to create objects.1 specification.0.0. While the JMS 1. 0.0.2b Specification The JMS 1.0.JMS Specification 247 | JMS 1. but the interfaces are specific to topics or queues. Queue Browser.2b interfaces have the same structure as the JMS 1. or Topic Subscriber Registers With Message Listener Queue or Topic Message Queue Sender or Topic Publisher Sends To Receives From TIBCO Enterprise Message Service User’s Guide .2b Programming Model Queue Connection Factory or Topic Connection Factory Creates Queue Connection or Topic Connection Creates Queue Session or Topic Session Creates Creates Queue Receiver.2b specification defined specific interfaces for topics and for queues. The JMS 1.0.1 common facilities. Figure 18 illustrates the previous interface model used by the JMS API. Figure 18 JMS 1. Connections are used to create sessions.2b) QueueConnectionFactory TopicConnectionFactory Connection QueueConnection TopicConnection Session QueueSession TopicSession Description Object used to create connections to EMS server. A message consumer is an object created by a session that receives messages sent to a destination.1 and 1. A connection encapsulates a physical connection with a provider (server). Sessions can also be transacted. a group of messages are sent and received in a single transaction. A session is a single-threaded object that creates instances of message producers.2b Interfaces Table 42 summarizes the interfaces used in the JMS API to support both the common facilities and specific interfaces. Message listeners must be registered with a specific MessageConsumer. message consumers. In a transacted session.1) ConnectionFactory Specific Interfaces (JMS 1.0. MessageProducer QueueSender TopicPublisher MessageConsumer QueueBrowser QueueReceiver TopicSubscriber MessageListener MessageListener A message listener is an object that acts as an asynchronous event handler for messages.0.248 | Chapter 9 Developing an EMS Client Application Summary of JMS 1. A message producer is an object created by a session that is used for sending messages to a destination. Table 42 JMS API object summary (Sheet 1 of 2) Common Facilities Interfaces (JMS 1. messages and transacted message groups. TIBCO Enterprise Message Service User’s Guide . Sample Clients 249 | Table 42 JMS API object summary (Sheet 2 of 2) Common Facilities Interfaces (JMS 1.1) MessageSelector Specific Interfaces (JMS 1.0.2b) MessageSelector Description Message selectors are optional filters that can be used by the application. They transfer the filtering work to the message provider, rather than the message consumer. A message selector is a String that contains an expression. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax. Message Queue Topic Message Queue Topic Several types of message bodies are available for queues and topics. The destination that messages can be sent to or received from. Normally these are created and managed by the server, but clients can create destinations dynamically by using methods on the Session object. Sample Clients TIBCO Enterprise Message Service includes several sample client applications that illustrate various features of EMS. You may wish to view these sample clients when reading about the corresponding features in this manual. The samples are included in the ems/samples/java, ems/samples/c, and ems/samples/cs subdirectories of the EMS installation directory. Each subdirectory includes a README file that describes how to compile and run the sample clients. Chapter 4, Getting Started, on page 75 walks through the procedures for setting up your EMS environment and running some of the sample clients. TIBCO Enterprise Message Service User’s Guide 250 | Chapter 9 Developing an EMS Client Application Programmer Checklists This section provides a checklist that outlines the steps for creating an EMS application in each language: • • • Java Programmer’s Checklist on page 250 C Programmer’s Checklist on page 252 C# Programmer’s Checklist on page 257 Java Programmer’s Checklist Install • • Install the EMS software release, which automatically includes the EMS jar files in the clients/java subdirectory. Add the full pathnames for the following jar files to your CLASSPATH: jms.jar jndi.jar tibjms.jar • If SSL is used for communication, add the following files to the CLASSPATH: tibcrypt.jar jnet.jar jcert.jar jsse.jar All jar files listed in this section are located in the java subdirectory of the TIBCO Enterprise Message Service installation directory. To use Entrust with an EMS client, you must separately purchase and install the Entrust Version 7.1 libraries. If you use the Entrust libraries, you must include them in the CLASSPATH before the JSSE JAR files. To use Entrust Version 7.1 with JDK, you must download the unlimited strength policy JAR files from Sun's website and install them in your local installation of JDK. For installation and configuration details, see Entrust Version 7.1 documentation. See , Security Considerations, on page 94 for a complete discussion of what is needed for a secure deployment. TIBCO Enterprise Message Service User’s Guide Programmer Checklists 251 | Code Import the following packages into your EMS application: import javax.jms.*; import javax.naming.*; Compile Compile your EMS application with the javac compiler to generate a .class file. For example: javac MyApp.java generates a MyApp.class file. Run Use the java command to execute your EMS .class file. For example: java MyApp TIBCO Enterprise Message Service User’s Guide 252 | Chapter 9 Developing an EMS Client Application C Programmer’s Checklist Developers of EMS C programs can use this checklist during the five phases of the development cycle. Install • Install the EMS software release, which automatically includes the EMS client libraries, binaries, and header files in the clients/c subdirectory. Code Application programs must: • Add clients/c/include to the include path. (OpenVMS environments do not require an include path; skip this item.) Include the tibems.h header file: #include <tibems/tibems.h> • • Call tibems_Open() to initialize the EMS C API and tibems_Close() to deallocate the memory used by EMS when complete. Compile and Link • • Compile programs with an ANSI-compliant C compiler. Link with the appropriate EMS C library files; see Link These Library Files on page 253. See the samples/c/readme file for details. Run • UNIX If you use dynamic EMS libraries on a UNIX platform, the environment variable $LD_LIBARY_PATH must include the clients/c/lib directory (which contains the shared library file. (On some UNIX platforms, this variable is called $LIBPATH). • • • Windows The PATH must include the clients\c\bin directory. OpenVMS The installation procedure automatically installs the shareable images required for using EMS dynamic libraries. All Platforms The application must be able to connect to a EMS server process (tibemsd). TIBCO Enterprise Message Service User’s Guide Programmer Checklists 253 | Link These Library Files EMS C programs must link the appropriate library files. The following sections describe which files to link for your operating system platform: • • • • 32-Bit UNIX on page 253 64-Bit UNIX on page 254 Microsoft Windows on page 255 OpenVMS on page 256 32-Bit UNIX In 32-bit UNIX environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration. Table 43 Linker Flags for 32-Bit UNIX Linker Flag -ltibems -lssl -lcrypto -lz Description All programs must link using this library flag. Programs that use SSL must link using these library flags. Programs that use compression must link using this library flag. Programs that use EMS LDAP lookup must link using these library flags. -ltibemslookup -lldap -lxml2 -llber TIBCO Enterprise Message Service User’s Guide 254 | Chapter 9 Developing an EMS Client Application 64-Bit UNIX In 64-bit UNIX environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration. In this release, 64-bit libraries are available on HP-UX, Solaris, AIX and Linux (2.4 glibc 2.3) platforms. To use 64-bit libraries, you must include EMS_install_dir/clients/c/lib/64 in your library path, and it must precede any other EMS directory in the library path. Table 44 Linker Flags for 64-Bit UNIX Linker Flag -ltibems64 -lssl -lcrypto -lz Description All programs must link using this library flag. Programs that use SSL must link using these library flags. Programs that use compression must link using this library flag. Programs that use EMS LDAP lookup must link using these library flags. -ltibemslookup64 -lldap -lxml2 -llber TIBCO Enterprise Message Service User’s Guide Programmer Checklists 255 | Microsoft Windows For a list of Windows platforms that Release 4.4 supports, see the file readme.txt in the installation directory. Both DLLs and static libraries are available. We recommend DLLs to ease forward migration. Table 45 Dynamic Library Files for Microsoft Windows Library File Description With dynamic libraries (DLLs), use the /MT compiler option. tibems.lib ws2_32.lib tibemslookup.lib All programs must link these libraries. Programs that use EMS LDAP lookup must link this library. In addition, programs that use EMS lookup must link one of these pairs of libraries. libxml2.lib liboldap32.lib olber32.lib libldap32_d.lib liblber32_d.lib Table 46 Static Library Files for Microsoft Windows Library File Description With static libraries (DLLs), use the /MD compiler option. libtibems.lib ws2_32.lib ssleay32mt.lib libeay32mt.lib zlib.lib libtibemslookup.lib All programs must link these libraries. libxml2.lib liboldap32.lib olber32.lib libldap32_d.lib liblber32_d.lib Programs that use EMS LDAP lookup must link this library. In addition, programs that use EMS lookup must link one of these pairs of libraries. TIBCO Enterprise Message Service User’s Guide 256 | Chapter 9 Developing an EMS Client Application OpenVMS In OpenVMS environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration. When upgrading from EMS 4.3 to 4.4 or later versions, EMS client executables that were linked with the EMS 4.3 dynamic libraries (shareable images) must be relinked to the new libraries after EMS 4.4 has been installed with its associated third party libraries. The third party libraries are part of the full installation of EMS. Table 47 Shareable Image Library Files for OpenVMS Library File LIBTIBEMSSHR.EXE LIBTIBEMSLOOKUPSHR.EXE LIBLDAPSHR.EXE LIBLBERSHR.EXE LIBXMLSHR.EXE LIBCRYPTOSHR.EXE LIBSSLSHR.EXE LIBZSHR.EXE Description All programs must link this library. Programs that use EMS LDAP lookup must link these libraries. Programs that use SSL must link these libraries. Programs that use data compression must link this library. Table 48 Static Library Files for OpenVMS Library File LIBTIBEMS.OLB LIBTIBEMSLOOKUP.OLB LIBLDAP.OLB LIBLBER.OLB LIBXML.OLB LIBCRYPTO.OLB LIBSSL.OLB LIBZ.OLB Description All programs must link this library. Programs that use EMS LDAP lookup must link these libraries. Programs that use SSL must link these libraries. Programs that use data compression must link this library. TIBCO Enterprise Message Service User’s Guide Programmer Checklists 257 | C# Programmer’s Checklist Developers of EMS C# programs can use this checklist during the four phases of the development cycle. Install • Install the EMS software release, which automatically includes the EMS assembly DLLs in the clients\cs subdirectory. Code • Import the correct EMS assembly (see Table 49). Table 49 EMS Assembly DLL Version Full .NET API .NET Compact Framework API DLL TIBCO.EMS.dll TIBCO.EMS-CF.dll Compile • Compile with any .NET compiler. Run • The EMS assembly must be in the global assembly cache (this location is preferred), or in the system path, or in the same directory as your program executable. The application must be able to connect to a EMS daemon process (tibemsd). • TIBCO Enterprise Message Service User’s Guide 258 | Chapter 9 Developing an EMS Client Application Connection Factories A client must connect to a running instance of the EMS server to perform any JMS operations. A connection factory is an object that encapsulates the data used to define a client connection to an EMS server. The minimum factory parameters are the type of connection (e.g., ’generic’ for JMS 1.1 connections and ’topic’ or ’queue’ for JMS 1.0.2b connections) and the URL (host name, transport protocol and port id) for the client connection to the EMS server. A connection factory is either dynamically created by the application or obtained from a data store by means of a naming service, such as a Java Naming and Directory Interface (JNDI) server or a Lightweight Directory Access Protocol (LDAP) server. Looking up Connection Factories EMS provides a JNDI implementation that can be used to store connection factories. Java, C, and C# clients can use the EMS JNDI implementation to lookup connection factories. You can also store connection factories in any JNDI-compliant naming service or in an LDAP server. Java clients can lookup connection factories in any JNDI-compliant naming service, but Java clients cannot use LDAP servers. C and C# clients can only use the JNDI service supplied by EMS, but these clients can use LDAP servers. Looking up Administered Objects Stored in EMS on page 291 describes how to lookup a connection factory from an EMS server. Chapter 1, Using JNDI With Third-Party Naming/Directory Services in the TIBCO Enterprise Message Service Application Integration Guide describes how to look up connection factories from a third-party JNDI or LDAP server. How to create connection factories in a EMS server is described in Creating and Modifying Administered Objects in EMS on page 288. Dynamically Creating Connection Factories Normally client applications use JNDI to look up a Connection Factory object. However, some situations require clients to connect to the server directly. To connect to the EMS server directly, the application must dynamically create a connection factory. TIBCO Enterprise Message Service User’s Guide the serverUrl parameter in these expressions is a string defining the protocol and the address of the running instance of the EMS Server. For example: serverUrl = tcp://server0:7222 For a fault-tolerant connection.c sample client for a working example. The serverUrl parameter has the form: serverUrl = protocol://host:port The supported protocols are tcp and ssl. C# To dynamically create a ConnectionFactory object in a C# client: ConnectionFactory factory = new TIBCO.java sample client for a working example. status = tibemsConnectionFactory_SetServerURL( factory. TIBCO Enterprise Message Service User’s Guide . In each example. serverUrl). tcp://server1:7344 See Configuring Clients for Fault-Tolerant Connections on page 397 for more information.0. see Configuring SSL in EMS Clients on page 372 and Creating Connection Factories for Secure Connections on page 289. you can specify two or more URLs. For details on using SSL for creating secure connections to the server.EMS. For example: serverUrl = tcp://server0:7222.2b "regular" and XA connections.TibjmsConnectionFactory(serverUrl). See the tibemsMsgProducer. Each API also supports connection factories for JMS 1. See the csMsgProducer.tibjms. C To dynamically create a tibemsConnectionFactory type in a C client: factory = tibemsConnectionFactory_Create().tibco.cs sample client for a working example.Connection Factories 259 | The following examples show how to create a connection factory in each supported language for JMS 1. Java To dynamically create a TibjmsConnectionFactory object in a Java client: ConnectionFactory factory = new com.ConnectionFactory(serverUrl).1 connections. as well as queue and topic factories for JMS 1.1 XA connections. See the tibjmsMsgProducer. 1000). 1000).setConnAttemptDelay(1000). null.setConnAttemptTimeout(1000). Java Use the TibjmsConnectionFactory object’s setConnAttemptCount(). Timeout and Delay Parameters By default. EMS also allows you to establish separate count. params ). a client will attempt to connect to the server 2 times with a 500 ms delay between each attempt.setConnAttemptCount(10). setConnAttemptDelay(). status = tibemsConnectionFactory_SetConnectAttemptDelay( factory. QUEUE_TYPE. and setConnAttemptTimeout() methods to establish new connection failure parameters: factory.260 | Chapter 9 Developing an EMS Client Application ConnectionFactoryInfo Constructor in Java Java clients can also use the Java Administrator API to specify the primary and backup server URLs in the url argument to a ConnectionFactoryInfo constructor. There are also a number of factors that may cause a client to hang while attempting to create a connection to the EMS server. The following examples establish a connection count of 10. A client can modify this behavior by setting new connection attempt count and delay values. TIBCO Enterprise Message Service User’s Guide . C Use the tibemsConnectionFactory_SetConnectAttemptCount and tibemsConnectionFactory_SetConnectAttemptDelay functions to establish new connection failure parameters: status = tibemsConnectionFactory_SetConnectAttemptCount( factory. factory. delay and timeout settings for reconnections after a fault-tolerant switchover. 10). status = tibemsConnectionFactory_SetConnectAttemptTimeout( factory. factory. so you can set a connection timeout value to abort a connection attempt after a specified period of time. as described in Setting Reconnection Failure Parameters on page 398. For example: ConnectionFactoryInfo cfi = new ConnectionFactoryInfo("tcp://server0:7222". a delay of 1000 ms and a timeout of 1000 ms. Setting Connection Attempts. setConnAttemptCount(10). and ConnectionFactory.Connection Factories 261 | C# Use the ConnectionFactory. ConnectionFactory.SetConnAttemptTimeout methods to establish new connection failure parameters: factory.SetConnAttemptDelay. factory. TIBCO Enterprise Message Service User’s Guide .setConnAttemptDelay(1000).SetConnAttemptCount. factory.setConnAttemptTimeout(1000). userName. but the recommended procedure is that you create tibemsConnection objects from factories.password). See the tibjmsMsgProducer. C Use the tibemsConnectionFactory_CreateConnection function to create a connection of type tibemsConnection: tibemsConnection connection = NULL. TIBCO Enterprise Message Service User’s Guide . if necessary.NULL. The tibemsConnection_Create function exists for backward compatibility.c sample client for a working example. If there is no connection factory. password).password).262 | Chapter 9 Developing an EMS Client Application Connecting to the EMS Server A connection with the EMS server is defined by the Connection object obtained from a Connection Factory. See the tibemsMsgProducer. status = tibemsConnectionFactory_CreateConnection(factory. serverUrl. The following examples show how to create a Connection object. Your application can create multiple connections. as described in Connection Factories on page 258.java sample client for a working example.createConnection(userName. userName. a C client can use the tibemsConnection_Create function to dynamically create a tibemsConnection type: status = tibemsConnection_Create(&connection. Java Use the TibjmsConnectionFactory object’s createConnection() method to create a Connection object: Connection connection = factory. &connection. so most clients will create a connection once and keep it open until the client exits. A connection is a fairly heavyweight object. See the csMsgProducer. but they do consume resources that could be used for other applications. See the "start. password).Connecting to the EMS Server 263 | C# Use the ConnectionFactory. Stopping and Closing a Connection Before consuming messages. the C tibemsConnection type. When a client application exits. all open connections must be "closed. See Creating a Message Consumer on page 272 for more details about Message Consumers.CreateConnection(userName. If you wish to temporarily suspend message delivery. Closing a connection also closes any sessions created by the connection." Unused open connections are eventually closed. the Message Consumer client must "start" the connection." "stop" and "close" methods for the Java Connection object.CreateConnection method to create a Connection object: Connection connection = factory. Starting. TIBCO Enterprise Message Service User’s Guide . you can "stop" the connection.cs sample client for a working example. and the C# Connection object. com.createSession( false.264 | Chapter 9 Developing an EMS Client Application Creating a Session A Session is a single-threaded context for producing or consuming messages. The EMS extended acknowledgement modes. A non-transactional Session can define the acknowledge mode of message objects received by the session.CreateSession(false.cs sample client for a working example. Session. status = tibemsConnection_CreateSession(connection. TIBEMS_AUTO_ACKNOWLEDGE).tibco. See the tibjmsMsgProducer.CreateSession method to create a Session object: Session session = connection. You create Message Producers or Message Consumers using Session objects.java sample client for a working example. TIBCO Enterprise Message Service User’s Guide . Java Use the Connection object’s createSession() method to create a Session object.Session.c sample client for a working example.NO_ACKNOWLEDGE). C# Use the Connection.AUTO_ACKNOWLEDGE). require that you include the com. See the csMsgProducer.AUTO_ACKNOWLEDGE). to create a non-transactional Session that uses the AUTO_ACKNOWLEDGE delivery mode: Session session = connection.createSession( false. to create a non-transactional Session that uses the NO_ACKNOWLEDGE delivery mode: Session session = Connection. For example.Tibjms constant when you specify the EMS delivery mode.tibjms. See the tibemsMsgProducer. For example. See Message Acknowledgement on page 36 for details.tibjms.jms.tibco. such as NO_ACKNOWLEDGE.Tibjms. TIBEMS_FALSE. &session. javax. A Session can be transactional to enable a group of messages to be sent and received in a single transaction. C Use the tibemsConnection_CreateSession function to create a session of type tibemsSession: tibemsSession session = NULL. TIBCO Enterprise Message Service User’s Guide . when the event is a fault-tolerant switchover.Tibjms. When the event is a disconnect. } See the tibjmsMsgConsumer. .java sample client for a working example (without the setExceptionOnFTSwitch call)...tibco.. the exception handler is not allowed to call any EMS method.tibjms..setExceptionOnFTSwitch to call the exception handler after a fault-tolerant switchover: public class tibjmsMsgConsumer implements ExceptionListener { .setExceptionListener(this). The following examples demonstrate how to establish an exception listener for a connection. the exception handler can call various EMS methods without any problem.. and call Tibjms.. Java Implement an ExceptionListener. To do so risks a deadlock....onException method. You can call the setExceptionOnFTSwitch method to receive an exception that contains the new server URL after a fault-tolerant switchover has occurred. connection..Setting an Exception Listener 265 | Setting an Exception Listener All the APIs support the ability to set an exception listener on the connection that gets invoked when a connection breaks or experiences a fault-tolerant switchover.setExceptionOnFTSwitch(true). public void onException(JMSException e) { /* Handle exception */ } . use the Connection object’s setExceptionListener method to register the exception listener.. However. com.. status = tibemsConnection_SetExceptionListener( connection. onException. TIBCO Enterprise Message Service User’s Guide ..EMS..SetExceptionOnFTSwitch to call the exception handler after a fault-tolerant switchover: public class csMsgConsumer : IExceptionListener { . use the tibemsConnection_SetExceptionListener function to call onException when an error is encountered.SetExceptionOnFTSwitch(true). connection.Tibems.. set the Connection object’s ExceptionListener property to register the exception listener... TIBCO.. void* closure) { /* Handle exception */ } . C# Implement an IExceptionListener.OnException method.. public void OnException(EMSException e) { /* Handle exception */ } ....ExceptionListener = this.. } See the csMsgConsumer..cs sample client for a working example (without the setExceptionOnFTSwitch call).. and call Tibems. and call tibems_SetExceptionOnFTSwitch to call the exception handler after a fault-tolerant switchover: void onException( tibemsConnection conn. tibems_setExceptionOnFTSwitch(TIBEMS_TRUE). See the tibemsMsgConsumer. .c sample client for a working example (without the setExceptionOnFTSwitch call)..266 | Chapter 9 Developing an EMS Client Application C Define an onException function to handle exceptions.. tibems_status reason.. NULL). TIBCO Enterprise Message Service User’s Guide . In JMS 1. Java. The destination is managed by the server as long as clients that use the destination are running. you can use the TopicSession. and C# clients can use the EMS JNDI implementation to lookup topics and queues.createQueue() methods to create topics and queues. If the destination does not exist.createTopic() and QueueSession. You can also store topics and queues in any JNDI-compliant naming service or in an LDAP server.createQueue(queueName). See the tibjmsMsgProducer. the server dynamically creates the new destination.0. Use the Session object’s createQueue() method to create a queue as a Destination object: Destination queue = session. but Java clients cannot use LDAP servers.conf or queues.createTopic(topicName).2b. C and C# clients can only use the JNDI service supplied by EMS.conf files allow the destination. Using JNDI With Third-Party Naming/Directory Services in the TIBCO Enterprise Message Service Application Integration Guide describes how to look up topics and queues from a third-party JNDI or LDAP server. Java clients can lookup topics and queues in any JNDI-compliant naming service. If a client requests the creation of a destination that already exists.Dynamically Creating Topics and Queues 267 | Dynamically Creating Topics and Queues EMS provides a JNDI implementation that can be used to store topics and queues. and the specification of the topics. C. The new destination inherits properties and permissions from its ancestors as described in Wildcards and Dynamically Created Destinations on page 65. Clients can also create destinations as needed. Java Use the Session object’s createTopic() method to create a topic as a Destination object: Destination topic = session. Chapter 1. the existing destination is used. Looking up Administered Objects Stored in EMS on page 291 describes how to lookup topics and queues from an EMS server.java sample client for a working example. but these clients can use LDAP servers. TIBCO Enterprise Message Service User’s Guide .CreateTopic method to create a Destination object: Destination topic = session. See the tibemsMsgProducer.cs sample client for a working example.CreateQueue(queueName). Use the Session. Use the tibemsQueue_Create function to create a queue of type tibemsDestination: tibemsDestination queue = NULL.c sample client for a working example.CreateQueue method to create a Queue object: Destination queue = session.CreateTopic(topicName). See the csMsgProducer.queueName).268 | Chapter 9 Developing an EMS Client Application C Use the tibemsTopic_Create function to create a topic of type tibemsDestination: tibemsDestination topic = NULL. status = tibemsQueue_Create(&queue. C# Use the Session. status = tibemsTopic_Create(&topic.topicName). See the tibjmsMsgProducer. and have at least use_durable permission on the topic to attach to an existing durable subscriber for the topic. You must have durable permission on the topic to create a new durable subscriber for that topic. a Message Producer is commonly referred to as a Publisher. The following examples create a message producer that sends messages to the queue that was dynamically created in Dynamically Creating Topics and Queues on page 267. See the csMsgProducer. Java MessageProducer Use the Session object’s createProducer() method to create a object: MessageProducer QueueSender = session.createProducer(queue). C# Use the Session. when creating a Message Producer. You must have send permission on a queue to create a message producer that sends messages to that queue.queue).CreateProducer method to create a MessageProducer object: MessageProducer QueueSender = session. When working with topics. See User Permissions on page 239 for details. TIBCO Enterprise Message Service User’s Guide .cs sample client for a working example. a Message Producer is an EMS client that either publishes messages to a topic or sends messages to a queue. as described in Sending Messages on page 280. &QueueSender.Creating a Message Producer 269 | Creating a Message Producer As described in JMS Message Models on page 3. status = tibemsSession_CreateProducer(session. you can set the destination to NULL and specify the destination when you send or publish a message.CreateProducer(queue).java sample client for a working example. C Use the tibemsSession_CreateProducer function to create a message producer of type tibemsMsgProducer: tibemsMsgProducer QueueSender = NULL. See the tibemsMsgProducer. Optionally.c sample client for a working example. tibco. To configure the Message Producer with a default delivery mode of NON_PERSISTENT: QueueSender.270 | Chapter 9 Developing an EMS Client Application Configuring a Message Producer A message producer can be configured to generate messages with default headers and properties that define how those messages are to be routed and delivered. or RELIABLE_DELIVERY. as described in the RELIABLE_DELIVERY on page 26.jms.java sample client for a working example. Delivery mode cannot be set by using the Message. Set whether message IDs are disabled.RELIABLE_DELIVERY). C Use the tibemsMsgProducer_SetDeliveryMode function to configure your Message Producer to set a default delivery mode for each message it produces to RELIABLE_DELIVERY: tibems_int deliveryMode = TIBEMS_RELIABLE. Set the producer's default priority. Java Use the MessageProducer object’s setDeliveryMode() method to configure your Message Producer with a default delivery mode of RELIABLE_DELIVERY: QueueSender. According to the JMS specification.DeliveryMode.setJMSDeliveryMode() method. you can: • • • • • Set the producer's default delivery mode. Set whether message timestamps are disabled. See the tibjmsMsgProducerPerf.tibjms.NON_PERSISTENT).setDeliveryMode( com. Set the default length of time that a produced message should be retained by the message system. For example. the publisher ignores the value of the JMSDeliveryMode header field when a message is being published.Tibjms.setDeliveryMode( javax. deliveryMode). TIBCO Enterprise Message Service User’s Guide . status tibemsMsgProducer_SetDeliveryMode(QueueSender. you can set the message deliver mode to either PERSISTENT. Specifically. NON_PERSISTENT. cs sample client for a working example.DeliveryMode = DeliveryMode.RELIABLE_DELIVERY.Creating a Message Producer 271 | C# Set the DeliveryMode on the MessageProducer object to RELIABLE_DELIVERY: QueueSender. See the csMsgProducerPerf. TIBCO Enterprise Message Service User’s Guide . A Message Consumer can be created with a "message selector" that restricts the consumption of message to those with specific properties. A user must have durable permission on the topic to create a new durable subscriber for that topic. The following Session. or the maximum size of the queue is reached. The createDurableSubscriber method either creates a new durable subscriber for a topic or attaches the client to a previously created durable subscriber. messages remain on the queue until they are either consumed by a Message Consumer. For queues."myDurable").java sample client for a working example. See the tibjmsMsgConsumer. As described in Durable Subscribers for Topics on page 5. Java Use the Session object’s createConsumer() method to create a MessageConsumer object: MessageConsumer QueueReceiver = session.createConsumer(queue). otherwise the messages are not consumed and cannot be retrieved later. a Message Consumer is commonly referred to as a Subscriber. When creating a Message Consumer for topics.createDurableSubscriber() method creates a durable subscriber. The following examples create a Message Consumer that consumes messages from the queue and a durable subscriber that consumes messages from a topic. TIBCO Enterprise Message Service User’s Guide .272 | Chapter 9 Developing an EMS Client Application Creating a Message Consumer Message consumers are clients that receive messages published to a topic or sent to a queue. messages published to topics are only consumed by active subscribers to the topic. When working with topics. See User Permissions on page 239 for details. you can set a noLocal attribute that prohibits the consumption of messages that are published over the same connection from which they are consumed. even if it is not currently running. The queue and topic are those that were dynamically created in Dynamically Creating Topics and Queues on page 267.java sample client for a working example. A user must have at least use_durable permission on the topic to attach to an existing durable subscriber for the topic. See the tibjmsDurable.createDurableSubscriber(topic. the message expiration time has been reached. You can create a durable subscriber that ensures messages published to a topic are received by the subscriber. named "MyDurable": TopicSubscriber subscriber = session. status = tibemsSession_CreateDurableSubscriber(session.c sample client for a working example. See the tibemsDurable.CreateDurableSubscriber method creates a durable subscriber." of type tibemsMsgConsumer: tibemsMsgConsumer msgConsumer = NULL. TIBEMS_FALSE). C# Use the Session.cs sample client for a working example. named "MyDurable": TopicSubscriber subscriber = session. &QueueReceiver. "myDurable". NULL. &msgConsumer.c sample client for a working example.cs sample client for a working example. NULL. TIBEMS_FALSE). The following Session. TIBCO Enterprise Message Service User’s Guide . named "myDurable.Creating a Message Consumer 273 | C Use the tibemsSession_CreateConsumer function to create a message consumer of type tibemsMsgConsumer: tibemsMsgConsumer QueueReceiver = NULL.CreateConsumer method to create a MessageConsumer object: MessageConsumer QueueReceiver = session. See the csMsgConsumer. The following tibemsSession_CreateDurableSubscriber function creates a durable subscriber. See the csDurable. "myDurable"). queue. topic.CreateDurableSubscriber(topic. status = tibemsSession_CreateConsumer(session.createConsumer(queue). See the tibemsMsgConsumer. the Message Consumer explicitly calls a receive method on the topic or queue. that is called by the EMS server when a message arrives on a destination.createConsumer(queue). A Message Listener is not specific to the type of the destination. connection. create a MessageConsumer.setMessageListener(this). which is used by application servers. Java Create an implementation of the MessageListener interface. Once you create a Message Listener. See the J2EE documentation for more information about MDBs. You implement the onMessage method to perform the desired actions when a message arrives. you can implement a Message Listener that serves as an asynchronous event handler for messages. you must register it with a specific Message Consumer before calling the connection’s start method to begin receiving messages.start(). session and consumer */ . } Do not use the Session. rather than by applications. The same listener can obtain messages from a queue or a topic. and use the MessageConsumer object’s setMessageListener() method to register the Message Listener with the Message Consumer: public class tibjmsAsyncMsgConsumer implements MessageListener { /* Create a connection. A Message Listener implementation has one method.3 platform introduced message-driven beans (MDBs) that are a special kind of Message Listener. and it should not throw any exceptions.274 | Chapter 9 Developing an EMS Client Application Creating a Message Listener for Asynchronous Message Consumption EMS allows a Message Consumer to consume messages either synchronously or asynchronously. depending upon the destination set for the Message Consumer with which the listener is registered. MessageConsumer QueueReceiver = session. QueueReceiver.setMessageListener() method. For synchronous consumption.. onMessage.. TIBCO Enterprise Message Service User’s Guide . For asynchronous consumption. Your implementation should handle all exceptions. The J2EE 1. /* Create a connection.Creating a Message Consumer 275 | Implement the onMessage() method to perform the desired actions when a message arrives: public void onMessage(Message message) { /* Process message and handle exceptions */ } See the tibjmsAsyncMsgConsumer. status = tibemsSession_CreateConsumer(session. status = tibemsConnection_Start(connection).java sample client for a working example. TIBEMS_FALSE). tibemsMsg message. specifying onMessage() as the callback function: void run() { tibemsMsgConsumer QueueReceiver = NULL. NULL).c sample client for a working example.. C Implement an onMessage() function to perform the desired actions when a message arrives: void onMessage(tibemsMsgConsumer QueueReceiver. TIBCO Enterprise Message Service User’s Guide . status = tibemsMsgConsumer_SetMsgListener(QueueReceiver. that creates a tibemsMsgConsumer and uses the tibemsMsgConsumer_SetMsgListener function to create a message listener for the Message Consumer. &QueueReceiver. queue. session and consumer */ . NULL.. void* closure) { /* Process message and handle exceptions */ } In another function. } See the tibemsAsyncMsgConsumer. onMessage. cs sample clients for working examples..MessageListener = this. connection. MessageConsumer QueueReceiver = session.OnMessage method to perform the desired actions when a message arrives: public void OnMessage(Message message) { try { /* Process message and handle exceptions */ } } See the csAsyncMsgConsumer.CreateConsumer to create a MessageConsumer. TIBCO Enterprise Message Service User’s Guide .cs and csAsyncMsgConsumerUsingDelegate. } Implement the IMessageListener.Start(). session and consumer */ . and set the MessageListener property on the MessageConsumer object to register the Message Listener with the Message Consumer: public class csAsyncMsgConsumer : IMessageListener { /* Create a connection. use Session.276 | Chapter 9 Developing an EMS Client Application C# Create an implementation of the IMessageListener interface.. QueueReceiver.CreateConsumer(queue). The following examples show how to create a simple text message containing the string "Hello. EMS works with the following types of messages: • • • • • • Messages with no body Text Messages Map Messages Bytes Messages Stream Messages Object Messages There is a separate create method for each type of message. C Use the tibemsTextMsg_Create function to create a text message of type tibemsTextMsg: tibemsTextMsg message = "Hello". See the tibemsMsgProducer. TIBCO Enterprise Message Service User’s Guide ." Java Use the Session object’s createTextMessage() method to create a TextMessage: TextMessage message = session.c sample client for a working example.java sample client for a working example. See the tibjmsMsgProducer.createTextMessage("Hello"). status = tibemsTextMsg_Create(&message).Working with Messages 277 | Working with Messages Messages are a self-contained units of information used by JMS applications to exchange data or request operations. Creating Messages As described in JMS Message Bodies on page 22. CreateTextMessage method to create text message of type TextMessage: TextMessage message = session.278 | Chapter 9 Developing an EMS Client Application C# Use the Session. See the csMsgProducer.cs sample client for a working example. TIBCO Enterprise Message Service User’s Guide .CreateTextMessage("Hello"). GetStringProperty method to get the user ID of the JMS_TIBCO_SENDER: string userID = message.getStringProperty("JMS_TIBCO_SENDER"). C Use the tibemsMsg_SetBooleanProperty function to set the JMS_TIBCO_PRESERVE_UNDELIVERED property to true: status = tibemsMsg_SetBooleanProperty(message. Java Use the Message object’s setBooleanProperty() method to set the JMS_TIBCO_PRESERVE_UNDELIVERED property to true: message.SetBooleanProperty method to set the JMS_TIBCO_PRESERVE_UNDELIVERED property to true: message. status = tibemsMsg_GetStringProperty(message. Use the getStringProperty() method to get the user ID of the JMS_TIBCO_SENDER: userID = message. &userID). C# Use the Message.GetStringProperty("JMS_TIBCO_SENDER").Working with Messages 279 | Setting and Getting Message Properties Before a client sends a message.setBooleanProperty("JMS_TIBCO_PRESERVE_UNDELIVERED". Use the tibemsMsg_GetStringProperty function to get the user ID of the JMS_TIBCO_SENDER: char* userID = NULL. Use the Message. The client can check the message properties with a "get property" method. "JMS_TIBCO_SENDER". true).SetBooleanProperty("JMS_TIBCO_PRESERVE_UNDELIVERED". it can use a "set property" method to set the message properties described in EMS Message Properties on page 19. true). TIBCO Enterprise Message Service User’s Guide . true). "JMS_TIBCO_PRESERVE_UNDELIVERED". send(message). to send messages to a destination. See the tibjmsMsgProducer. TIBCO Enterprise Message Service User’s Guide . and JMSPriority message header fields described in JMS Message Header Fields on page 17 when sending each message. you can optionally set the JMSDeliveryMode. described in Creating a Message Producer on page 269.createProducer(null). if the Message Producer specifies NULL as the destination. You can either send a message the destination specified by the Message Producer or. Use the following form of the destination: send() method to send a message to a specific MessageProducer NULLsender = session. .. The second example uses a Message Producer. that specifies a destination of NULL and sends the message to the topic created in Dynamically Creating Topics and Queues on page 267. Java Use the MessageProducer object’s send() method to send a message to the destination specified by the MessageProducer object: QueueSender. NULLsender. JMSExpiration. The following examples show two ways to send a text message in each language.280 | Chapter 9 Developing an EMS Client Application Sending Messages You can use the Message Producer client..java sample client for a working example. In either case. Messages for more information about creating messages. The first example sends the message to the Message Producer. you can send a message to a specific destination.send(topic. See Chapter 2. message). created in Creating a Message Producer on page 269. QueueSender.. NULLsender. Send(topic. C# Use the MessageProducer. NULLsender.Send method to send a message to the destination specified by the MessageProducer: QueueSender. message).cs sample client for a working example. Use the tibemsMsgProducer_SendToDestination function to send the message to a specific destination: status = tibemsMsgProducer_SendToDestination(NULLsender. See the csMsgProducer. Use the following form of the MessageProducer.Send method to send a message to a specific destination: MessageProducer NULLsender = session. Unlike the Java and C# APIs.c sample client for a working example. See the tibemsMsgProducer. message). you can use the tibemsMsgProducer_SendToDestination function to specify the destination regardless of whether a destination is in the tibemsMsgProducer. topic. message).Working with Messages 281 | C Use the tibemsMsgProducer_Send function to send a message to the destination specified by the tibemsMsgProducer: status = tibemsMsgProducer_Send(QueueSender. in the C API.CreateProducer(NULL).Send(message). TIBCO Enterprise Message Service User’s Guide . You can also implement a Message Listener for your Message Consumer to asynchronously receive messages. Before exiting.start(). Java Use the Connection object’s start() method to start the connection: connection. as described in Creating a Message Listener for Asynchronous Message Consumption on page 274.282 | Chapter 9 Developing an EMS Client Application Receiving Messages The Message Consumer created in Creating a Message Consumer on page 272 receives messages from a destination and acknowledges the receipt of messages using the acknowledge mode established for the session. TIBCO Enterprise Message Service User’s Guide . This is typically used in a loop for the duration the client wishes to receive messages: Message message = QueueReceiver. The following examples start the connection created in Connecting to the EMS Server on page 262.close(). the Message Consumer must start the connection to the EMS server. synchronously receive messages from the queue created in Dynamically Creating Topics and Queues on page 267. See the tibjmsMsgConsumer.java sample client for a working example. When the client has finished receiving messages. Use the MessageConsumer object’s receive() method to receive a message. Before receiving messages.receive(). it uses the Close() method to close the connection: connection. as described in Creating a Session on page 264. the Message Consumer must close the connection. and then close the connection. Close function to close the connection: connection. status = tibemsMsgConsumer_Receive(QueueReceiver.receive(). use the tibemsConnection_Close function to close the connection: status = tibemsConnection_Close(connection).Working with Messages 283 | C Use the tibemsConnection_Start function to start the connection: status = tibemsConnection_Start(connection).&message).Close().Receive function to receive a message. When the client has finished receiving messages. use the Connection.cs sample client for a working example.c sample client for a working example. See the tibemsMsgConsumer. See the csMsgConsumer. Use the tibemsMsgConsumer_Receive function to receive a message. TIBCO Enterprise Message Service User’s Guide . When the client has finished receiving messages. Use the MessageConsumer. This is typically used in a loop for the duration the client wishes to receive messages: Message message = QueueReceiver.Start function to start the connection: connection. This is typically used in a loop for the duration the client wishes to receive messages: tibemsMsg message = NULL.Start(). C# Use the Connection. 284 | Chapter 9 Developing an EMS Client Application TIBCO Enterprise Message Service User’s Guide . | 285 TIBCO Enterprise Message Service User’s Guide . 286 | Chapter 9 Developing an EMS Client Application TIBCO Enterprise Message Service User’s Guide . topics and queues. Java clients can look up administered objects stored in EMS using standard JNDI calls.| 287 Chapter 10 Using the EMS Implementation of JNDI The EMS server provides a implementation of JNDI that enables you to lookup connection factories. The C and C# APIs provide similar calls to look up object data in the EMS server. How to create topics and queues is described in Creating and Modifying Destinations on page 61. page 288 Looking up Administered Objects Stored in EMS. Topics • • Creating and Modifying Administered Objects in EMS. which are collectively referred to as administered objects. page 291 TIBCO Enterprise Message Service User’s Guide . named myFactory. This section describes how to create administered objects using the administration tool. as described in Connection Factory Properties on page 210. or directly in the configuration files. and removeprop factory commands. to set the maximum number of connection attempts for the connection factory. myFactory.288 | Chapter 10 Using the EMS Implementation of JNDI Creating and Modifying Administered Objects in EMS You can create administered objects for storage in EMS using either the administration tool or the administration APIs. A connection factory may include optional properties for balancing server load and establishing thresholds for attempted connections. enter: setprop factory myFactory connect_attempt_count=2 TIBCO Enterprise Message Service User’s Guide .conf file. For example. to create a generic connection factory. use the create factory command in the EMS Administration Tool. start the EMS Administration Tool and enter: addprop factory myFactory connect_attempt_count=5 And to reset the value back to 2. from the default value of 2 to 5. For example. You can use the show factories command to list all of the connection factories on your EMS server and the show factory command to show the configuration details of a specific connection factory. start the EMS Administration Tool and enter: create factory myFactory generic URL=tcp://server1:7344 The connection factory data stored on the EMS server is located in the factories. that establishes a TCP connection to port 7344 on server1. These properties can be specified when creating the factory or modified for an existing factory using the addprop factory. You create a connection factory. setprop factory. and to set the ssl_auth_only parameter so that SSL is only used by the client when creating the connection.pem To create a factory to set up a topic connection. check the server's certificate (but not the name inside the certificate).cert. named mySecureFactory.Creating and Modifying Administered Objects in EMS 289 | Creating Connection Factories for Secure Connections This section describes how to create a static connection factory for establishing an SSL connection. Connections that are to be secured using SSL identify the transport protocol as ’ssl’ and may include any number of the SSL configuration parameters listed in SSL Server Parameters on page 188. For example. enter (all one line): create factory AnotherSSLFactory topic url=ssl://7243 ssl_verify_host=enabled ssl_verify_hostname=disabled ssl_trusted=certs/server_root. Similar SSL parameters must be used when looking up the connection factory.cert. Using the SSL Protocol. See Chapter 14. to create a generic connection factory. on page 365 for details. as described in Performing Secure Lookups. start the EMS Administration Tool and enter: create factory mySecureFactory generic URL=ssl://server1:7243 To create a factory to set up a generic connection and check the server's certificate to confirm the name of the server is myServer.pem is located in "certs" subdirectory of the directory where the server is running.cert. enter (all one line): create factory MySSLFactory generic url=ssl://7243 ssl_verify_host=enabled ssl_expected_hostname=myServer ssl_trusted=certs/server_root.pem ssl_auth_only=enabled These samples assume that the certificate server_root. that establishes a SSL connection to port 7243 on server1. TIBCO Enterprise Message Service User’s Guide . 290 | Chapter 10 Using the EMS Implementation of JNDI Creating Connection Factories for Fault-Tolerant Connections When connecting a fault-tolerant client to EMS, you must specify two or more EMS servers in your connection factory. When creating a connection factory for a fault-tolerant client, specify multiple server URLs in the url argument of the create factory command. For example, to create a generic connection factory, named myFtFactory, that establishes TCP connections to port 7545 on the primary server, server0, and port 7344 on the backup server, server1, start the EMS Administration Tool and enter (on one line): create factory myFtFactory generic url=tcp://server0:7545, tcp://server1:7344 Should server0 become unavailable, the client will connect to server1. See Chapter 15, Fault Tolerance, on page 383 for details. TIBCO Enterprise Message Service User’s Guide Looking up Administered Objects Stored in EMS 291 | Looking up Administered Objects Stored in EMS This section describes how to lookup objects from an EMS server by name. All clients can lookup objects in the EMS naming service. Alternatively, Java applications can lookup objects in a third-party JNDI server, and C and C# clients can lookup objects in a third-party LDAP server. See Chapter 1, Using JNDI With Third-Party Naming/Directory Services in the TIBCO Enterprise Message Service Application Integration Guide for details on how to look up connection factories from a third-party JNDI or LDAP server. To lookup administered objects stored in EMS, you need to create the initial context that identifies the URL of the naming service provider and any other properties, such as the username and password to authenticate the client to the service. The naming service provider URL has form: tibjmsnaming://host:port The following examples demonstrate how to access JMS administered objects when using TIBCO Enterprise Message Service. Each of these examples assume that a connection factory, named ConFac, exists in the factories.conf file, a topic.sample topic exists in topics.conf, and a queue.sample queue exists in queues.conf. Java Create an InitialContext object for the initial context, which consists of the provider context factory and JNDI provider URL, as well as the username and password to authenticate the client to the EMS server: Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.tibco.tibjms.naming.TibjmsInitialContextFactory"); env.put(Context.PROVIDER_URL,"tibjmsnaming://localhost:7222"); env.put(Context.SECURITY_PRINCIPAL, "userName"); env.put(Context.SECURITY_CREDENTIALS, "password"); InitialContext jndiContext = new InitialContext(env); Look up a connection factory, named ConFac, and destinations, named topic.sample and queue.sample, from the initial context: ConnectionFactory factory = (javax.jms.ConnectionFactory) jndiContext.lookup("ConFac"); javax.jms.Topic sampleTopic = (javax.jms.Topic)jndiContext.lookup("topic.sample"); javax.jms.Queue sampleQueue = (javax.jms.Queue)jndiContext.lookup("queue.sample"); TIBCO Enterprise Message Service User’s Guide 292 | Chapter 10 Using the EMS Implementation of JNDI See the tibjmsJNDI.java sample client located in the /ems/samples/java/JNDI directory. C Create a tibemsLookupContext object for the initial context, which consists of the JNDI provider URL and the username and password to authenticate the client to the EMS server: tibemsLookupContext* contextstatus = NULL; status = tibemsLookupContext_Create( &context, "tibjmsnaming://localhost:7222", "userName", "password"); Use the tibemsLookupContext_LookupConnectionFactory function to look up a connection factory, named ConFac, and use the tibemsLookupContext_LookupDestination function to look up the destinations, named topic.sample and queue.sample, from the initial context: tibemsConnectionFactory factory = NULL; tibemsDestination sampleTopic = NULL; tibemsDestination sampleQueue = NULL; status = tibemsLookupContext_Lookup(context, "ConFac", (void**)&factory); status = tibemsLookupContext_Lookup(context, "sample.queue", (void**)&sampleQueue); status = tibemsLookupContext_Lookup(context, "topic.sample, (void**)&sampleTopic); TIBCO Enterprise Message Service User’s Guide Looking up Administered Objects Stored in EMS 293 | C# Create a ILookupContext object for the initial context, which consists of the JNDI provider URL and the username and password to authenticate the client to the EMS server: Hashtable env = new Hashtable(); env.Add(LookupContext.PROVIDER_URL, "tibjmsnaming://localhost:7222"); env.Add(LookupContext.SECURITY_PRINCIPAL", "myUserName"); env.Add(LookupContext.SECURITY_CREDENTIALS", "myPassword"); LookupContextFactory factory = new LookupContextFactory(); ILookupContext searcher = factory.CreateContext( LookupContextFactory.TIBJMS_NAMING_CONT EXT, env); Use the ILookupContext.Lookup method to look up a connection factory, named ConFac, and destinations, named topic.sample and queue.sample, from the initial context: ConnectionFactory factory = (ConnectionFactory) searcher.Lookup("ConFac"); Topic sampleTopic = (Topic)searcher.Lookup("topic.sample"); TIBCO.EMS.Queue sampleQueue = (TIBCO.EMS.Queue)searcher.Lookup("queue.sample"); TIBCO Enterprise Message Service User’s Guide 294 | Chapter 10 Using the EMS Implementation of JNDI Looking Up Objects Using Full URL Names Java clients can look up administered objects using full URL names. In this case, the Context.URL_PKG_PREFIXES property is used in place of the Context.PROVIDER_URL property. For example: Hashtable env = new Hashtable(); env.put(Context.URL_PKG_PREFIXES,"com.tibco.tibjms.naming"); env.put(Context.PROVIDER_URL,"tibjmsnaming://localhost:7222"); env.put(Context.SECURITY_PRINCIPAL,"userName"); env.put(Context.SECURITY_CREDENTIALS,"password"); jndiContext = new InitialContext(env); When using full URL names, you can look up objects like the following example: Topic sampleTopic = (javax.jms.Topic)jndiContext.lookup( "tibjmsnaming://jmshost:7222/topic.sample"); Queue sampleQueue = (javax.jms.Queue)jndiContext.lookup( "tibjmsnaming://jmshost:7222/queue.sample"); For further information on how to use full URL names, refer to the tibjmsJNDIRead.java example located in the /ems/samples/java/JNDI directory. Performing Secure Lookups TIBCO Enterprise Message Service client programs can perform secure JNDI lookups using the Secure Sockets Layer (SSL) protocol. To accomplish this, the client program must set SSL properties in the environment when the InitialContext is created. The SSL properties are similar to the SSL properties for the TIBCO Enterprise Message Service server. See Chapter 14, Using the SSL Protocol for more information about using SSL in the TIBCO Enterprise Message Service server. TIBCO Enterprise Message Service User’s Guide Looking up Administered Objects Stored in EMS 295 | The following examples illustrate how to create an InitialContext that can be used to perform JNDI lookups using the SSL protocol. Java In this example, the port number specified for the Context.PROVIDER_URL is set to the SSL listen port that was specified in the server configuration file tibjsmd.conf. The value for TibjmsContext.SECURITY_PROTOCOL is set to ssl. Finally, the value of TibjmsContext.SSL_ENABLE_VERIFY_HOST is set to "false" to turn off server authentication. Because of this, no trusted certificates need to be provided and the client will then not verify the server it is using for the JNDI lookup against the server’s certificate. Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.tibco.tibjms.naming.TibjmsInitialContextFactory"); env.put(Context.PROVIDER_URL, tibjmsnaming://jmshost:7223); env.put(Context.URL_PKG_PREFIXES, "com.tibco.tibjms.naming") env.put(TibjmsContext.SECURITY_PROTOCOL, "ssl"); env.put(TibjmsContext.SSL_ENABLE_VERIFY_HOST, new Boolean("false")); Context context = new InitialContext(env); C Create a tibemsSSLParams object and use the tibemsSSLParams_SetIdentityFile function to establish the client identify by means of a pkcs12 file. Use the tibemsLookupContext_CreateSSL function to create a tibemsLookupContext object that uses an SSL connection for the initial context. tibemsLookupContext* tibemsConnection_Factory tibemsSSLParams tibems_status context factory sslParams status = = = = NULL; NULL; NULL; TIBEMS_OK; sslParams = tibemsSSLParams_Create(); status = tibemsSSLParams_SetIdentityFile( ssl_params, "client_identity.p12", TIBEMS_SSL_ENCODING_AUTO); status = tibemsLookupContext_CreateSSL( &context, "tibjmsnaming://localhost:7222", "userName", "password", sslParams, "pk_password"); TIBCO Enterprise Message Service User’s Guide 296 | Chapter 10 Using the EMS Implementation of JNDI C# Create a ILookupContext object for the initial context over an SSL connection. The SSL Store Info consists of a pkcs12 file that identifies the client and the client’s password, which are stored in an EMSSSLFileStoreInfo object. string ssl_identity = client_identity.p12; string ssl_target_hostname = "server"; string ssl_password = "password"; EMSSSLFileStoreInfo StoreInfo = new EMSSSLFileStoreInfo(); info.SetSSLClientIdentity(ssl_identity); info.SetSSLPassword(ssl_password.ToCharArray()); Hashtable env = new Hashtable(); env.Add(LookupContext.PROVIDER_URL, "adc1.na.tibco.com:10636"); env.Add(LookupContext.SECURITY_PRINCIPAL", "myUserName"); env.Add(LookupContext.SECURITY_CREDENTIALS", "myPassword"); env.Add(LookupContext.SECURITY_PROTOCOL, "ssl"); env.Add(LookupContext.SSL_TARGET_HOST_NAME, ssl_target_hostname); env.Add(LookupContext.SSL_STORE_TYPE, EMSSSLStoreType.EMSSSL_STORE_TYPE_FILE); env.Add(LookupContext.SSL_STORE_INFO, StoreInfo); TIBCO Enterprise Message Service User’s Guide Looking up Administered Objects Stored in EMS 297 | Performing Fault-Tolerant Lookups TIBCO Enterprise Message Service can perform fault-tolerant JNDI lookups. If the primary server fails and the backup server becomes the primary, the JNDI provider automatically uses the new primary server for JNDI lookups. You accomplish this by providing multiple URLs in the Context.PROVIDER_URL property when creating the InitialContext. Specify more than one URL separated by commas (,) in the property. Example The following illustrates setting up the Context.PROVIDER_URL property with the URLs of a primary EMS server on the machine named emshost and a backup EMS server on the machine named backuphost. env.put(Context.PROVIDER_URL, "tibjmsnaming://jmshost:7222, tibjmsnaming://backuphost:7222"); If at any time the first EMS server fails, the JNDI provider will automatically switch to the EMS server on the host backuphost for JNDI lookups. If emshost is repaired and restarted, it then becomes the backup EMS server. Limitations of Fault-Tolerant JNDI Lookups Fault-tolerant JNDI lookups do not occur in the following scenarios: • • When using full URL names in argument to the lookup method. When looking up an object that has been bound into a foreign naming/directory service such as LDAP. TIBCO Enterprise Message Service User’s Guide 298 | Chapter 10 Using the EMS Implementation of JNDI TIBCO Enterprise Message Service User’s Guide | 299 Chapter 11 Working With TIBCO Rendezvous This chapter describes the interoperation of EMS and TIBCO Rendezvous. Topics • • • • • • • • Overview, page 300 Configuring Transports for Rendezvous, page 302 Topics, page 306 Queues, page 308 Import Issues, page 310 Export Issues, page 312 Message Translation, page 313 Pure Java Rendezvous Programs, page 319 TIBCO Enterprise Message Service User’s Guide 9 and later). TIBCO Enterprise Message Service User’s Guide TIBCO Rendezvous Export . Scope • • EMS can import and export messages to an external system through an EMS topic. for details. When tibemsd imports or exports a messages. Figure 19 Rendezvous Transports in the EMS Server EMS Server EMS Topic Translation tibrv Transport EMS Destination (Topic or Queue) Translation tibrv Transport Import Message Translation EMS and Rendezvous use different formats for messages and their data. EMS can import messages from an external system to an EMS queue (but queues cannot export). see Message Translation on page 340. it translates the message and its data to the appropriate format.300 | Chapter 11 Working With TIBCO Rendezvous Overview TIBCO Enterprise Message Service (release 4 and later) can exchange messages with TIBCO Rendezvous (release 6. conf) globally enables or disables message exchange with Rendezvous. For details. RVCM Listeners When exporting messages on a transport configured for certified message delivery. see Configuring Transports for Rendezvous on page 302.conf on page 215. The default value is disabled. see Topics on page 334. and deliver them to the EMS destination. To use these transports.conf and the export and import properties on destinations described in this chapter.conf and destination properties for configuring communication with TIBCO Rendezvous.conf and queues. see tibrvcm. You can achieve the same functionality that these parameters provide by using transports. and Certified Messages on page 312 Deprecated Configuration Properties Previous releases of EMS provided properties in tibemsd. Transport definitions (in the configuration file transports.conf) can set the import and export properties to specify one or more transports: • • import instructs tibemsd to import messages that arrive on those transports from Rendezvous. Destination definitions (in the configuration files topics. For details. you must explicitly set this parameter to enabled. Enabling The parameter tibrv_transports (in the configuration file tibemsd. for details.conf. These properties are deprecated and are no longer recognized by the server.conf) specify the communication protocol between EMS and the external system. TIBCO Enterprise Message Service User’s Guide . you can pre-register RVCM listeners in the file tibrvcm. export instructs tibemsd to take messages that arrive on the EMS destination.Overview 301 | Configuration tibemsd uses definitions and parameters in four configuration files to guide the exchange of messages with Rendezvous. Transports Destinations and export them to Rendezvous via those transports. and Queues on page 335. For Rendezvous transports. When absent. surrounded by square brackets. Each definition begins with the name of a transport. service network When absent. the default value is the host computer’s primary network. supply hostname:protocol:port. The default protocol is tcp.302 | Chapter 11 Working With TIBCO Rendezvous Configuring Transports for Rendezvous Transports mediate the flow of messages between EMS and TIBCO Rendezvous. Rendezvous Parameters The syntax and semantics of these parameters are identical to the corresponding parameters in Rendezvous clients. the default value is an rvd process on the local host computer. see the Rendezvous documentation set. Transport definitions (in the file transports. When absent. You must properly configure these transports. When transporting messages between EMS and Rendezvous. The default port is 7500. TIBCO Enterprise Message Service User’s Guide . the value must be either tibrv or tibrvcm. the default value is 7500.conf) configure the behavior of these connections. Table 50 Rendezvous: Transport Parameters (Sheet 1 of 3) Parameter type Description Required. You may omit any of the three parts. timemsd Transport Definitions transports. To connect to a non-default daemon.conf contains zero or more transport definitions. connects to Rendezvous daemons in the same way as any other Rendezvous client would. Subsequent lines set the parameters of the transport. the rvd process must be configured to run on the same host as the EMS daemon (tbemsd). The daemon default hostname is the local host computer. For full details. true or false.Configuring Transports for Rendezvous 303 | Table 50 Rendezvous: Transport Parameters (Sheet 2 of 3) Parameter temp_destination_timeout Description Specifies the amount of time the server is to keep the temporary destination (created for the RV inbox) after its last use of the destination. ledger_file sync_ledger request_old default_ttl This parameter sets default CM time limit (in seconds) for all CM messages exported on this transport. The syntax and semantics of these parameters are identical to the corresponding parameters in Rendezvous CM clients. tibemsd allows RVCM listeners to register for certified delivery only if they are configured in advance with the EMS server (either in tibrvcm. tibemsd allows any RVCM listener to register. Name for file-based ledger. If true. For example. cm_name rv_tport Correspondent name. Required. operations that update the ledger do not return until changes are written to the storage medium. That is. tibemsd ignores registration requests from non-configured listeners. in a configuration in which rv-requester -> serverA -> serverB -> rv-responder. TIBCO Enterprise Message Service User’s Guide . true or false. If true. If true. true or false. Each RVCM transport depends in turn upon an ordinary Rendezvous transport. For full details. This is useful for a multi-server configuration. see the Rendezvous documentation set. this transport server requests unacknowledged messages sent from other RVCM senders while this transport was unavailable.conf. setting temp_destination_timeout=60 on serverB specifies that serverB is to hold the temporary destination for 60 seconds.conf or using the create rvcmlistener command). Rendezvous Certified Messaging (RVCM) Parameters Use these properties only for tibrvcm transports. explicit_config_only If false (the default). Set this parameter to the name of a Rendezvous transport (type tibrv) defined in the EMS configuration file transports. TIBEMS_PERSISTENT | TIBEMS_NON_PERSISTENT | TIBEMS_RELIABLE When absent. However. When false. tibemsd suppresses JMS properties in exported messages. TIBCO Enterprise Message Service User’s Guide . tibemsd includes JMS header fields in exported messages. export_properties When true. Instead. tibemsd includes JMS properties in exported messages. the default value is true. Rendezvous clients cannot set this header. When absent. the default is TIBEMS_NON_PERSISTENT. these two parameters determine the delivery modes for all topic messages and queue messages that tibemsd imports on this transport. the default value is true.304 | Chapter 11 Working With TIBCO Rendezvous Table 50 Rendezvous: Transport Parameters (Sheet 3 of 3) Parameter EMS Parameters topic_import_dm queue_import_dm Description EMS sending clients can set the JMSDeliveryMode header field for each message. export_headers When true. When absent. tibemsd suppresses JMS header fields in exported messages. When false. Configuring Transports for Rendezvous 305 | Example These examples from transports. [RV01] type = tibrv topic_import_dm = TIBEMS_RELIABLE queue_import_dm = TIBEMS_PERSISTENT service = 7780 network = lan0 daemon = tcp:host5:7885 [RV02] type = tibrv service = 7890 network = lan0 daemon = tcp:host5:7995 temp_destination_timeout = 60 [RVCM01] type = tibrvcm export_headers = true export_properties = true rv_tport = RV02 cm_name = RVCMTrans1 ledger_file = ledgerFile.conf illustrate the syntax of transport definitions.store sync_ledger = true request_old = true default_ttl = 600 TIBCO Enterprise Message Service User’s Guide . see topics. (For general information about topics.news export="RV02" Rendezvous messages with subject myTopics.conf on page 202. Import Only when Subscribers Exist When a topic specifies import on a connected transport. you can configure topic definitions (in the configuration file topics.news. tibemsd imports messages only when the topic has registered subscribers.news are exported to Rendezvous over transport RV02.306 | Chapter 11 Topics Working With TIBCO Rendezvous Topics can both export and import messages.news arrive at tibemsd over the transports RV01 and RV02. You can also configure topics using the administration tool command addprop topic.conf) with import and export properties that specify one or more external transports: import • import instructs tibemsd to import messages that arrive on those transports from Rendezvous.) Example For example. addprop topic myTopics. EMS clients can receive those messages by subscribing to myTopics. export instructs tibemsd to take messages that arrive on the EMS destination.news.RV02" addprop topic myTopics. EMS messages sent to myTopics. export • and export them to Rendezvous via those transports. TIBCO Enterprise Message Service User’s Guide . and to export messages on the transport RV02.news to import messages on the transports RV01 and RV02. The EMS server never re-exports an imported message on the same topic. the following tibemsadmin commands configure the topic myTopics. Accordingly. Rendezvous clients of the corresponding daemons can receive those messages by subscribing to myTopics.news import="RV01. and deliver them to the EMS destination.conf syntax and semantics. RVCM Ledger tibrvcm transports can store information about subjects in a ledger file. see show rvcmtransportledger on page 145). TIBCO Enterprise Message Service User’s Guide .Topics 307 | Wildcards Wildcards in the import and export properties obey EMS syntax and semantics (which is identical to Rendezvous syntax and semantics). see Destination Name— Syntax and Semantics on page 332. Rendezvous certified transports guarantee message delivery. You can review the ledger file using an administration tool command. Certified Messages You can import and export TIBCO Rendezvous certified messages (tibrvcm transport) to EMS topics. see TIBCO Rendezvous documentation. For more information about ledger files. 308 | Chapter 11 Queues Working With TIBCO Rendezvous Queues can import messages. tibemsd immediately begins importing messages to the queue. For static queues (configured by an administrator) tibemsd continues importing until you explicitly delete the queue.news to import messages on the transports RV01 and RV02.in.conf syntax and semantics.in arrive at tibemsd over the transports SS01 and SS02. TIBCO Enterprise Message Service User’s Guide .conf) with the import property that specify one or more external transports. You can also configure queues using the administration tool command addprop queue. even when no receivers exist for the queue. EMS clients can receive those messages by subscribing to myQueue. the following tibemsadmin command configures the queue myTopics. Import—Start and Stop When a queue specifies import on a connected transport. see queues. addprop queue myQueue. and deliver them to the EMS destination. Configuration You can configure queue definitions (in the configuration file queues. (For general information about queues.RV02" Rendezvous messages with subject myQueue. • import instructs tibemsd to import messages that arrive on those transports from Rendezvous.in import="RV01.conf on page 203. but cannot export them.) Example For example. TIBCO Enterprise Message Service User’s Guide . If you define a queue that imports foo.Queues 309 | Wildcards Wildcards in the import property obey EMS syntax and semantics (not Rendezvous syntax and semantics).bar and foo. As messages arrive. see Destination Name—Syntax and Semantics on page 332.baz) and delivers the messages to them. EMS clients cannot subscribe to wildcard queues—however. That is.bar and foo.baz will both inherit those properties. Notices that tibemsd delivers messages to these dynamic child queues even when no subscribers exist to drain them. you can configure a static queue named foo. foo. so that child queues named foo. tibemsd begins importing all matching messages from Rendezvous.* and set properties on it. tibemsd creates dynamic child queues (for example. you can define wildcards queues in the EMS server for the purpose of property inheritance.*. When a topic and a queue share the same name. the sender program no longer certifies delivery. it sets the JMSExpiration field of the EMS message to the time limit of the certified message. imported destination names must be unique. which exports messages to Rendezvous.bar are both defined. tibemsd Usually this value represents a Rendezvous subject. JMSDestination When tibemsd imports and translates a Rendezvous message. JMSExpiration When tibemsd imports and translates a Rendezvous certified message. Therefore. If the message time limited is exceeded. it sets the JMSReplyTo field of the EMS message to the value of the Rendezvous reply subject. TIBCO Enterprise Message Service User’s Guide . You must explicitly configure to create a topic with a corresponding name. it sets the JMSDestination field of the EMS message to the value of the Rendezvous subject. if a topic foo. For example.bar and a queue foo. only one may specify the import property. JMSReplyTo When tibemsd imports and translates a Rendezvous message.310 | Chapter 11 Working With TIBCO Rendezvous Import Issues This section presents issues associated with importing messages to EMS from Rendezvous—whether on a topic or a queue. at most one of them may set the import property. so that EMS clients can reply to the message. The transport definition must set topic_import_dm or queue_import_dm (as appropriate) to TIBEMS_PERSISTENT. all three of these conditions must be true: • • • Rendezvous senders must send labeled messages on RVCM transports. A durable subscription for the EMS topic or queue must exist.Import Issues 311 | Guaranteed Delivery For full end-to-end certified delivery from Rendezvous to EMS. TIBCO Enterprise Message Service User’s Guide . or in the configuration file tibrvcm.conf on page 215). When tibemsd exports such a message to Rendezvous. you must explicitly configure tibemsd to import replies from Rendezvous to that reply topic. Pre-register an RVCM listener. you do not need to configure it explicitly. the following condition must be true: • EMS senders must send persistent messages. it receives labeled messages as reliable messages. it automatically arranges to import replies to that temporary topic from Rendezvous. TIBCO Enterprise Message Service User’s Guide . it registers to receive subsequent messages as certified messages. When exporting such a message to Rendezvous. either with the administration tool (see create on page 111). Until the registration is complete. When exporting messages on a tibrvcm transport. Consider an EMS message in which the field JMSReplyTo contains a temporary topic. rvcmlistener Guaranteed Delivery For full end-to-end certified delivery to Rendezvous from EMS.conf (see tibrvcm.312 | Chapter 11 Working With TIBCO Rendezvous Export Issues This section presents issues associated with exporting messages from EMS to Rendezvous. Temporary Topics Certified Messages RVCM Registration When an RVCM listener receives its first labeled message. we recommend either of two actions to ensure certified delivery for all exported messages: • • Create the RVCM listener before sending any messages from EMS clients. JMSReplyTo Topics Consider an EMS message in which the field JMSReplyTo contains a topic. You can instruct tibemsd to suppress the entire header submessage in all exported messages by setting the transport property export_headers = Table 51 presents the mapping of JMS header fields to Rendezvous data types (that is. tibemsd does not set any JMS header fields. The field JMSHeaders contains that submessage.Message Translation 313 | Message Translation JMS Header Fields EMS supports the ten predefined JMS header fields. see JMS Message Header Fields on page 17. Special Cases These header fields are special cases: • • • JMS header JMSDestination corresponds to Rendezvous subject. tibemsd groups all the JMS header fields (except for the special cases noted above) into a single submessage within the Rendezvous message. tibemsd Export ignores any JMS header fields that are null or absent—it omits them from the exported message. Fields of the submessage map the names of JMS header fields to their values. Table 51 Rendezvous: Mapping JMS Header Fields to RV Datatypes (Sheet 1 of 2) JMS Header Name JMSDeliveryMode JMSPriority JMSTimestamp JMSExpiration JMSType Rendezvous Type TIBRVMSG_U8 TIBRVMSG_U8 TIBRVMSG_U64 TIBRVMSG_U64 TIBRVMSG_STRING TIBCO Enterprise Message Service User’s Guide . JMS header JMSReplyTo corresponds to Rendezvous reply subject. When exporting an EMS message to a Rendezvous message. JMS header JMSExpiration corresponds to the time limit of the Rendezvous certified message. false. the type of the corresponding field in the exported message). Import When importing a Rendezvous message to an EMS message. except for the special cases noted above. to indicate that the message might contain submessage fields or array fields. Import RVCM In addition to the two fields described above. A long value indicating the CM sequence number of an RVCM message imported from TIBCO Rendezvous. to indicates that the message did not originate from an EMS client. it can also set these properties (if the corresponding information is set in the Rendezvous message): Table 52 Rendezvous Mapping Message Properties Property JMS_TIBCO_CM_PUBLISHER Description A string value indicating the correspondent name of the TIBCO Rendezvous CM transport that sent the message (that is.314 | Chapter 11 Working With TIBCO Rendezvous Table 51 Rendezvous: Mapping JMS Header Fields to RV Datatypes (Sheet 2 of 2) JMS Header Name JMSMessageID JMSCorrelationID JMSRedelivered JMSDestination JMSReplyTo Rendezvous Type TIBRVMSG_STRING TIBRVMSG_STRING TIBRVMSG_BOOL send subject in TIBCO Rendezvous subject in TIBCO Rendezvous reply JMS Property Fields Import When importing a Rendezvous message to an EMS message. JMS_TIBCO_MSG_EXT gets the value true. the sender name). JMS_TIBCO_CM_SEQUENCE TIBCO Enterprise Message Service User’s Guide . tibemsd sets these JMS properties: • • JMS_TIBCO_IMPORTED gets the value true. when tibemsd imports a certified message on a tibrvcm transport. tibemsd For information about JMS body types. TIBCO Enterprise Message Service User’s Guide . We strongly discourage you from using these field names in either EMS and Rendezvous applications. The field JMSProperties contains that submessage. see JMS Message Bodies on page 22.Message Translation 315 | Export When exporting an EMS message to a Rendezvous message. tibemsd can import messages with any message type from TIBCO Rendezvous. The field names DATA and _data_ are reserved. You can instruct tibemsd to suppress the entire properties submessage in the exported message by setting the transport property export_properties = false. Table 53 Rendezvous: Mapping Message Types (Import) Rendezvous Field JMSBytes JMSObject JMSStream JMSText EMS Body Type JMSBytesMessage JMSObjectMessage JMSStreamMessage JMSTextMessage JMSMapMessage None of these fields are present. tibemsd translates it to an EMS message body types based on the presence of the fields in Table 53. Message Body can export messages with any JMS message body type to TIBCO Rendezvous. The tibemsd daemon ignores any JMS property fields that are not set. Conversely. Import When importing a Rendezvous message. For information about the structure of messages. Fields of the submessage map the names of JMS property fields to their values. and especially when these two message transport mechanisms interoperate. or are set to null—it omits them from the exported message. see JMS Message Structure on page 17. tibemsd groups all the JMS property fields into a single submessage within the Rendezvous message. MapMessage The message data fields map directly to top-level fields in the Rendezvous message. this field is omitted. see JMS Header Fields on page 313. It has type TIBRVMSG_OPAQUE. It has type TIBRVMSG_OPAQUE.316 | Chapter 11 Working With TIBCO Rendezvous Export When exporting an EMS message. It has type TIBRVMSG_OPAQUE. The fields retain the same names as in the original EMS message. The field JMSText receives this data. see JMS Property Fields on page 314. The field JMSBytes receives this data. ObjectMessage The message data translates to a byte array containing the serialized Java object. The field JMSStream receives this data. When the transport parameter export_properties is false. The field JMSObject receives this data. When the transport parameter export_headers is false. When translating the data fields of an EMS message. the results depend on the JMS body type. EMS Extensions to JMS Messages on page 16. See also. TIBCO Enterprise Message Service User’s Guide . • • Table 54 Rendezvous: Mapping Message Types (Export) JMS Body Type BytesMessage Export Translation The message data translates to a byte array that contains the bytes of the original EMS message. tibemsd translates it to a Rendezvous message with the following structure: • The field JMSHeaders contains a submessage. this field is omitted. Table 54 specifies the mapping. It has type TIBRVMSG_STRING. StreamMessage The message data translates to a byte array that encodes the objects in the original EMS message. TextMessage The message data translates to a UTF-8 string corresponding to the text of the original EMS message. The field JMSProperties contains a submessage. Message Translation 317 | Data Types Table 55 presents the mapping between EMS datatypes and Rendezvous datatypes.lang. Table 55 Rendezvous: Mapping Data Types (Sheet 1 of 2) EMS Boolean Byte Short Short Integer Integer Long Long Long Float Double Short Integer MapMessage Long byte[] java.String byte[] byte[] Map Rendezvous TIBRVMSG_BOOL TIBRVMSG_I8 <— TIBRVMSG_U8 TIBRVMSG_I16 <— TIBRVMSG_U16 TIBRVMSG_I32 <— TIBRVMSG_U32 TIBRVMSG_I64 <— TIBRVMSG_U64 TIBRVMSG_F32 TIBRVMSG_F64 <— <— TIBRVMSG_IPPORT16 TIBRVMSG_IPADDR32 TIBRVMSG_MSG <— TIBRVMSG_DATETIME TIBRVMSG_OPAQUE TIBRVMSG_STRING <— <— TIBRVMSG_XML TIBRVMSG_I8ARRAY TIBCO Enterprise Message Service User’s Guide . The mapping is bidirectional. except for the Rendezvous types that have no corresponding EMS type (for these types the mapping is marked as unidirectional in the middle column of Table 55). 318 | Chapter 11 Working With TIBCO Rendezvous Table 55 Rendezvous: Mapping Data Types (Sheet 2 of 2) EMS short[] short[] int[] int[] long[] long[] long[] float[] double[] Map <— Rendezvous TIBRVMSG_U8ARRAY TIBRVMSG_I16ARRAY <— TIBRVMSG_U16ARRAY TIBRVMSG_I32ARRAY <— TIBRVMSG_U32ARRAY TIBRVMSG_I64ARRAY <— TIBRVMSG_U64ARRAY TIBRVMSG_F32ARRAY TIBRVMSG_F64ARRAY TIBCO Enterprise Message Service User’s Guide . and configured before creating pure Java Rendezvous applications that use the TibrvJMSTransport class. are not supported by this transport.jar (included with EMS) and tibrvjweb. Both TIBCO Rendezvous and EMS must be purchased.Pure Java Rendezvous Programs 319 | Pure Java Rendezvous Programs TIBCO Enterprise Message Service is shipped with the tibrvjms. For more information about TibrvNetTransport and how to create use transports in TIBCO Rendezvous Java programs. The TibrvJMSTransport class provides Rendezvous reliable communication only.tibco. Table 56 on page 320 describes the additional methods of TibrvJMSTransport. your application must include tibrvjms.tibrv.TibrvJMSTransport class. This class extends the com.tibrv.tibco. To use the TibrvJMSTransport class. Other types of communication.TibrvNetTransport class and allows your pure Java Rendezvous programs to communicate directly with the EMS server instead of through rva.jar (included with TIBCO Rendezvous).jar file that you can include in your TIBCO Rendezvous applications. This JAR file includes the implementation of the com. installed. TIBCO Enterprise Message Service User’s Guide . This transport cannot be used to send messages to JMS queues. such as certified messaging. EMS topics receiving Rendezvous messages sent by way of the TibrvJMSTransport do not need to specify the import property. see TIBCO Rendezvous documentation. You can use TibrvJMSTransport only in Rendezvous applications. Applications using this transport can send messages to a topic on an EMS server that has the same topic name as the subject of the message. This class is not intended for use in your EMS Java clients. String userName. String password. Hashtable sslParameters. Sets the EMS persistent delivery mode for messages sent or received on this transport. Returns true if persistent delivery mode is set for this transport. You may also pass the clientID of your client connection. SSL parameters govern the connection between the Rendezvous Java client and tibemsd. When emulateReconnect is true. the first argument can be a list of server URLs. Returns a string representation of this transport. TibrvJMSTransport( String serverURL) throws TibrvException TibrvJMSTransport( String serverURL. and the recoverConnection method attempts to reconnect to one of them. If no parameters are passed. String clientId. and a username and a password to use to connect to the server. You can also pass the serverURL to connect to the EMS server at the specified location. String userName.320 | Chapter 11 Working With TIBCO Rendezvous Table 56 TibrvJMSTransport class (Sheet 1 of 2) Method TibrvJMSTransport() throws TibrvException Description Constructor for creating a TibrvJMSTransport. the transport assumes the server is running on the same machine with the default listener port. String clientId. boolean emulateReconnect) throws TibrvException destroy() toString() setPersistentDelivery( boolean persistent) isPersistentDelivery() TIBCO Enterprise Message Service User’s Guide . String password) throws TibrvException TibrvJMSTransport( String serverURL. Destroys the transport and all associated listeners. it throws an exception. Try servers in sequence. getCurrentConnectedServer() TIBCO Enterprise Message Service User’s Guide . Return a string identifying the server to which the transport is currently connected. If the call cannot connect to any server. starting with the most recently connected server.Pure Java Rendezvous Programs 321 | Table 56 TibrvJMSTransport class (Sheet 2 of 2) Method recoverConnection() throws TibrvException Description Reconnect to a server. 322 | Chapter 11 Working With TIBCO Rendezvous TIBCO Enterprise Message Service User’s Guide . | 323 TIBCO Enterprise Message Service User’s Guide . 324 | Chapter 11 Working With TIBCO Rendezvous TIBCO Enterprise Message Service User’s Guide . page 337 Export Issues. page 334 Queues. page 327 Topics.| 325 Chapter 12 Working With TIBCO SmartSockets This chapter describes the interoperation of TIBCO Enterprise Message Service and TIBCO SmartSockets. page 326 Configuring Transports for SmartSockets. Topics • • • • • • • Overview. page 338 Message Translation. page 335 Import Issues. page 340 TIBCO Enterprise Message Service User’s Guide . Scope • • EMS can import and export messages to an external system through an EMS topic. you must explicitly set this parameter to enabled. Enabling The parameter tibss_transports (in the configuration file tibemsd. for details. To use these transports. When tibemsd imports or exports a messages. Configuration tibemsd uses definitions and parameters in three configuration files to guide the exchange of messages with SmartSockets. see Message Translation on page 340.conf) globally enables or disables message exchange with SmartSockets.5 and later). Figure 20 SmartSockets Transports in the EMS Server EMS Server EMS Topic EMS Topic Translation Translation tibss Transport EMS EMS Destination EMS Destination (Topic or Queue) Destination (Topic or Queue) Translation Translation tibss Transport Import Message Translation EMS and SmartSockets use different formats for messages and their data. The default value is disabled. EMS can import messages from an external system to an EMS queue (but queues cannot export). TIBCO Enterprise Message Service User’s Guide TIBCO SmartSockets Export .326 | Chapter 12 Working With TIBCO SmartSockets Overview TIBCO Enterprise Message Service (release 4 and later) can exchange messages with TIBCO SmartSockets (release 6. it translates the message and its data to the appropriate format. Destinations and export them to SmartSockets via those transports. and deliver them to the EMS destination. You must properly configure these transports. Transports Transport definitions (in the configuration file transports. Starting the Servers We recommend starting the SmartSockets RTserver before starting tibemsd.conf and queues. see Configuring Transports for SmartSockets on page 327.conf) specify the communication protocol between EMS and the external system. connects to SmartSockets RTservers in the same way as any other SmartSockets client. Transport definitions (in the file transports. see Topics on page 334. export instructs tibemsd to take messages that arrive on the EMS destination. Configuring Transports for SmartSockets Transports mediate the flow of messages between TIBCO Enterprise Message Service and TIBCO SmartSockets.Configuring Transports for SmartSockets 327 | The parameter tibss_config_dir (in the configuration file tibemsd.conf) can set the import and export properties to specify one or more transports: • • import instructs tibemsd to import messages that arrive on those transports from SmartSockets.conf) specifies the location of SmartSockets files needed by the SmartSockets client within tibemsd. For details. and Queues on page 335. for details.conf) configure the behavior of these connections. Destination definitions (in the configuration files topics. timemsd TIBCO Enterprise Message Service User’s Guide . surrounded by square brackets.328 | Chapter 12 Working With TIBCO SmartSockets Transport Definitions transports. SmartSockets Parameters The syntax and semantics of these parameters are identical to the corresponding parameters in SmartSockets clients. For full details. For SmartSockets transports. the default project is rtworks. on Windows platforms. server_names The value is a comma-separated list specifying connections to one or more SmartSockets RTservers. When this parameter is absent. delivery_mode This parameter determines the quality of service with which delivers messages to the SmartSockets server over this transport: best_effort | gmd_all | gmd_some | ordered When absent. the default instructs the EMS server to attempt to connect to an RTserver on the local host computer (the same computer as the EMS server). You may omit any of the three parts. SmartSockets uses projects to maintain orthogonal subject name-spaces. the default is best_effort. When absent.conf contains zero or more transport definitions. Each definition begins with the name of a transport. the value must be tibss. see the SmartSockets documentation set. the default protocol is tcp and the default port is 5101. Subsequent lines set the parameters of the transport. A list of several servers specifies fault tolerance—timemsd attempts to connect to them in the order listed. username password project timemsd uses these two parameters to authenticate itself to the SmartSockets servers. The default hostname is the local host computer. The default protocols and ports vary with hardware and operating system platforms. using default protocols and ports. TIBCO Enterprise Message Service User’s Guide . Each item in the list has the form protocol:hostname:port. Table 57 SmartSockets: Transport Parameters (Sheet 1 of 4) Parameter type Description Required. type_num. the default is exact. a message logging facility would require all order messages. or all. subscribe_mode • • When subscriptions do not collide. For a definition of wildcard collision. When absent. for correct semantics. When subscriptions collide. specify all. the default is none. the EMS server) participates in load balancing (for example. even though many order-processing clients might share the load of order messages. rather than a subset. When absent. the default is disable. the default value is none. see Subscribe Mode on page 332. see SmartSockets Message Properties on page 341. disable instructs tibemsd to open the existing GMD store file. enable instructs tibemsd to delete the GMD store file and create a new one when creating this transport. override_lb_mode enable instructs the RTserver to deliver all messages on this client connection—even if other clients participate in load balancing. gmd_file_delete SmartSockets clients keep data for guaranteed message delivery (GMD) in a store file. The value can be none. disable informs the RTserver that this client (that is. none | round_robin | weighted | sorted When absent. This parameter determines the load balancing regimen for messages that this transport exports to the SmartSockets server. For complete details. import_ss_headers This parameter governs the import of SmartSockets message headers to EMS properties. When absent. When absent. TIBCO Enterprise Message Service User’s Guide . for best performance.Configuring Transports for SmartSockets 329 | Table 57 SmartSockets: Transport Parameters (Sheet 2 of 4) Parameter lb_mode Description SmartSockets servers balance the message load by distributing messages among several clients. specify exact. sharing the load with other EMS servers). the default is enable. For example. and complete details about the operation of these two modes. • • always instructs EMS to preserve all undelivered GMD messages in the EMS undelivered message queue. and SmartSockets cannot deliver that message. never • instructs EMS to discard all undelivered SmartSockets GMD messages. Set the value of JMS_TIBCO_SS_EXPIRATION to the current time—that is. see Message Translation on page 340. or discard it. When SmartSockets returns the undelivered message. then EMS does not preserve the undelivered message. Disregard the value of the import_ss_headers parameter. it follows these rules to convert the returned SmartSockets message to an EMS message: • • Follow all general rules for importing messages. When absent. This parameter applies only when the transport’s delivery_mode parameter is either gmd_all or gmd_some. if SmartSockets cannot deliver a message because no GMD receivers exist. see SmartSockets Message Properties on page 341. For a list of headers. the time at which the SmartSockets server returned the undelivered message to EMS. (Notice that the this header would otherwise remain unused. EMS can either preserve it in the EMS undelivered message queue. and instead import all SmartSockets headers (as if the value of import_ss_headers were all). receivers instructs EMS to preserve only those undelivered GMD messages that SmartSockets could not deliver despite the existence of one or more GMD receivers. That is.) • TIBCO Enterprise Message Service User’s Guide . since GMD messages do not expire. the default value is never.330 | Chapter 12 Working With TIBCO SmartSockets Table 57 SmartSockets: Transport Parameters (Sheet 3 of 4) Parameter preserve_gmd Description This parameter determines the behavior of the EMS server when it has exported a GMD message to SmartSockets. When the EMS server preserves a GMD message. the default value is true. the default is TIBEMS_NON_PERSISTENT. export_headers When true. When false. TIBEMS_PERSISTENT | TIBEMS_NON_PERSISTENT | TIBEMS_RELIABLE When absent. [SS01] type = tibss server_names = rtHost1 username = emsServer6 password = myPasswd project = sales_order_entry [SS02] type = tibss server_names = tcp:rtHost2A:5555. the default value is true. tibemsd includes JMS header fields in exported messages. tibemsd suppresses JMS header fields in exported messages. When false. When absent. these two parameters determine the delivery modes for all topic messages and queue messages that tibemsd imports on this transport. tibemsd suppresses JMS properties in exported messages. Instead.conf illustrate the syntax of transport definitions. tibemsd includes JMS properties in exported messages. When absent.Configuring Transports for SmartSockets 331 | Table 57 SmartSockets: Transport Parameters (Sheet 4 of 4) Parameter EMS Parameters topic_import_dm queue_import_dm Description EMS sending clients can set the JMSDeliveryMode header field for each message. However. Example These examples from transports. SmartSockets clients cannot set this header. ssl:rtHost2B:5571 username = emsServer6 password = myPasswd project = mfg_process_control override_lb_mode = enable delivery_mode = gmd_some TIBCO Enterprise Message Service User’s Guide . export_properties When true. bar. A leading dot indicates an empty element preceding it. However. an all connection carries more data than an exact connection. and once for the subscription to foo. the EMS name foo/bar. in EMS syntax. to the RTserver.baz corresponds to the SmartSockets name (Remember that SmartSockets names must begin with a leading slash.. As a result. to avoid confusion. the RTserver delivers each SmartSockets message with subject /foo/bar to this client (tibemsd) twice—once for the subscription to foo. The transport parameter subscribe_mode governs SmartSockets message filtering when EMS wildcard subscriptions collide.bar.) character. tibemsd does not recognize these duplicates as redundant. This section describes the mechanisms of subscription. and bidirectional.baz corresponds to the SmartSockets name /foo.bar). one-to-one. /foo/bar/baz. exact all instructs tibemsd to pass the subscription /. It is illegal to configure exact when EMS subscriptions collide. In EMS slash is an ordinary character. all Destination Name—Syntax and Semantics Slash & Dot Separators This aspect of the mapping between EMS destination names and SmartSockets subjects is straightforward. and the results when import subscriptions collide.) The slash and dot characters have complementary roles in EMS and SmartSockets. foo.bar.* collides with *. Consequently.*. the RTserver delivers all messages to this client (only once)—letting tibemsd filter the messages. TIBCO Enterprise Message Service User’s Guide . and foo. In SmartSockets slash is a separator. subject filtering occurs on the RTserver. and delivers two copies to each subscriber. while dot is an ordinary character. exact instructs tibemsd to pass subscriptions to the RTserver exactly as the EMS subscribers specify. tibemsd delivers messages to each subscriber as appropriate. EMS destination names consist of tokens separated by the dot (. we discourage using either slash or dot as ordinary characters. For example. To translate names between EMS and SmartSockets. but EMS names need not begin with a leading dot. so EMS subscribers do not receive duplicate messages. while dot is a separator.bar/baz. For example. SmartSockets subjects consists of tokens preceded by the slash (/) character (like UNIX directory pathnames). However.332 | Chapter 12 Working With TIBCO SmartSockets Subscribe Mode Both EMS and SmartSockets allow wildcard subscriptions to collide (for example. the EMS name foo.* collides with foo. As a result.. Because tibemsd requests all messages from SmartSockets. substitute these characters one for another. the mapping is not one-to-one.Configuring Transports for SmartSockets 333 | Wildcard Star Although both EMS and SmartSockets both interpret the star (*) character as a wildcard. If you are familiar with SmartSockets wildcards but not EMS wildcards. In EMS. TIBCO Enterprise Message Service User’s Guide . they differ in its semantics. In this aspect.. Trailing Wildcard In EMS the greater-than (>) character is a wildcard that matches any number of trailing tokens. In SmartSockets a string of three dots (. but not part of a token. see Wildcards on page 63. /foo/b*/baz matches /foo/bar/baz and /foo/box/baz. In SmartSockets.) signifies identical semantics.. star can match any whole token of a name. star can match part of an token—for example. ) Example For example. see topics. export instructs tibemsd to take messages that arrive on the EMS destination.news are exported to SmartSockets over all three transports—SS01.news to import and export messages on three transports. (For general information about topics. addprop topic myTopics. and deliver them to the EMS destination. tibemsd imports messages only when the topic has registered subscribers.news export="SS01. export • and export them to SmartSockets via those transports. The EMS server never re-exports an imported message on the same topic.SS02. You can also configure topics using the administration tool command addprop topic. TIBCO Enterprise Message Service User’s Guide . EMS messages sent to myTopics. SS02 and SS03. you can configure topic definitions (in the configuration file topics.conf) with import and export properties that specify one or more external transports: import • import instructs tibemsd to import messages that arrive on those transports from SmartSockets. Accordingly.news.conf syntax and semantics.SS02" addprop topic myTopics.334 | Chapter 12 Topics Working With TIBCO SmartSockets Topics can both export and import messages. SmartSockets clients of the corresponding RTservers can receive those messages by subscribing to /myTopics/news.SS03" SmartSockets messages with subject /myTopics/news arrive at tibemsd over the transports SS01 and SS02.conf on page 202.news import="SS01. Import Only when Subscribers Exist When a topic specifies import on a connected transport. EMS clients can receive those messages by subscribing to myTopics. the following tibemsadmin commands configure the topic myTopics. see queues. You can also configure queues using the administration tool command addprop queue. the following tibemsadmin command configures the queue myTopics. addprop queue myQueue.news to import messages on the transports SS01 and SS02.) Example For example. even when no receivers exist for the queue.conf syntax and semantics. Queues Queues can import messages. Configuration You can configure queue definitions (in the configuration file queues.in import="SS01.SS02" SmartSockets messages with subject /myQueue/in arrive at tibemsd over the transports SS01 and SS02. (For general information about queues.conf on page 203. see Destination Name—Syntax and Semantics on page 332. tibemsd immediately begins importing messages to the queue.in. EMS clients can receive those messages by subscribing to myQueue. For static queues (configured by an administrator) tibemsd continues importing until you explicitly delete the queue. and deliver them to the EMS destination.Queues 335 | Wildcards Wildcards in the import and export properties obey EMS syntax and semantics (not SmartSockets syntax and semantics).conf) with the import property that specify one or more external transports. Import—Start and Stop When a queue specifies import on a connected transport. • import instructs tibemsd to import messages that arrive on those transports from SmartSockets. TIBCO Enterprise Message Service User’s Guide . but cannot export them. EMS clients cannot subscribe to wildcard queues—however. foo. you can configure a static queue named foo. you can define wildcards queues in the EMS server for the purpose of property inheritance. tibemsd begins importing all matching messages from SmartSockets. see Destination Name—Syntax and Semantics on page 332. That is. As messages arrive. so that child queues named foo. If you define a queue that imports foo. tibemsd creates dynamic child queues (for example.baz will both inherit those properties.336 | Chapter 12 Working With TIBCO SmartSockets Wildcards Wildcards in the import property obey EMS syntax and semantics (not SmartSockets syntax and semantics). Notices that tibemsd delivers messages to these dynamic child queues even when no subscribers exist to drain them.baz) and delivers the messages to them.*.bar and foo. TIBCO Enterprise Message Service User’s Guide .* and set properties on it.bar and foo. The transport definition must set topic_import_dm or queue_import_dm (as appropriate) to TIBEMS_PERSISTENT.bar are both defined. TIBCO Enterprise Message Service User’s Guide . For example. Import Destination Names Must be Unique When a topic and a queue share the same name.Import Issues 337 | Import Issues This section presents issues associated with importing messages to EMS from SmartSockets—whether on a topic or a queue. Guaranteed Delivery For full end-to-end guaranteed delivery from SmartSockets to EMS. at most one of them may set the import property. see Guaranteed Delivery on page 339. For export guarantees. A durable subscription for the EMS topic or queue must exist. all three of these conditions must be true: • • • SmartSockets senders must send messages with guaranteed message delivery (GMD). it sets the JMSReplyTo field of the EMS message to the value of the SmartSockets reply_to header. JMSReplyTo When tibemsd imports and translates a SmartSockets message. if a topic foo. which exports messages to SmartSockets. Usually this value represents a SmartSockets subject. so that EMS clients can reply to the message. only one may specify the import property.bar and a queue foo. You must explicitly configure tibemsd to create a topic with a corresponding name. bar*. you must explicitly configure tibemsd to import replies from SmartSockets to that reply topic.338 | Chapter 12 Working With TIBCO SmartSockets Export Issues This section presents issues associated with exporting messages from EMS to SmartSockets. see Destination Name—Syntax and Semantics on page 332. it automatically arranges to import replies to that temporary topic from SmartSockets. Temporary Topics Wildcard Subscriptions Star Wildcard Both EMS and SmartSockets interpret the star character (*) as a wildcard—but with different semantics. which matches a whole element. When a SmartSockets client subscribes to foo. Consider an EMS message in which the field JMSReplyTo contains a temporary topic. matching a substring within the element. then configure tibemsd to export the superset foo. When tibemsd exports such a message to SmartSockets. you do not need to configure it explicitly. TIBCO Enterprise Message Service User’s Guide . EMS accepts star only as a whole element. JMSReplyTo Topics Consider an EMS message in which the field JMSReplyTo contains a topic. In contrast. SmartSockets accepts star as part of an element. RTserver narrows the set by delivering only messages that match subscribers. When exporting such a message to SmartSockets.*. For a full discussion of the differences between EMS and SmartSockets wildcards. both of these conditions must be true: • • EMS senders must send persistent messages. see preserve_gmd on page 330. To preserve undelivered GMD messages in the EMS undelivered queue. The transport definition must set delivery_mode to gmd_some or gmd_all (as appropriate). see Guaranteed Delivery on page 337.Export Issues 339 | Guaranteed Delivery For full end-to-end guaranteed delivery to SmartSockets from EMS. For import guarantees. TIBCO Enterprise Message Service User’s Guide . 340 | Chapter 12 Working With TIBCO SmartSockets Message Translation JMS Header Fields EMS supports the ten predefined JMS header fields. JMS_TIBCO_SS_SENDER gets the value of the SmartSockets sender header field (in SmartSockets syntax). indicating that the message did not originate from an EMS client. tibemsd sets these JMS properties: • • • JMS_TIBCO_IMPORTED gets the value true. TIBCO Enterprise Message Service User’s Guide . for details see SmartSockets Message Properties on page 341. except for the special cases noted above. The field JMSHeaders contains that submessage. Import When importing a SmartSockets message to an EMS message. indicating that the message might contain submessage fields or array fields. false. tibemsd maps SmartSockets message properties to EMS properties. see JMS Message Header Fields on page 17. When exporting an EMS message to a SmartSockets message. tibemsd groups all the JMS header fields (except for the special cases noted above) into a single submessage within the SmartSockets message. tibemsd Export ignores any JMS header fields that are null or absent—it omits them from the exported message. JMS_TIBCO_MSG_EXT gets the value true. Two Special Cases These two header fields are special cases: • • JMS header JMSDestination corresponds to SmartSockets dest. JMS header JMSReplyTo corresponds to SmartSockets reply_to. tibemsd does not set any JMS header fields. You can instruct tibemsd to suppress the entire header submessage in all exported messages by setting the transport property export_headers = JMS Property Fields Import When importing a SmartSockets message to an EMS message. Fields of the submessage map the names of JMS header fields to their values. In addition. The field JMSProperties contains that submessage. You can instruct tibemsd to suppress the entire properties submessage in the exported message by setting the transport property export_properties = false. tibemsd ignores any JMS property fields that are not set. The first column indicates the EMS property. TIBCO Enterprise Message Service User’s Guide . exporting a native EMS message does not carry these properties to SmartSockets. SmartSockets Message Properties In release 4. Asymmetr.1. tibemsd maps these properties in reverse.) Export of these properties depends on the value of the transport parameter export_properties on page 331. When exporting an EMS message to SmartSockets. JMS_TIBCO_SS_MESSAGE_ID and JMS_TIBCO_SS_SEQ_NUM) are asymmetric—export maps them to subfields of the field JMSProperties within the SmartSockets message. (However. The third column of Table 58 lists the values of that parameter for which tibemsd imports the message property in that row. EMS client programs may modify the values of these properties within imported messages for re-export to SmartSockets. tibemsd groups all the JMS property fields into a single submessage within the SmartSockets message. or are set to null—it omits them from the exported message.Message Translation 341 | Export When exporting an EMS message to a SmartSockets message. tibemsd maps SmartSockets message headers to EMS message properties on import. the mapping is symmetric—export maps them back to the same SmartSockets header.0 (and later). However. See import_ss_headers on page 329. Fields of the submessage map the names of JMS property fields to their values. Table 58 summarizes the mapping. The fourth column of Table 58 indicates this asymmetry. three exceptions (JMS_TIBCO_SS_SENDER. Import The transport parameter import_ss_headers governs the import behavior. and the second column indicates the SmartSockets method that gets the corresponding header. Export Table 58 SmartSockets Mapping Message Properties (Import & Export) (Sheet 1 of 2) EMS Property JMS_TIBCO_SS_SENDER SmartSockets Method TipcMsgGetSender Import none type_num all Export Asymmetr. In most cases. then it translates into a JMSStreamMessage. Import When importing a SmartSockets message. see JMS Message Structure on page 17. The map message contains the named fields. JMS_TIBCO_SS_DELIVERY_MODE JMS_TIBCO_SS_LB_MODE JMS_TIBCO_SS_EXPIRATION JMS_TIBCO_SS_PRIORITY JMS_TIBCO_SS_SENDER_TIMESTAMP JMS_TIBCO_SS_CORRELATION_ID JMS_TIBCO_SS_USER_PROP JMS_TIBCO_SS_MESSAGE_ID JMS_TIBCO_SS_SEQ_NUM TipcMsgGetDeliveryMode TipcMsgGetLbMode TipcMsgGetExpiration TipcMsgGetPriority TipcMsgGetSenderTimestamp TipcMsgGetCorrelationId TipcMsgGetUserProp TipcMsgGetMessageId TipcMsgGetSeqNum all all all all all all all all all Asymmetr. then it translates into a JMSMapMessage. Conversely. If the SmartSockets message contains one or more named fields. • TIBCO Enterprise Message Service User’s Guide . For information about the structure of messages. The stream contains the values of the unnamed fields in the same order as they appear in the SmartSockets message. see JMS Message Bodies on page 22.342 | Chapter 12 Working With TIBCO SmartSockets Table 58 SmartSockets Mapping Message Properties (Import & Export) (Sheet 2 of 2) EMS Property JMS_TIBCO_SS_TYPE_NUM SmartSockets Method TipcMsgGetType Import type_num all Export Asymmetr. Asymmetr. tibemsd translates it to one of two EMS message body types: • If the SmartSockets message contains only unnamed fields. the order of the fields is indeterminate. tibemsd can import messages with any message type from TIBCO SmartSockets. For information about JMS body types. Message Body tibemsd can export messages with any JMS message body type to TIBCO SmartSockets. It contains a submessage. indeterminate order One unnamed field of type T_MSG_FT_BINARY JMSObjectMessage T_MT_JMS_OBJECT JMSStreamMessage JMSTextMessage T_MT_JMS_STREAM T_MT_JMS_TEXT Unnamed fields in order One unnamed field of type T_MSG_FT_STR All other JMS message types T_MT_INFO No data fields TIBCO Enterprise Message Service User’s Guide . see the third column of Table 59. tibemsd translates it to one of six SmartSockets message types (see Table 59) with the following structure: • The named field JMSHeaders is the first field (omitted when the transport parameter export_headers is false).Message Translation 343 | Export When exporting an EMS message. The named field JMSProperties is the next field (omitted when the transport parameter export_properties is false). For details about field names and types. It contains a submessage. The data fields follow the JMS headers and properties (when present). • • Table 59 SmartSockets: Mapping Message Types (Export) JMS Message Type JMSBytesMessage SmartSockets Message Type T_MT_JMS_BYTES Data Fields One unnamed field of type T_MSG_FT_BINARY JMSMapMessage T_MT_JMS_MAP Named fields. see JMS Header Fields on page 340. see JMS Property Fields on page 340. The mapping is bidirectional.344 | Chapter 12 Working With TIBCO SmartSockets Data Types Table 60 presents the mapping between EMS datatypes and SmartSockets datatypes. Table 60 SmartSockets: Mapping Data Types (Sheet 1 of 2) EMS Boolean Byte Character Short Integer Long Float Double Double String String String Byte Array Short Array Short Array Integer Array Long Array Float Array Double Array Map SmartSockets T_MSG_FT_BOOL T_MSG_FT_CHAR T_MSG_FT_INT2 T_MSG_FT_INT2 T_MSG_FT_INT4 T_MSG_FT_INT8 T_MSG_FT_REAL4 T_MSG_FT_REAL8 <— T_MSG_FT_TIMESTAMP T_MSG_FT_STR <— <— T_MSG_FT_XML T_MSG_FT_UTF8 T_MSG_FT_BINARY <— T_MSG_FT_BOOL_ARRAY T_MSG_FT_INT2_ARRAY T_MSG_FT_INT4_ARRAY T_MSG_FT_INT8_ARRAY T_MSG_FT_REAL4_ARRAY T_MSG_FT_REAL8_ARRAY TIBCO Enterprise Message Service User’s Guide . except for a few SmartSockets types that have no corresponding EMS type (for these types the mapping is marked as unidirectional in the middle column of Table 60). Message Translation 345 | Table 60 SmartSockets: Mapping Data Types (Sheet 2 of 2) EMS Double Array Stream Message Map Message Map <— SmartSockets T_MSG_FT_TIMESTAMP_ARRAY T_MSG_FT_MSG (See Import on page 342.) Destination Names tibemsd automatically translates destination names when importing or exporting a message. TIBCO Enterprise Message Service User’s Guide . When importing. see Slash & Dot Separators on page 332. When exporting. it translates names in the SmartSockets subject and reply_to fields. it translates names in the EMS JMSDestination and JMSReplyTo fields. 346 | Chapter 12 Working With TIBCO SmartSockets TIBCO Enterprise Message Service User’s Guide . page 355 Working with Server Statistics. page 353 Monitoring Server Events. The logging. Topics • • • • Log Files and Tracing. monitoring.| 347 Chapter 13 Monitoring Server Activity System administrators must monitor and manage the TIBCO Enterprise Message Service server. page 360 TIBCO Enterprise Message Service User’s Guide . and statistics facilities provided by the server allow system administrators to effectively view system activity and track system performance. page 348 Message Tracing. if desired. You can move the files out of the log directory. the first copy is named tibems. The log can be written to a file.348 | Chapter 13 Monitoring Server Activity Log Files and Tracing You can configure the TIBCO Enterprise Message Service server to write a variety of information to the log. it is recommended that you remove or move all log files in the log file directory. Once the log file reaches its maximum size. The server can then restart its log file sequence with 1. MB. When you remove or move log files. The logfile_max_size configuration parameter allows you to specify the maximum size of the current log file. see Tracing and Log File Parameters on page 183.log. or to both.log. Set the parameter to 0 to specify no limit. or GB units. Configuring the Log File The logfile configuration parameter in tibemsd. You can also dynamically force the log file to be backed up and truncated using the rotatelog command in tibemsadmin. and the next log file is determined based on the first available numbered backup in the log file directory. For example. TIBCO Enterprise Message Service User’s Guide . Several parameters and commands control where the log is located as well as what information is written to the log. You can specify that the log file should be backed up and emptied after it reaches a maximum size. if the current log file is named tibems. See Command Listing on page 106 for more information about the rotatelog command. to the system console. This allows you to rotate the log file and ensure that the log file does not grow boundlessly.1.2.log. The server queries the directory and determines the first available sequence number. Use KB. and so on. the second is named tibems. it is copied to a file with the same name as the current log file except a sequence number is appended to the name of the backup file. For other configuration parameters that affect the log file.conf controls the location and the name of the log file. or the messages can provide warnings in the event of failures or illegal actions. or both. By specifying the -trace option when starting the server By using the set server command when the server is running. You configure tracing in the following ways: • • • By configuring the log_trace and/or console_trace parameters in the tibemsd. or Routing). log_trace and console_trace can be used to configure what types of messages are to go to the log file and to the console. Administration. but they are not used until the server is started with a valid log file. These messages can describe actions performed for various areas of functionality (for example. Trace messages can be sent to a log file. Table 61 describes the available tracing options. you have a variety of options for the types of trace messages that can be generated. TIBCO Enterprise Message Service User’s Guide . and the logfile configuration parameter is not set to a valid file. If you specify log_trace. the console. When you want trace messages to be sent to a log file.conf file. When configuring log or console tracing. These messages can also provide information about activities performed on or by the server. see Table 12 on page 123. the tracing options are stored.Log Files and Tracing 349 | Tracing on the Server The TIBCO Enterprise Message Service server can be configured to produce tracing messages. Access Control. you must also configure the logfile configuration parameter. and purging messages. For example. a message is printed when a user attempts to publish to a wildcard destination name. opening the persistent database files. Prints a message when a limit is exceeded. For example. Prints a message whenever an administration function is performed.350 | Chapter 13 Monitoring Server Activity Table 61 Server tracing options (Sheet 1 of 2) Trace Option DEFAULT Description Sets the trace options to the default set. This includes: • • • • • • • • • • INFO WARNING ACL LIMITS ROUTE ADMIN RVADV CONNECT_ERROR CONFIG MSG INFO Prints messages as the server performs various internal housekeeping functions. Prints a message when a user attempts to perform an unauthorized action. Also prints a message when tracking by message ID is enabled or disabled. such as the maximum size for a destination. Prints a message when a failure of some sort occurs. if the user attempts to publish a message to a secure topic for which the user has not been granted the publish permission. WARNING ADMIN LIMITS ACL TIBCO Enterprise Message Service User’s Guide . usually because the user attempts to do something illegal. such as creating a configuration file. If message tracing is not enabled for any messages or destinations. See Message Tracing on page 353 for more information about message tracing. Prints a message when the server enforces flow control or stops enforcing flow control on a destination. Specifies that message trace messages should be printed. Prints a message when an error occurs on a connection. Prints TIBCO Rendezvous advisory messages whenever they are received. Prints messages when LDAP is used for authentication or to obtain group information. Prints a message when a client performs a transaction.Log Files and Tracing 351 | Table 61 Server tracing options (Sheet 2 of 2) Trace Option SSL Description Prints detailed messages of the SSL process. Prints a message when a client creates or closes a producer or consumer. no trace messages are printed when this option is specified for log or console tracing. Prints a message when routes are created or when a route connection is established. Prints a message when a dynamic destination is created. Prints status and error messages related to the route. Prints a message when the server authenticates a user using an external LDAP system. Message tracing is enabled/disabled on a destination or on an individual message. Prints a message when a user attempts to connect to the server. Prints messages that trace the establishment of SSL connections. SSL_DEBUG ROUTE ROUTE_DEBUG CONNECT CONNECT_ERROR PRODCONS DEST TX LDAP_DEBUG AUTH MSG FLOW RVADV TIBCO Enterprise Message Service User’s Guide . including certificate content. but ADMIN messages are not shown. console_trace=RVADV TIBCO Enterprise Message Service User’s Guide . log_trace=DEFAULT. .A trace option preceded by .+SSL The next example sends a trace message to the console when a TIBCO Rendezvous advisory message arrives. in addition to SSL messages. Examples The following example sets the trace log to only show messages about access control violations.removes the option from the current set of trace options.352 | Chapter 13 Monitoring Server Activity Specify tracing with a comma-separated list of trace options.-ADMIN. log_trace=ACL The next example sets the trace log to show all default trace messages. + A trace option preceded by + adds the option to the current set of trace options. You may specify trace options in three forms: • • • plain A trace option without a prefix character replaces any existing trace options. The sections below describe the tracing properties for destinations and messages. If your application uses unprintable characters within messages (whether in data or headers). and the DEFAULT trace option includes the MSG option. EMS tracing features do not filter unprintable characters from trace output. you specify the trace property to enable the generation of trace messages. The MSG trace option specifies that message trace entries should be displayed. You must set the tracing property on either destinations or messages and also set the MSG or DEFAULT trace option on the console or the log before you can view trace entries for messages. For destinations. Trace entries for messages are only generated for destinations or messages that specify tracing should be performed. TIBCO Enterprise Message Service User’s Guide . the JMS_TIBCO_MSG_TRACE property specifies that tracing should be performed for this message.Message Tracing 353 | Message Tracing In addition to other server activity. SeeTracing on the Server on page 349 for more information about specifying trace options. For individual messages. Message trace entries can be output to either the console or the log. regardless of the destination settings. the results of message tracing are unpredictable. you can trace messages as they are processed. In the case of exported messages. trace entries are generated for the message as it is processed. Setting the property to "body" specifies the message body will be included in the trace entries for the message. Setting trace=body includes the message body in trace messages. the reply destination must have the trace property set. Enabling Message Tracing on a Message You can enable tracing on individual messages by setting the JMS_TIBCO_MSG_TRACE property on the message. the reply message automatically generates a trace entry when JMSReplyTo is set to a temporary destination.354 | Chapter 13 Monitoring Server Activity Enabling Message Tracing for a Destination The trace property on a destination specifies that trace entries are generated for that destination. When the JMS_TIBCO_MSG_TRACE property is set for a message. TIBCO Enterprise Message Service User’s Guide . a trace entry is output for each of the following events that occur in message processing: • • • • • • messages are received into a destination messages are sent to consumers messages are imported or exported to/from an external system messages are acknowledged messages are sent across a destination bridge messages are routed Also. Setting the property to null specifies only the message ID and message sequence will be included in the trace entries for the message. when a message is sent to a destination that has a trace property. The value of the property can be either null (Java/.NET null or NULL in C) or the string "body". Trace messages are generated for the message when it is sent by the producer and when it is received by the consumer. regardless of whether the trace property is set for any destinations the message passes through. any reply messages are traced when the request message is sent to a destination that has the trace property. When message tracing is enabled for a destination. If the reply to an exported message is sent to a static destination. Setting trace without the body option specifies that only the message sequence and message ID are included in the trace message. to generate a trace entry. This property can optionally be specified as trace=body. connection. For example. For example. Monitor topics are created and maintained by the server. The naming scheme for system event topics allows you to create wildcard subscriptions for all events of a certain class. Each event class is further subdivided into the events for each class. This section gives an overview of the monitoring facilities provided by the server. Users can subscribe to monitor topics but cannot create them. All system event topic names begin with $sys. the server publishes a message to the topic $sys. For example. you would create a topic subscriber for the topic $sys. There are several types of event classes. see Appendix B. Monitor topics are not listed in the topics. Monitor Messages. the server can publish a message when users connect or disconnect.Monitoring Server Events 355 | Monitoring Server Events The TIBCO Enterprise Message Service server can publish topic messages for several system events.monitor.conf file. For example. These event classes are used to group the system events into meaningful categories. each class groups a set of related events.connection. admin.monitor. the connection class has two events: connect and disconnect. For a list of monitor topics and a description of the message properties for each topic. on page 433. and route.*. The remainder of the name is the event class followed by the event. For example.monitor. System Monitor Topics The TIBCO Enterprise Message Service server can publish messages to various topics when certain events occur. System event messages contain detail about the event stored in properties of the message. TIBCO Enterprise Message Service User’s Guide . to receive messages whenever clients connect or disconnect.disconnect whenever a client disconnects from the server. some event classes are connection. Include the message body in the monitor message as a byte array. Use the createFromBytes() method when viewing the monitor message to recreate the message body. Table 62 describes the possible values of D and E in message monitoring topics. received.monitor. Destination to monitor is a queue. You can also monitor messages that have prematurely exited due to expiration.D.monitor topic for monitoring messages has the following format: $sys.destinationName Where D is the type of destination. Destination to monitor is a queue. or acknowledged. Table 62 Message monitoring qualifiers (Sheet 1 of 2) Qualifier D Value T Description Destination to monitor is a topic. and destinationName is the name of the destination whose messages you wish to monitor. Use the createFromBytes() method when viewing the monitor message to recreate the message body. Destination to monitor is a topic. if desired. if desired. Do not include the message body in the monitor message.356 | Chapter 13 Monitoring Server Activity Monitoring Messages You can monitor messages processed by a destination as they are sent.E. or a maxRedelivery failure. Include the message body in the monitor message as a byte array. being discarded. The $sys. E is the event you wish to monitor. Do not include the message body in the monitor message. t Q q TIBCO Enterprise Message Service User’s Guide . receive. on page 433 for a complete description of the properties available in monitoring messages.monitor.monitor. Monitor message is generated when a message is sent. or acknowledged for the specified destination. $sys.corp.* monitors all message events (send. depending upon the value of D. information about where the message came from (a producer.*. external system. and so on). or a maxRedelivery failure. being discarded. acknowledge) for all queues matching the name corp. Monitor Messages.News is the topic for monitoring any received messages to the topic named corp. and optionally the message body. TIBCO Enterprise Message Service User’s Guide .T.*. Monitor message is generated when a message prematurely exits due to expiration.News.Monitoring Server Events 357 | Table 62 Message monitoring qualifiers (Sheet 2 of 2) Qualifier E Value s Description Monitor message is generated when a message is sent by the server to: • • • a consumer a route an external system by way of a transport r Monitor message is generated when a message is received by the specified destination. The messages sent to this type of monitor topic include a description of the event. received. p * For example.q. route. See Appendix B. The message body is not included in this topic’s messages.corp. This occurs when the message is: • • • • Sent by a producer Sent by a route Forwarded from another destination by way of a bridge Imported from transport to an external system a Monitor message is generated when a message is acknowledged.r. The topic $sys. The message body of any received message is included in monitor messages on this topic. TIBCO Enterprise Message Service User’s Guide .monitor do not participate in any permission inheritance from parent topics other than those starting with $sys. specify wildcards in the destinationName portion of the message monitoring topic to subscribe to the message monitoring topic for all matching destinations. and you wish to allow user BOB to monitor all connection events. such as $sys. *.bar. You must explicitly grant users permission to $sys. create a client application that subscribes to the desired topics. The admin user and members of the $admin group have permission to perform any server action.monitor). That is.monitor.monitor topics (or parent topics.> will subscribe to all topics beginning with $sys. but it does not subscribe you to any specific message monitoring topic such as $sys. authentication and permissions are always checked when clients access a monitor topic.T. To view these topics. Because monitor topics contain potentially sensitive system information. That is. For performance reasons. All other users must be explicitly granted permission to view monitor topics before the user can successfully create subscribers for monitor topics.T. granting permission to a user to subscribe to > does not allow that user to subscribe to $sys. For example. subscribing to $sys.foo. clients are not able to access monitor topics unless they have logged in with a valid username and password and the user has permission to view the desired topic.monitor. even if authentication for the server is disabled.monitor.admin. you may want to avoid subscribing to too many message monitoring topics. including subscribing to monitor topics. For example. See Performance Implications of Monitor Topics on page 359 for more information. however.connect.> is not a parent of $sys.monitor.r.monitor.monitor topics. Therefore.> to monitor all messages received by all topics. if user BOB is not a member of the $admin group. you can grant BOB the required permission with the following command using the administration tool: grant topic $sys. Topics starting with $sys.* and view any connect or disconnect events.358 | Chapter 13 Monitoring Server Activity You must explicitly subscribe to a message monitoring topic.*. You can.monitor (that is.* BOB subscribe Bob’s application can then create a topic subscriber for $sys.monitor. you can subscribe to $sys.connection. Viewing Monitor Topics Monitor topics are just like any other topic.monitor.* or *.*) for a user to be able to subscribe to that topic. Also. Subscriptions to monitor topics in production systems should always be limited to specific monitor topics or wildcard subscriptions to specific classes of monitor topics that are required. For production systems. development and testing systems do not have large message volumes. using message selectors to limit monitor messages can improve performance slightly. Performance Implications of Monitor Topics The TIBCO Enterprise Message Service server only generates messages for monitor topics that currently have subscribers. no monitor messages are generated. such as creating topics. so creating subscriptions for these types of events will most likely not have a significant effect on performance.monitor. do not occur frequently. monitor events are likely to be added in future releases. Therefore there is still system overhead for subscribers to a monitor topic. just as it would handle any message sent to a topic. if no applications subscribe to monitor topics. For development and testing systems. You can create different applications that subscribe to different monitor topics. or you can create one application that subscribes to all desired monitor topics. Generating a monitor message does consume system resources. Your topic subscribers can also use message selectors to filter the monitor messages so your application receives only the messages it is interested in. Your application can receive and display all or part of a monitor message. so you can have any number of applications that subscribe to monitor messages. Each system event has different properties. Usually. and therefore you should consider what kinds of monitoring your environment requires. Monitor Messages. System administration events. Also. Monitor messages are like any topic messages. so the number of monitor topics may grow. you should not create topic subscribers for $sys. The server does not send any messages that do not match a subscriber’s message selector. So. on page 433 describes each of the monitor topics and the message properties for the messages published on that topic. and monitoring can give you information about system problems. monitoring all system events is probably desirable. routes. even if all messages for that topic do not match any subscriber’s message selector filter. monitoring all events may have an adverse effect on system performance. System performance is affected by the number of subscribers for monitor topics as well as the frequency of messages for those topics. Therefore. Even though the message is not sent. Information about the event is stored within properties in the message. Appendix B. consider the frequency of messages to each monitor topic. the message is still generated. and changing permissions.> in your production system.Monitoring Server Events 359 | Monitor topics publish messages of type MapMessage. TIBCO Enterprise Message Service User’s Guide . Also. but these are not included in the number of messages. Gathering this information consumes virtually no system resources. disk storage usage. The server_rate_interval configuration parameter controls the collection interval for server statistics. Statistics can be viewed using the administration tool. TIBCO Enterprise Message Service User’s Guide .360 | Chapter 13 Monitoring Server Activity Working with Server Statistics The TIBCO Enterprise Message Service server allows you to track incoming and outgoing message volume. You may wish to view average system usage statistics over a larger interval. However.tibjms. but only messages sent or received by a producer. or you can change the configuration dynamically using commands in the administration tool or by creating your own application with the administration APIs. For more information about the administration APIs. This includes the rate of inbound and outbound messages (expressed as number of messages per second). see the description of com. Overall Server Statistics The server always collects certain overall server statistics. You can configure the type of statistics collected. and you may notice that some messages have a greater message size than expected. and the number of destinations. connections. therefore these statistics are always available. the server can add a small amount of data to a message for internal use by the server. message memory usage. the interval for computing averages. The default interval for collecting overall server statistics is 1 second. The TIBCO Enterprise Message Service server tracks the number of incoming or outgoing messages. consumer. consumer. The server also sends system messages. message size. and message statistics for the server overall as well as for each producer. Statistic tracking can be set in the server’s configuration file. or route. The parameter can be set in the configuration file or dynamically using the set server command. This overhead is counted in the total message size.admin in the online documentation. and durable subscriptions. You can view overall server statistics by executing the show server command. or you can create your own application that performs more advanced analysis of statistics using the administration APIs. This parameter can only be set to positive integers greater than zero. This section details how to configure and view statistics using the configuration files and administration tool commands. and amount of detail for each type.tibco. or route are tracked. You can increase or decrease this value by altering the rate_interval parameter. To enable statistic gathering. or consumer are kept. By default. producer. Also. producers and consumers keep these statistics for each destination that they use to send or receive messages. and it can be changed dynamically using the set server command. and route can gather overall statistics and statistics for each of its destinations. destination. destination. Statistics are kept in server memory for the life of each object. you must set the statistics parameter to enabled. Detailed Statistics In some situations. consumers. disable statistic gathering. If you wish to reset the total statistics for all objects to zero. Under most circumstances. Server statistics are also reset when the server shuts down and restarts. For example. and routes consumes few system resources. route. destinations. This parameter can be specified in the configuration file. For each producer. consumer. consumer. the total statistics for all topics that match the wildcard are kept.Working with Server Statistics 361 | Enabling Statistic Gathering Each producer. and route the total number of sent/received messages and total size of messages is maintained. The statistics parameter allows you to globally enable and disable statistic gathering. then re-enable it. if a topic subscriber subscribes to wildcard topics. You may wish to get further detail in this case and track the statistics for each actual topic the subscriber receives. the average is calculated every 3 seconds. Gathering total statistics for producers. The rate of incoming/outgoing messages and message size is calculated over an interval. or in the event of a fault-tolerant failover. TIBCO Enterprise Message Service User’s Guide . This parameter can be set in the configuration file or dynamically using the set server command. Setting this parameter to 0 disables the tracking of statistics over an interval— only the total statistics for the destination. enabling statistic gathering and average calculations should not affect system performance. the default statistic gathering may not be sufficient. The parameter can have the following values: • • • • NONE — disables detailed statistic gathering. you can control the amount of time statistics are kept.bar within 15 seconds. When application programs create many dynamic destinations. PRODUCERS — enables detailed statistics for producers that do not specify a destination when they are created. statistics are kept for 15 seconds. ROUTES — enables detailed statistics for routes You can set the detailed_statistics parameter to NONE or any combination of CONSUMERS. the following set server command enables detailed statistic tracking for producers and routes. PRODUCERS. By default.bar.362 | Chapter 13 Monitoring Server Activity The following situations may require detailed statistic gathering: • • Topic subscribers that subscribe to wildcard topics Message producers that do not specify a destination when they are created. For example. set server detailed_statistics = PRODUCERS.*. or ROUTES. statistics for an object only exist as long as the object itself exists. Routes can have incoming and outgoing messages on many different topics. To specify more than one type of detailed statistic gathering.bar are deleted for that consumer. You can set this parameter to 0 to signify that all detailed statistics are to be kept indefinitely. There are two parameters that allow you to control resource consumption when collecting detailed statistics. You can set the detailed_statistics parameter in the configuration file or dynamically by using the set server command. if no new messages arrive for topic foo. and can adversely affect performance when gathering a high volume of statistics. First. provide a comma-separated list of values. statistics for topic foo. The statistics_cleanup_interval parameter controls how long detailed statistics are kept. Of course. CONSUMERS — enables detailed statistics for topic subscribers with wildcard topic names. and the destination name is specified when a message is sent. all detailed statistics for that consumer are deleted from memory. set the detailed_statistics parameter to the type of statistics you wish to receive. and the subscriber receives a message on topic foo. For example. That is. if a message consumer terminates. if there is a topic subscriber for the topic foo. These message producers can produce messages for any destination. we recommend against gathering detailed statistics. TIBCO Enterprise Message Service User’s Guide .ROUTES Collecting detailed statistics does consume memory. This parameter can be set either in the configuration file or dynamically with the set server command. • To enable detailed statistics. and second you can set a maximum amount of memory for detailed statistic gathering. 4 Kb Outbound statistics for route 'B': Total Count Destination Msgs Size <total> 9538 1.6 Kb Topic: dynamic. or any combination of criteria.9 Kb Topic: dynamic. you can specify units as KB. tcp://server1:7322> show stat route B Inbound statistics for route 'B': Total Count Destination Msgs Size <total> 189 37.Working with Server Statistics 363 | The max_stat_memory parameter controls the amount of memory used by detailed statistics. TIBCO Enterprise Message Service User’s Guide .4 Rate/Second Msgs Size 10 2.3 1907 394. You can also optionally specify the "wide" keyword when displaying statistics for destinations or routes. the server stops collecting new statistics.6 Kb Topic: dynamic.6 Kb Topic: dynamic. user name. Optionally. connection ID. By default. You can optionally specify the total keyword to retrieve only the total statistics (this suppresses the detailed output).4 2 0. This parameter can be set either in the configuration file or dynamically with the set server command. If no units are specified.5 Kb Topic: dynamic.4 2 0. you can view statistics for producers. The following illustrates displaying statistics for a route where detailed statistic tracking is enabled. The show stat command allows you to filter the statistics based on destination name.4 37 7.4 2 0. consumers.1 1908 394. or GB.4 2 0.4 2 0. This specifies that inbound and outbound message statistics should be displayed on the same line (the line can be 100 characters or more).6 Kb Topic: dynamic. if the statistics_cleanup_interval is set and old statistics are removed).5 Kb Rate/Second Msgs Size 10 2.1 2 0. MB.5 Kb Kb Kb Kb Kb Kb Kb Kb Kb Kb Kb Kb See show stat on page 145 for more information and detailed syntax of the show stat command.3 38 7.5 Kb Topic: dynamic. this parameter is set to 0 which signifies that detailed statistics have no memory limit. Displaying Statistics When statistic collecting is enabled. the value of this parameter is in bytes.0 2 0.9 Kb Topic: dynamic. routes.4 1907 394.2 38 7.0 38 7. and destinations using the show stat command in the administration tool.2 1907 394.1 38 7. The server will only resume collecting statistics if the amount of memory used decreases (for example.4 2 0.9 MB Topic: dynamic.0 1909 394.4 2 0.7 Kb Topic: dynamic.4 2 0. When the specified limit is reached. 364 | Chapter 13 Monitoring Server Activity TIBCO Enterprise Message Service User’s Guide . Most web browsers support SSL. and many Web sites and Java applications use it to obtain confidential user information. page 382 TIBCO Enterprise Message Service User’s Guide .com/eng/ssl3/. page 372 Specifying Cipher Suites. this chapter describes how to configure SSL in the TIBCO Enterprise Message Service server and in client applications that communicate with the server. page 376 Third-Party SSL Hardware Accelerators. page 369 Configuring SSL in the Server.netscape. Instead. The SSL protocol is complex. and this chapter is not a complete description of SSL. see the SSL specification at http://wp. page 371 Configuring SSL in EMS Clients. page 366 Digital Certificates. Topics • • • • • • • SSL Support in TIBCO Enterprise Message Service.| 365 Chapter 14 Using the SSL Protocol Secure Sockets Layer (SSL) is a protocol that provides secure authentication and transmits encrypted data over the Internet or an internal network. For a more complete description of SSL. such as credit card numbers. page 367 File Names for Certificates and Keys. org.366 | Chapter 14 Using the SSL Protocol SSL Support in TIBCO Enterprise Message Service TIBCO Enterprise Message Service supports the Secure Sockets Layer (SSL) protocol. The Microsoft implementation of SSL is compatible with OpenSSL. Certificates required by the client can either be stored in files or the Microsoft certificate store. you must purchase and install the Entrust SSL Version 7. if you prefer to use Entrust. EMS .NET 2. see www. EMS Java clients can use either JSSE (from Sun JavaSoft) or the SSL implementation from Entrust. For exact version numbers see Third Party Software License Agreements on page 489. The EMS Java installation includes JSSE.openssl. SSL uses public and private keys to encrypt data over a network connection to secure communication between pairs of components: • • • • Implementations between an EMS client and the tibemsd server between the tibemsadmin tool and the tibemsd server between two routed servers between two fault-tolerant servers The TIBCO Enterprise Message Service server and the C client libraries use OpenSSL for SSL support. EMS distributions usually build and include the latest versions of OpenSSL and OpenLDAP publicly available at the time of release. TIBCO Enterprise Message Service User’s Guide .0 clients use the Microsoft implementation of SSL. For more information.1 implementation separately (earlier versions are not supported). each user and server on the network requires a unique digital certificate. such as the following: • The name of the owner. an EMS client can be configured to verify the server’s certificate. most certificate authorities. The length of time the certificate will remain valid—defined by a start date and an end date. If the server is configured to verify client certificates. Though it is not necessary to validate either the server or the client for them to exchange data over SSL.509.509 version 3 (X. The public part of a digital certificate includes a variety of information. a client must have a certificate and have it verified by the server. which identifies its owner (a user or server). or by a security officer within your enterprise. the EMS server must have a digital certificate. which the owner keeps confidential. A serial number. comply with this standard. A digital certificate has two parts—a public part. A digital certificate is issued either by a trusted third-party certificate authority. TIBCO Enterprise Message Service supports digital certificates that comply with X. or an email address. TIBCO Enterprise Message Service User’s Guide .Digital Certificates 367 | Digital Certificates Digital certificates are data structures that represent identities. Similarly. and a private key. Usually. to ensure that data is sent from and received by the correct party. EMS uses certificates to verify the identities of servers and clients. and other information required to confirm the unique identity of the subject. such as Verisign and Entrust. encrypted data can be transferred over SSL between the clients and server. In order to support SSL.509v3). The subject’s public key. • • • • The most widely-used standard for digital certificates is ITU-T X. Optionally. certificates provide an additional level of security. The name of the certificate authority (CA) that issued the digital certificate. EMS clients may also be issued certificates. This information can include the URL of the web server using the digital certificate. Once the identity of the server and/or client has been verified. TIBCO Enterprise Message Service User’s Guide . DER. PKCS8 and PKCS12 formats. it does not read Java KeyStore or Entrust Store files.368 | Chapter 14 Using the SSL Protocol Digital Certificate File Formats TIBCO Enterprise Message Service supports the following file formats for digital certificates: • • • • • • PEM (Privacy Enhanced Mail) DER (Distinguished Encoding Rules) PKCS#7 PKCS#12 Java KeyStore (for client digital certificates) Entrust Store (for client digital certificates) Private Key Formats TIBCO Enterprise Message Service supports the following file formats for private keys: • • • • PEM (Privacy Enhanced Mail) DER (Distinguished Encoding Rules) PKCS#8 PKCS#12 The EMS server uses OpenSSL to read private keys. It supports PEM. Not all types of files are supported for clients and servers. private key.pem server_root.p7b .p8 • A server certificate and corresponding private keys in encrypted PEM and PKCS8 formats.p12 .cert.key.key.pem and is used by the server: server.der . EMS is installed with some sample certificates and private keys that are used by the sample configuration files.epf Certificates are located in the EMS_install_dir/certs directory. or trusted list of certificate authorities.cert. This certificate is issued by server_root. The description of each parameter details which formats it supports.File Names for Certificates and Keys 369 | File Names for Certificates and Keys For all parameters that specify the identity (digital certificate).key.key.cert.p8 .p8 TIBCO Enterprise Message Service User’s Guide .pem Description PEM encoded certificates and keys (allows the certificate and private key to be stored together in the same file) DER encoded certificates PKCS#8 file PKCS#7 file PKCS12 file (allows the certificate and private key to be stored together in the same file) Java KeyStore file Entrust store file . issuer (certificate chain). Table 63 File types Extension .jks . Table 63 lists the valid types of files.pem server.pem server. The sample certificates include: • A root. valid files must be specified.pem server_root. self-signed certificate and corresponding private keys in encrypted PEM and PKCS8 formats: server_root. cert.p8 • A PKCS12 file that includes the client.key.370 | Chapter 14 Using the SSL Protocol • A root.key.cert.pem issuer certificate: client_identity.key.pem and is used by the clients: client.pem client_root. This certificate is issued by client_root.pem client private key.pem client_root.cert. the client.cert.key.cert.pem client.key. self-signed certificate and corresponding private key in encrypted PEM and PKCS8 formats.pem client certificate.p8 • A client certificate and corresponding private key in encrypted PEM and PKCS8 formats. client_root.pem client.p12 TIBCO Enterprise Message Service User’s Guide . and the client_root. conf. then you must specify it in ssl_server_key. For more information. specify the SSL protocol in the listen parameter as follows: listen = ssl://localhost:7243 SSL Parameters Several SSL parameters can be set in tibemsd. -ssl_password—specifies the private key password.Configuring SSL in the Server 371 | Configuring SSL in the Server To use SSL. To specify that a port accept SSL connections. see the description of the ssl_password configuration parameter. When starting tibemsd. The server can optionally require a certificate chain or trusted certificates. If you do not supply a password using either of these methods. Command Line Options The server accepts a few command-line options for SSL.conf. you can specify the following options: • • • -ssl_trace—enables tracing of loaded certificates. you can specify this password in the ssl_server_password parameter in tibemsd. Set the server to listen for SSL connections from clients by using the listen parameter in tibemsd. SSL Server Parameters on page 188 provides a complete description of the SSL parameters that can be set in tibemsd.conf. The minimum configuration is only one required parameter—ssl_server_identity. each instance of tibemsd must have a digital certificate and a private key. Alternatively.conf. if the server’s certificate file does not contain its private key. it is not for use in production systems. -ssl_debug_trace—enables more detailed SSL tracing for debugging only. However. This prints a message to the console during startup of the server that describes each loaded certificate. tibemsd will prompt for the password when it starts. TIBCO Enterprise Message Service User’s Guide . 1 libraries. you must include them in the CLASSPATH before the JSSE JAR files. Table 64 SSL JAR Files JAR File jsse. a Java client must include appropriate JAR files in the CLASSPATH (see Table 64 below).1 with JDK.4 and later). These files are included with EMS. If this is the case.372 | Chapter 14 Using the SSL Protocol Configuring SSL in EMS Clients To use an SSL connection to the EMS server.conf). To use Entrust Version 7. the client may combine its client certificate and private key in a single file in one of the following formats: • • • PKCS#12 Java KeyStore Entrust Store You can also store the private key file separately from the client certificate file.jar tibcrypt.jar Included with JDK JDK JDK EMS To use Entrust with an EMS client. you must separately purchase and install the Entrust Version 7. see Entrust Version 7. If you use the Entrust libraries. and also with JDK (1.1 documentation. Client Digital Certificates When client authentication with a digital certificate is required by the EMS server (see the description of the ssl_require_client_cert parameter in tibemsd.jar jnet.jar jcert. the certificate and private key must be stored in one of the following formats: • • PEM PKCS#8 TIBCO Enterprise Message Service User’s Guide . For installation and configuration details. you must download the unlimited strength policy JAR files from Sun's website and install them in your local installation of JDK. See Chapter 6. as described in Dynamically Creating Connection Factories and set the global SSL parameters locally using the TibjmsSSL class (Java). JSSE and Entrust support different formats and combinations of formats. If the files do not match the supported types or the files are not found. the JNDI lookup fails with a ConfigurationException. TIBCO Enterprise Message Service User’s Guide . Specifying any SSL parameters within a connection factory causes all global SSL parameters set with the TibjmsSSL class to be ignored.conf. you can specify several SSL parameters. tibemsSSLParams type (C). At the time the factory is retrieved using JNDI. When configuring a connection factory. on page 101.Configuring SSL in EMS Clients 373 | The format of the client digital certificate and private key file depends on the SSL vendor used by the client. Configuring SSL A client connecting to an EMS server can configure SSL characteristics in the following ways: • Create a connection factory that specifies the appropriate SSL parameters and use JNDI to lookup the connection factory. See Creating Connection Factories for Secure Connections and Performing Secure Lookups for details on how to create a connection factory with SSL parameters in EMS. the EMS server attempts to resolve any file references. The server URL in the connection factory must specify the SSL protocol. or EMSSSL class (C#). Using the EMS Administration Tool. These parameters are similar to the server parameters that you can configure in tibemsd. see your SSL vendor’s documentation. • Dynamically create a connection factory. A preconfigured connection factory is the preferred mechanism in many situations. When configuring a connection factory. Configuring a Connection Factory You can configure a connection factory using the administration tool or the EMS Administration APIs. For more information about formats. EMS does not verify any file names specified in the SSL parameters. and the factory must specify appropriate SSL parameters. see File Names for Certificates and Keys on page 369. see File Names for Certificates and Keys on page 369. For more information on file types for digital certificates. When disabled. see File Names for Certificates and Keys on page 369.pem ssl_issuer = certs\CA_child1.pem For more information on file types for digital certificates. the client establishes secure communication with the server. Supply the entire chain. For more information on file types for digital certificates. Example ssl_issuer = certs\CA_root. By default. including the CA root certificate. For more information on file types for digital certificates. The client reads the certificates in the chain in the order they are presented in this parameter. TIBCO Enterprise Message Service User’s Guide . The values for this parameter are enabled or disabled. ssl_trusted List of CA certificates to trust as issuers of server certificates. see File Names for Certificates and Keys on page 369. see the description of the equivalent parameter in tibemsd. The client’s digital certificate. this parameter is enabled.conf on page 157. For more information about each parameter. Supply only CA root certificates. then you may omit this parameter. signifying the client should verify the server’s certificate. ssl_private_key The client’s private key. If the key is included in the digital certificate in ssl_identity.pem ssl_issuer = certs\CA_child2. ssl_verify_host Specifies whether the client should verify the server’s certificate. ssl_issuer Issuer’s certificate chain for the client’s certificate. but does not verify the server’s identity.374 | Chapter 14 Using the SSL Protocol Table 65 briefly describes the parameters you can set in a connection factory. Table 65 ConnectionFactory SSL parameters (Sheet 1 of 2) Parameter ssl_vendor ssl_identity Description The vendor name of the SSL implementation that the client uses. and refers to additional information about each parameter. For more information. if one is installed. This daemon generates random data for the client. the client establishes secure communication with the server. The values for this parameter are enabled and disabled.Configuring SSL in EMS Clients 375 | Table 65 ConnectionFactory SSL parameters (Sheet 2 of 2) Parameter ssl_verify_hostname Description Specifies whether the client should verify the name in the CN field of the server’s certificate. but does not verify the server’s name. the expected name is the hostname of the server. signifying the client should verify the name of the connected host or the name specified in the ssl_expected_hostname parameter against the value in the server’s certificate. ssl_ciphers Specifies the cipher suites that the client can use. ssl_expected_hostname The name the client expects in the CN field of the server’s certificate. see Specifying Cipher Suites on page 376. By default. or longer descriptive names. Names may be either OpenSSL names. TIBCO Enterprise Message Service User’s Guide . When disabled. Supply a colon-separated list of cipher names. ssl_rand_egd The path for the entropy gathering daemon (EGD). If this parameter is not set. The value of this parameter is used when the ssl_verify_hostname parameter is enabled. this parameter is enabled. If the names do not match. the client rejects the connection. see Configuring SSL in EMS Clients on page 372. So. + to add the suite) followed by the cipher suite name. if you use -ALL. otherwise the SSL connection fails to initialize. For more information. Using the Configuration Files. Move the cipher to the end of the list. Syntax for Cipher Suites EMS uses OpenSSL for SSL support. For more information about server configuration files.376 | Chapter 14 Using the SSL Protocol Specifying Cipher Suites On the EMS server. on page 155. Therefore.conf. At least one cipher suite must be present. you can use spaces and commas to separate names. Move the cipher to the beginning of the list. the usual way to specify more than one cipher suite is to separate each suite name with a colon (:) character. Alternatively. You can use this keyword to add or remove all ciphers. For Java clients. TIBCO Enterprise Message Service User’s Guide . you must subsequently add the desired ciphers to the list. the cipher suite names can be specified as the OpenSSL name for the cipher suite. specify cipher suites using the ssl_ciphers connection factory parameter. Java Client Syntax The syntax for specifying the list of cipher suites is different for Java clients than for any other location where cipher suites can be specified. Table 66 Qualifiers for Cipher Suites in Java Clients Qualifier + > < ALL Description Add the cipher to the list of ciphers. For clients connecting with a connection factory. Table 66 describes the qualifiers you can use when specifying cipher suite names in a ConnectionFactory for Java clients. see Chapter 7. All ciphers from the list (except null ciphers). you specify a qualifier (for example. specify cipher suites using the ssl_server_ciphers configuration parameter in tibemsd. Cipher suite names are case-sensitive. Remove the cipher from the list of ciphers. When specifying cipher suites. Specifying Cipher Suites 377 | This example specifies cipher suites in the ssl_ciphers connection factory parameter in a Java client: -ALL:+RC4-MD5:+DES-CBC-SHA:<DES-CBC3-SHA Syntax for All Other Cipher Suite Specifications For any cipher suite list that is not specified in a connection factory of a Java client. ssl_server_ciphers = -ALL:RC4-MD5:DES-CBC-SHA:DES-CBC3-SHA This example illustrates disables RC4-MD5. specifying a cipher suite name adds that cipher suite to the list. then adds all other ciphers: ssl_server_ciphers = !RC4-MD5:ALL TIBCO Enterprise Message Service User’s Guide . At least one cipher suite must be present or the SSL connection fails to initialize. Cipher suite names are case-sensitive. Permanently disable the cipher within the list of ciphers. So. use the OpenSSL syntax. Use this option if you wish to remove a cipher and you do not want later items in the list to add the cipher to the list. and add the ciphers that follow it. the cipher can be added later on in the list of ciphers. after using -ALL. In particular. When this option is used. Table 67 describes the qualifiers available using OpenSSL syntax. All ciphers from the list (except null ciphers). C clients and the ssl_server_ciphers configuration parameter require OpenSSL syntax. You can use this keyword to add or remove all ciphers. you should add at least one cipher to the list. Each cipher suite name can be preceded by a qualifier. ! ALL @STRENGTH Sort the cipher list by key length. This qualifier takes precedence over all other qualifiers. This example specifies cipher suites in the ssl_server_ciphers configuration parameter. In OpenSSL syntax. Remove the cipher from the list of ciphers. Table 67 OpenSSL Qualifiers for Cipher Suites Qualifier / + - Description Start with an empty list. Moves the cipher to the end of the list. Table 68 Supported Cipher Suites in Java API (Sheet 1 of 3) Suite Name (OpenSSL Name) SSL_RSA_WITH_RC4_128_MD5 (RC4-MD5) RSA SSL_RSA_WITH_RC4_128_SHA (RC4-SHA) RSA SSL_RSA_WITH_DES_CBC_SHA (DES-CBC-SHA) RSA SSL_RSA_WITH_3DES_EDE_CBC_SHA (DES-CBC3-SHA) RSA SSL_RSA_EXPORT_WITH_RC4_40_MD5 (EXP-RC4-MD5) Yes SSL_RSA_EXPORT_WITH_DES_40_CBC_SHA (EXP-DES-CBC-SHA) Yes RSA(512) RSA DES 40 SHA1 RSA(512) RSA RC4 40 MD5 RSA 3-DES 168 SHA1 RSA DES 56 SHA1 RSA RC4 128 SHA1 RSA RC4 128 MD5 Export Key Exch Auth Encrypt Key Size MAC TIBCO Enterprise Message Service User’s Guide . For a complete list. Supported Cipher Suites In general. For convenience. see current OpenSSL documentation. RC-5 and CAST. Java clients support only the cipher suites listed in Table 68. which is equivalent to ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH. except IDEA.378 | Chapter 14 Using the SSL Protocol Default Cipher List The EMS server and C client library hard-code a default cipher list. the EMS server and C client library support all cipher suites that OpenSSL supports. the table lists both the standard name and the OpenSSL name for each cipher suite. Specifying Cipher Suites 379 | Table 68 Supported Cipher Suites in Java API (Sheet 2 of 3) Suite Name (OpenSSL Name) Export Key Exch Auth Encrypt Key Size MAC SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA (EDH-DSS-DES-CBC3-SHA) DH SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA (EDH-RSA-DES-CBC3-SHA) DH SSL_DHE_DSS_WITH_DES_CBC_SHA (EDH-DSS-DES-CBC-SHA) DH SSL_DHE_RSA_WITH_DES_CBC_SHA (EDH-RSA-DES-CBC-SHA) DH SSL_DHE_DSS_EXPORT_WITH_DES_40_CBC_SHA (EXP-EDH-DSS-DES-CBC-SHA) Yes DH(512) DSS DES 40 SHA1 RSA DES 56 SHA1 DSS DES 56 SHA1 RSA 3-DES 168 SHA1 DSS 3-DES 168 SHA1 SSL_DHE_RSA_EXPORT_WITH_DES_40_CBC_SHA (EXP-EDH-RSA-DES-CBC-SHA) Yes TLS_RSA_WITH_AES_128_CBC_SHA (AES128-SHA) RSA TLS_RSA_WITH_AES_256_CBC_SHA (AES256-SHA) RSA RSA AES 256 SHA1 RSA AES 128 SHA1 DH(512) RSA DES 40 SHA1 TIBCO Enterprise Message Service User’s Guide . Entrust does not support this suite.380 | Chapter 14 Using the SSL Protocol Table 68 Supported Cipher Suites in Java API (Sheet 3 of 3) Suite Name (OpenSSL Name) Export Key Exch Auth Encrypt Key Size MAC TLS_DHE_DSS_WITH_AES_128_CBC_SHA (DHE-DSS-AES128-SHA) DH TLS_DHE_DSS_WITH_AES_256_CBC_SHA (DHE-DSS-AES256-SHA) DH TLS_DHE_RSA_WITH_AES_128_CBC_SHA (DHE-RSA-AES128-SHA) DH TLS_DHE_RSA_WITH_AES_256_CBC_SHA (DHE-RSA-AES256-SHA) DH SSL_RSA_WITH_NULL_MD5 (NULL-MD5) JSSE only. Entrust does not support this suite. DH SSL_RSA_WITH_NULL_SHA (NULL-SHA) JSSE only. DH RSA none — SHA1 RSA none — MD5 RSA AES 256 SHA1 RSA AES 128 SHA1 DSS AES 256 SHA1 DSS AES 128 SHA1 TIBCO Enterprise Message Service User’s Guide . or by calling: — Java: TibemsSSL. using ordinary TCP communications for subsequent data exchange. EMS behavior reverts to using SSL for all communications throughout the life of the connection.SSL Authentication Only 381 | SSL Authentication Only EMS servers can use SSL for secure data exchange (standard usage). Preconditions All three of these preconditions must be satisfied to use SSL only for authentication: • The server and clients must both be release 4. In this situation. or only for client authentication. decreasing message speed and throughput. clients can specify this request in factories by enabling the ssl_auth_only parameter. and then avoid SSL calls thereafter.2 or later. This section describes the use of SSL for client authentication. The client program must request a connection that uses SSL for authentication only. the preferred solution is to use SSL only to authenticate clients. Motivation Some applications require strong or encrypted authentication. this solution incurs internal overhead costs of SSL calls. However.) The server must explicitly enable the parameter ssl_auth_only in the tibemsd. Message performance remains unaffected. For optimal performance. (If not.SetAuthOnly • • See Also ssl_auth_only on page 192 TIBCO Enterprise Message Service User’s Guide .setAuthOnly — C: tibemsSSLParams_SetAuthOnly — C#: EMSSSL. but do not require message encryption.conf configuration file. application architects could configure SSL with a null cipher. 1.0 and are no longer supported. release 4. TIBCO Enterprise Message Service User’s Guide .382 | Chapter 14 Using the SSL Protocol Third-Party SSL Hardware Accelerators SSL accelerators were deprecated in TIBCO Enterprise Message Service. | 383 Chapter 15 Fault Tolerance This chapter describes the fault tolerance features of TIBCO Enterprise Message Service. page 395 Configuring Clients for Fault-Tolerant Connections. page 391 Configuring Fault-Tolerant Servers. page 384 Failover. Topics • • • • • Fault Tolerance Overview. page 397 TIBCO Enterprise Message Service User’s Guide . page 386 Shared State. 384 | Chapter 15 Fault Tolerance Fault Tolerance Overview You can arrange TIBCO Enterprise Message Service servers for fault-tolerant operation by configuring a pair of servers—one primary and one backup. TIBCO Enterprise Message Service User’s Guide . The primary server accepts client connections.) Shared State A pair of fault-tolerant servers must have access to shared state. (We do not support more than two servers in a fault-tolerant configuration. If the primary server fails. Figure 21 illustrates a fault-tolerant configuration of TIBCO Enterprise Message Service. the lock is released. Figure 21 Primary Server and Backup Server Fault-Tolerant Clients Primary Server lo c k Shared State Backup Server Locking To prevent the backup server from assuming the role of the primary server. which consists of information about client connections and persistent messages. This information enables the backup server to properly assume responsibility for those connections and messages. and the backup server can obtain the lock. the backup server resumes operation in its place. and interacts with clients to deliver messages. If the primary server fails. the primary server locks the shared state during normal operation. unintended misconfiguration can result. then administrative changes to the old primary carry over to the new primary. you must limit configuration changes to the current primary server only. its backup server assumes the status of the primary server and resumes operation. Before becoming the new primary server. the backup server re-reads all of its configuration files. When fault-tolerant servers share configuration files. If the two servers share configuration files. TIBCO Enterprise Message Service User’s Guide . Separately reconfiguring the backup server can cause it to overwrite the shared configuration files.Fault Tolerance Overview 385 | Configuration Files When a primary server fails. When B can access this information. Figure 22 Failed Primary Server Fault-Tolerant Clients Failed A Failed Server Shared State ck Lo B Primary Server TIBCO Enterprise Message Service User’s Guide . see Heartbeat Parameters on page 390. Detection A backup server detects a failure of the primary in either of two ways: • Heartbeat Failure—The primary server sends heartbeat messages to the backup server to indicate that it is still operating. When the primary process terminates unexpectedly. the backup server detects the interruption in the steady stream of heartbeats. B obtains the lock on the current shared state. the backup server detects the broken connection.386 | Chapter 15 Fault Tolerance Failover This section presents details of the failover sequence. it becomes the new primary server. then B attempts to assume the role of primary server. • Response When a backup server (B) detects the failure of the primary server (A). For details. First. When a network failure stops the servers from communicating with each other. Connection Failure—The backup server can detect the failure of its TCP connection with the primary server. ft. A can restart as a backup server. see the class com. C client programs call tibems_setExceptionOnFTSwitch(TIBEMS_TRUE) and register the exception callback in order to receive the notification that the reconnection was successful.tibjms. TIBCO Enterprise Message Service User’s Guide . and define an ExceptionListener to handle failover notification. Client Notification Client applications can receive notification when failover occurs. B reads the client’s current state from the shared storage to deliver any persistent messages to the client. Java To receive notification.Failover 387 | Role Reversal When B becomes the new primary server.exception to any value.tibco. Java client programs set the system property tibco. Figure 23 Recovered Server Becomes Backup Fault-Tolerant Clients Recovered A Backup Server Shared State ck Lo B Primary Server Client Transfer Clients of A that are configured to failover to backup server B automatically transfer to B when it becomes the new primary server. C To receive notification.Tibjms in TIBCO Enterprise Message Service Java API Reference. so that the two servers exchange roles.switch.tibjms. .SetExceptionOnFTSwitch(true). TIBCO Enterprise Message Service User’s Guide .NET API Reference. and define an exception listener to handle failover notification. see the method Tibems.SetExceptionOnFTSwitch on page 294 in TIBCO Enterprise Message Service . it alternates between attempting to obtain the lock (and become the primary server).388 | Chapter 15 Fault Tolerance C# To receive notification. Lock Unavailable If B cannot obtain the lock immediately.NET client programs call Tibems. and attempting to reconnect to A (and resume as a backup server)—until one of these attempts succeeds. When a queue receiver catches a javax. EMS guarantees that a message with PERSISTENT delivery mode and a failsafe destination will not be lost during a failure. messages with delivery mode PERSISTENT.jms. are redelivered. any messages that have been sent to receivers.Failover 389 | Message Redelivery Persistent When a failure occurs. This exception cannot occur if there is only one receiver at the time of a failover. but have not been acknowledged before the failover. Acknowledged messages are never redelivered (in compliance with the JMS specification). A receiver trying to acknowledge a message after a failover may receive the javax.1 specification. the best course of action is to call the Session. application programs must check this header to avoid duplicate processing of the same message in the case of redelivery. The case described above occurs when the application cannot acknowledge a message because of a failover. Your application program should also be prepared to handle redelivery of messages in this situation. may be sent to other receivers immediately after the failover.recover() method. All topic subscribers continue normal operation after a failover.IllegalStateException. All queue messages that can be redelivered to another queue receiver after a failover always have the header field JMSRedelivered set to true. Any messages that have been successfully acknowledged or committed are not redelivered.IllegalStateException. or when the session or connection have been closed. This exception only occurs in this scenario. but it may occur for exclusive queues if more than one receiver was started for that queue. that were not successfully acknowledged before the failure. in compliance with the JMS 1. TIBCO Enterprise Message Service User’s Guide . This exception signifies that the attempted acknowledgement is for a message that has already been sent to another queue receiver. When using durable subscribers.jms. Failsafe Delivery Succeeded Topics Queues For queue receivers. After a failover. attempting to commit the active transaction results in a javax. TIBCO Enterprise Message Service User’s Guide . The backup server automatically redelivers any messages that were delivered to the session during the transaction that rolled back.TransactionRolledBackException. the backup server waits for its activation interval (elapsed time since it detected the most recent heartbeat). Clients that use transactions must handle this exception.jms. See Fault Tolerance Parameters on page 178 for details. Both intervals are specified in seconds.390 | Chapter 15 Fault Tolerance Transactions A transaction is considered active when at least one message has been sent or received by the session. and resend any messages sent during the transaction. The default heartbeat interval is 3 seconds. and the default activation interval is 10 seconds. The activation interval must be at least twice the heartbeat interval. and the transaction has not been successfully committed. then the backup server retrieves information from shared storage and assumes the role of primary server. You can set these intervals in the server configuration files. Heartbeat Parameters When the primary server heartbeat stops. Shared State 391 | Shared State The primary server and backup server must share the same state. Support Criteria Several options are available for implementing shared storage using a combination of hardware and software. the storage solution guarantees that all the data have been written to durable. to enhance disk efficiency) do not satisfy this requirement. Server state includes three categories of information: • • • persistent message data (for queues and topics) client connections of the primary server metadata about message delivery During a failover. Always consult your shared storage vendor and your operating system vendor to ascertain that the storage solution you select satisfies all four criteria.) Synchronous Write Persistence Upon return from a synchronous write call. persistent storage. TIBCO Enterprise Message Service User’s Guide . Implementing Shared State We recommend that you implement shared state using shared storage devices. (Solutions that write data blocks in any other order (for example. EMS requires that your storage solution guarantees all four criteria in Table 69. The shared state must be accessible to both the primary and backup servers. Table 69 Shared Storage Criteria for Fault Tolerance (Sheet 1 of 2) Criterion Write Order Description The storage solution must write data blocks to shared storage in the same order as they occur in the data buffer. the backup server re-reads all shared state information. NAS TIBCO Enterprise Message Service User’s Guide . pending writes queued by the previous owner must fail. Hardware Options Consider these examples of commonly-sold hardware options for shared storage: • • • SCSI and SAN Dual-Port SCSI device Storage Area Network (SAN) Network Attached Storage (NAS) Dual-port SCSI and SAN solutions generally satisfy the Write Order and Synchronous Write Persistence criteria. and some do not. (The clustering software must satisfy the remaining two criteria. The storage solution must not assign the locks to two servers simultaneously. (See Software Options on page 393. you must confirm all four requirements with your vendors.) As always. Some NAS solutions satisfy the criteria.392 | Chapter 15 Fault Tolerance Table 69 Shared Storage Criteria for Fault Tolerance (Sheet 2 of 2) Criterion Distributed File Locking Description The EMS servers must be able to request and obtain an exclusive lock on the shared storage. Unique Write Ownership The EMS server process that has the file lock must be the only server process that can write to the file.) EMS servers use this lock to determine the primary server. Once the system transfers the lock to another server. you must confirm all four requirements with your vendors. NAS solutions require a CS (rather than a CFS) to satisfy the Distributed File Locking criterion (see below). the CFS assigns the lock to only one server process at a time. NFS v3 with TCP might satisfy the criteria. Consult with the operating system vendor to verify that the NFS client (in the OS on the server host computer) satisfies the criteria. it starts the backup server instead. For more information on how the EMS locks shared store files. Of course. the CS restarts it. you must confirm all four requirements with your vendors. • Clustered File System (CFS) A clustered file system lets the two EMS server processes run simultaneously. and ensures that exactly one server process is running at all times. see How EMS Manages Access to Shared Store Files on page 98. if it fails to restart the primary. However. With NAS hardware. With dual-port SCSI or SAN hardware. it is particularly difficult to determine whether the solution meets the criteria. either a CS or a CFS might satisfy the Distributed File Locking criterion. It even lets both servers mount the shared file system simultaneously. so the backup server has an up-to-date view of the file system (instead of a stale cache). Consult with the NAS vendor to verify that the NFS server (in the NAS) satisfies the criteria. Software Options Consider these examples of commonly-sold software options: • Cluster Server (CS) A cluster server monitors the EMS server processes and their host computers. NFS v3 with UDP definitely does not satisfy the criteria. TIBCO Enterprise Message Service User’s Guide . Our research indicates the following conclusions: • • • NFS v2 definitely does not satisfy the criteria. The CFS also manages operating system caching of file data.Shared State 393 | NAS with NFS When NAS hardware uses NFS as its file system. then the shared storage solution supports EMS. If the primary server fails. When both vendors certify that their components cooperate to guarantee the criteria. only a CS can satisfy this criterion (CFS software generally does not). then the server stores its messages in this file (using synchronous I/O calls). TIBCO Enterprise Message Service User’s Guide . and other metadata. fault-tolerant connections. When a queue or topic definition (in a configuration file) does not specify that the destination is failsafe. Table 70 Shared State Files File Name meta. Using the Configuration Files. see How EMS Manages Access to Shared Store Files on page 98. see Storage File Parameters on page 173. see Chapter 7. For more information about configuration files.db async-msgs. For more information on how the EMS manages shared store files. on page 155. see Message Redelivery on page 389. each server restricts access to its store file for the duration of the server process. Storage Files The tibemsd server creates three files to store shared state. When a queue or topic definition (in a configuration file) specifies that the destination is failsafe.db Description This file records durable subscribers. Messages with NON_PERSISTENT delivery mode are not available if the primary server fails.394 | Chapter 15 Fault Tolerance Messages Stored in Shared State Messages with PERSISTENT delivery mode are stored. and are available in the event of primary server failure. then the server stores its messages in this file (using asynchronous I/O calls). see failsafe on page 47. For more information about the failsafe destination property. Storage Parameters Several configuration parameters apply to EMS storage files (even when fault-tolerant operation is not configured).db To prevent two servers from using the same store file. sync-msgs. For more information about recovery of messages during failover. While the backup server is in standby mode. The user name and password in the users.conf file for each server must match the values of the server and password parameters in the tibemsd. set these parameters in its main configuration file (or on the server command line): • • server Set this parameter to the same server name in the configuration files of both the primary server and the backup server. set this parameter to the URL of the primary server.conf file. If authorization is enabled and the two EMS Servers are configured for fault tolerance. When the backup server starts. • If the two EMS Servers are not sharing a users. To administer the backup server. then the backup server enters standby mode. ft_active In the configuration file of the primary server. it does not accept connections from clients. then the backup server assumes the role of the primary server (in active mode).conf file for each server must have the same server name and password (the server and password parameters must be the same on each server). it attempts to connect to the primary server. set this parameter to the URL of the backup server. If it establishes a connection to the primary. Authorization and Fault-Tolerant Servers EMS authorization interacts with fault tolerance. make sure that you create a user with the same name as the EMS Server. then both servers in a fault-tolerant pair must be configured as follows: • The tibemsd.Configuring Fault-Tolerant Servers 395 | Configuring Fault-Tolerant Servers To configure an EMS server as a fault-tolerant backup.conf file. If it cannot establish a connection to the primary. TIBCO Enterprise Message Service User’s Guide . the admin user can connect to it using the administration tool. In the configuration file of the backup server. and set the user's password with the value of the "server" password. " To set the user names and passwords. see Fault Tolerance Parameters on page 178. The ft_reconnect_timeout time starts once the server has fully recovered the shared state. start the EMS Administration Tool on each server. enter: set server password=mySecret create user EMS-SERVER password=mySecret From the backup (Server 2). You can instruct the server to clean up state information for clients that do not reconnect before the time limit specified by the ft_reconnect_timeout configuration parameter. as described in Using the EMS Administration Tool on page 101. Before accepting reconnects from the clients. so this value does not account for the time it takes to recover the store files. See ft_reconnect_timeout on page 178 for details. You must configure these parameters for both servers in the pair. TIBCO Enterprise Message Service User’s Guide . Using the SSL Protocol.conf) affect this behavior. enter: set server authorization=enabled From the backup (Server 2). From the active (Server 1). on page 365 Reconnect Timeout When a backup server assumes the role of the primary server during failover. the backup server reads its message state from the shared state files. See Also Chapter 14. and do the following. The relevant parameters all begin with the prefix ft_ssl.396 | Chapter 15 Fault Tolerance For example. the new primary) and continue processing their current message state. enter: set server password=mySecret create user EMS-SERVER password=mySecret From the active (Server 1). Parameters in the main configuration file (tibemsd. you have two EMS Servers (Server 1 and Server 2) that are named "EMS-SERVER" and are to use a password of "mySecret. enter: set server authorization=enabled SSL You can use SSL to secure communication between a pair of fault-tolerant servers. clients attempt to reconnect to the backup server (that is. The reconnection logic in the client is triggered by the specifying multiple URLs when connecting to a server. To enable a client to reconnect. the attempts wrap to the start of the list (so each URL is tried). the client tries the next URL in the list. The client attempts to connect to each URL in the order listed. The client tries the URLs in sequence until all URLs have been tried. the new primary). the connection fails.Configuring Clients for Fault-Tolerant Connections 397 | Configuring Clients for Fault-Tolerant Connections When a backup server assumes the role of the primary server during failover. If the first failed connection was not the first URL in the list. at a different network interface). to identify the first server as tcp://server0:7222. clients can specify more than two URLs for the connection. In another example. if each server has more than one listen address. and the second server as tcp://server1:7344 (if first server is not available). see Performing Fault-Tolerant Lookups on page 297. TIBCO Enterprise Message Service User’s Guide . clients attempt to reconnect to the backup server (that is. the client must still provide at least two URLs (typically pointing to the same server) in order for it to automatically reconnect to the server when it becomes available after a failure. For example. Specify multiple servers as a comma-separated list of URLs. If no backup server is present. a client can reconnect to the same server at a different address (that is. Both URLs must use the same protocol (either tcp or ssl). Specifying More Than Two URLs Even though there are only two servers (the primary and backup servers). If none of the attempts succeed. clients can configure to failover to parallel remote servers for catastrophe recovery. tcp://server1:7344 For information on how to lookup a fault-tolerance URL in the EMS naming service. you must specify the URLs of both servers when creating a connection. you can specify: serverUrl = tcp://server0:7222. If a connection to one URL fails. For example. You can modify these settings in the factories. and setReconnAttemptTimeout() methods to establish new reconnection failure parameters: setReconnAttemptDelay(). The reason for having separate connect and reconnect attempt parameters is that there is a limit imposed by the operating system to the number of connection attempts the EMS server can handle at any particular time.398 | Chapter 15 Fault Tolerance Setting Reconnection Failure Parameters EMS allows you to establish separate parameters for initial connection attempts and reconnection attempts.setReconnAttemptCount(10).conf file or by means of your client connection factory API. When the number of connections is large. each connect attempt is distributed so it is less likely for the server to exceed its maximum accept queue. (For example. However. during a fault-tolerant switchover. This section describes the parameters you can establish for reconnection attempts following a fault-tolerant switchover. TIBCO Enterprise Message Service User’s Guide .setReconnAttemptTimeout(1000).) Under normal circumstances. By default. Java Use the TibjmsConnectionFactory object’s setReconnAttemptCount(). all of the clients automatically try to reconnect to the backup server at approximately the same time. The following examples establish a reconnection count of 10. it may require more time for each client to reconnect than for the initial connect.setReconnAttemptDelay(1000). this limit is adjusted by the ulimit setting. factory. factory. How to set the initial connection attempt parameters is described in Setting Connection Attempts. in Unix. a delay of 1000 ms and a timeout of 1000 ms. as demonstrated by the examples in this section. Timeout and Delay Parameters on page 260. factory. a client will attempt reconnection 4 times with a 500 ms delay between each attempt. and ConnectionFactory. 10).setReconnAttemptDelay(1000).setReconnAttemptCount(10). C# Use the ConnectionFactory. factory. 1000). tibemsConnectionFactory_SetReconnectAttemptDelay. ConnectionFactory. TIBCO Enterprise Message Service User’s Guide . factory.SetReconnAttemptCount.setReconnAttemptTimeout(1000).Configuring Clients for Fault-Tolerant Connections 399 | C Use the tibemsConnectionFactory_SetReconnectAttemptCount.SetReconnAttemptDelay. and tibemsConnectionFactory_SetReconnectAttemptTimeout functions to establish new reconnection failure parameters: status = tibemsConnectionFactory_SetReconnectAttemptCount( factory.SetReconnAttemptTimeout methods to establish new reconnection failure parameters: factory. 1000). status = tibemsConnectionFactory_SetReconnectAttemptTimeout( factory. status = tibemsConnectionFactory_SetReconnectAttemptDelay( factory. 400 | Chapter 15 Fault Tolerance TIBCO Enterprise Message Service User’s Guide . page 422 TIBCO Enterprise Message Service User’s Guide . page 406 Active and Passive Routes.| 401 Chapter 16 Working With Routes This chapter describes routing of messages among TIBCO Enterprise Message Service servers. Topics • • • • • • • • Overview of Routing. page 409 Configuring Routes and Zones. page 403 Zone. page 415 Routed Queues. page 420 Routing and Authorization. page 410 Routed Topic Messages. page 402 Route. TIBCO Enterprise Message Service User’s Guide . or administration APIs). tibemsadmin. configuration files.402 | Chapter 16 Working With Routes Overview of Routing TIBCO Enterprise Message Service servers can route messages to other servers. You can define routes using an administrative interface (that is. Queue messages can travel only one hop to the home queue. • • Topic messages can travel one hop or multiple hops (from the first server). and one hop from the home queue. Figure 24 Routes: bidirectionality and corresponding destinations Server: A Route Server: B Server: A Queue: Q1 Server: B Queue: Q1@A Topic: T1 Topic: T1 Topic: T2 TIBCO Enterprise Message Service User’s Guide . The route does not forward messages from T2. In addition. the compact view at the top of Figure 24 denotes a route between two servers. global topics with the same name. Each server has a global topic named T1. server A has a global topic T2.Route 403 | Route Basic Operation • • Each route connects two TIBCO Enterprise Message Service servers. these destinations correspond. each server in the pair forwards messages along the route to the other server. so the route forwards messages between them. Each route forwards messages between corresponding destinations (that is. or explicitly routed queues) on its two servers. which does not correspond to any topic on server B. and a routed queue Q1. The exploded view beneath it illustrates the behavior of the route. • For example. Routes are bidirectional. that is. A and B. neither C nor D forward T2 messages to one another. (For more information about destination properties. However.) Figure 25 illustrates a route between two servers. see Routed Queues on page 420). so both servers forward messages across the route to the corresponding destination. This rule overrides the inherent bidirectionality of routes. See Destination Properties on page 46. with corresponding destinations T1 and T2. C and D. T2 is not global on C. Figure 25 Routes: global destinations Server: C T1 global Server: D T1 global T2 global T2 TIBCO Enterprise Message Service User’s Guide .404 | Chapter 16 Working With Routes Global Destinations Routes forward messages only between global destinations—that is. Notice that T1 is global on both C and D. for topics the global property must be set on both servers (for queues. see Zone on page 406. B. the routes connecting servers A. Figure 26 on page 405 depicts two sets of routes. The graph contains redundant routing paths between servers Q and S (one direct. the routing configuration on the right is illegal in a multi-hop zone. and one through R and T). TIBCO Enterprise Message Service servers detect illegal duplicate routes and report them as configuration errors. Note that the configuration on the right is illegal only in a multi-hop zone. this configuration is legal (in any zone). it is legal in a one-hop zone. On the left. with only one route connecting any pair of servers. For further information.Route 405 | Unique Routing Path It is illegal to define a set of routes that permit a message to reach a server by more than one path. D and E form an acyclic graph. Figure 26 Routes: Unique Path Legal A B C Illegal (in a multi-hop zone) P Q R D E S T TIBCO Enterprise Message Service User’s Guide . C. In contrast. 406 | Chapter 16 Zone Working With Routes Zones restrict the behavior of routes. Z1. the servers forward the message to A. If a client sends a message to a global topic on server B. Figure 27 depicts a set of servers connected by routes within a multi-hop zone. Queue messages travel only one hop. D and E. even within multi-hop zones. Basic Operation A zone is a named set of routes. For example. Figure 27 Zones: multi-hop A B C Zone: Z1 mhop D E TIBCO Enterprise Message Service User’s Guide . A zone affects the forwarding behavior of its routes: • • • In a multi-hop (mhop) zone. so you can configure complex routing paths. In a one-hop (1hop) zone. topic messages travel along all applicable routes to all servers connected by routes within the zone. B would forward the message to A. but not queue messages. C. topic messages travel only one hop (from the first server). Every route belongs to a zone. C and D—but D would not forward it E. Zones affect topic messages. if Z1 were a one-hop zone. In contrast. M serves consumers at the main office. auditing. which process the messages from the branches. R serves consumers that record messages for archiving. this limitation results in the desired result—forwarding from B1 to M and R. since these routes belong to the one-hop zone Z2. and from B2 to M and R. and backup. Instead.Zone 407 | Eliminating Redundant Paths with a One-Hop Zone Figure 28 illustrates an enterprise with four servers: • • • B1 and B2 serve producers at branch offices of an enterprise. However. The goal is to forward messages from B1 and B2 to both M and R. Figure 28 Zones: one-hop B1 B2 Zone: Z2 1hop M R TIBCO Enterprise Message Service User’s Guide . The routing graph seems to contain a cycle—the path from B1 to M to B2 to R duplicates the route from B1 to R. it is impossible for messages to travel the longer path. NY1 forwards it one hop to each of the other New York servers. When the message reaches NY1. and its hop count is reset to zero. it crosses into zone PA (with hop count reset to zero). which in turn forwards it to PA1. the routing behavior within each zone does not limit routing in other zones. When the message reaches TK1. when a forwarded message reaches a server with routes in several zones. when the message reaches PA1. it travels one hop to each of the other Tokyo servers. TK1 forwards the message to NY1. the message crosses zone boundaries. Zone TK connects all the servers in Tokyo. it crosses into zone NY (with hop count reset to zero). Similarly. the multi-hop zone WO connects one server in each city. In addition. Figure 29 Zones: overlap TK3 TK2 PA2 PA3 TK4 Zone: TK 1hop TK1 Zone: WO mhop PA1 Zone: PA PA4 1hop NY1 NY2 NY4 Zone: NY 1hop NY3 TIBCO Enterprise Message Service User’s Guide . zone PA connects all the servers in Paris. Figure 29 on page 408 illustrates an enterprise with one-hop zones connecting all the servers in each of several cities in a fully-connected graph. When a client of server TK3 produces a message. When zones overlap at a server.408 | Chapter 16 Working With Routes Overlapping Zones A server can have routes that belong to several zones. it crosses into zone WO. zone NY connects all the servers in New York. PA1 forwards it one hop to each of the other Paris servers. That is. so we refer to it as the passive server. Active-Passive Routes When you configure a route at only one server. You can promote an active-passive route to an active-active route. and also configure other servers to initiate routes to S. or initiating server. this asymmetry results in two perspectives on the route: • A route is active from the perspective of the server where it is configured. use this command on the passive server: create route name url=url The url argument is required. so we refer to it as the active server. This configuration results in only one connection. properties of routes are associated with the server where the route is configured. You can specify and modify the properties of an active route. Active-Active Routes Two servers can both configure an active route one to the other. it persists messages for durable subscribers.Active and Passive Routes 409 | Active and Passive Routes A route connects two servers. TIBCO Enterprise Message Service User’s Guide . This server actively initiates the connection to the other server. That is. and B specifies a route to A. Either server can attempt to initiate the connection. the server reports an error). For example. A route is passive from the perspective of the other server. Note that defining a route specifies a zone as well (either implicitly or explicitly). so that the server (where the route is being promoted) can connect to the other server if the route becomes disconnected. The promoted route behaves as a statically configured route—that is. subsequent routes in the same zone must have the same zone type (otherwise. and administrators can modify its properties. See also create route on page 110. This arrangement is called an active-active configuration. To promote a route. You may configure a route at either or both of the servers. and stores its configuration in routes. it does not result in redundant routes.conf. and which initiates the connection. server A specifies a route to server B. but not those of a passive route. That is. This server passively accepts connection requests from the active server. you can configure server S to initiate routes. The first route in the zone defines the type of the route. • A server can have both active and passive routes. the URL can be a comma-separated list of URLs denoting fault-tolerant servers. see Selectors for Routing Topic Messages on page 417. • zone_name specifies that the route belongs to the routing zone with this name. Example For example. Syntax To create a route using the administration tool. URL specifies the passive server by its URL—including protocol and port. see Routing and SSL on page 411. it also becomes the name of the route.0). properties is a space-separated list of properties for the route. first connect to one of the servers. Fault Tolerance.RouteInfo in the online documentation). • • The zone type is either 1hop or mhop. on page 383.tibjms.admin. see Chapter 15. For properties that configure the Secure Sockets Layer (SSL) protocol for the route. the default value is default_mhop_zone (this default yields backward compatibility with configurations from releases earlier than 4. these commands on server A would create routes to servers B and C. or the administration APIs (see com. For more information about fault tolerance.tibco. When absent. If your environment is configured for fault tolerance. create route B url=tcp://B:7454 zone_name=Z1 zone_type=1hop create route C url=tcp://C:7455 zone_name=ZM zone_type=mhop TIBCO Enterprise Message Service User’s Guide . The route to C belongs to the multi-hop zone ZM. When omitted. The route to B belongs to the one-hop zone Z1. Each property has the syntax: prop_name=value For gating properties that control the flow of topics along the route.410 | Chapter 16 Working With Routes Configuring Routes and Zones You can create routes using the administration tool (see Chapter 6 on page 101). then use the create route command with the following syntax: create route name url=URL zone_name=zone_name zone_type=1hop|mhop properties • • name is the name of the passive server (at the other end of the route). the default value is mhop. Example create route B url=tcp://B:7454.tcp://BBackup:7454 zone_name=Z1 zone_type=1hop Routing and SSL When configuring a route. tibemsd. Failover behavior for route connections is similar to that for client connections. the active server can connect to the backup server and resume routing. you can specify SSL parameters for the connection.Configuring Routes and Zones 411 | Show Routes You can display these routes using the show administration tool: show Route B C routes T ConnID A 3 A - routes command in the URL tcp://B:7454 tcp://C:7455 Zone Z1 ZM T 1 m • • • The Route column lists the name of the passive server. each server specifies this information in a different place: • • The passive server must specify SSL parameters in its main configuration file. Routes to Fault-Tolerant Servers You can configure servers for fault tolerance. or you can specify them in the route configuration file. Client applications can specify the primary and backup servers.conf. see Configuring Clients for Fault-Tolerant Connections on page 397. if the client’s connection to the primary server fails. When a server initiates an SSL connection. Although both participants in an SSL connection must specify a similar set of parameters. from the perspective of server A. TIBCO Enterprise Message Service User’s Guide .conf. it sends the route’s SSL parameters to identify and authenticate itself to the passive server. The ConnID column contains either an integer connection ID (if the route is currently connected. routes. the client can connect to the backup server and resume operation. Similarly. so that if the route to the primary server fails. a route specification can specify primary and secondary passive servers. You can specify these parameters when creating the route. The T column indicates whether the route is active (A) or passive (P). or a dash (-) if the route is not connected. see File Names for Certificates and Keys on page 369. DER. This parameter accepts private keys in PEM. including the CA root certificate.pem ssl_issuer = certs\CA_child2. see Chapter 14. on page 365. ssl_private_key The local server’s private key. or you can specify the path to a file that contains the certificate in one of the supported formats. DER. or PKCS#12 format. see File Names for Certificates and Keys on page 369. Example ssl_issuer = certs\CA_root. then you may omit this parameter. Table 71 SSL Parameters for Routes (Sheet 1 of 3) Parameter ssl_identity Description The server’s digital certificate in PEM. For more information. Using the SSL Protocol.412 | Chapter 16 Working With Routes Table 71 lists the parameters that you can specify in the routes. or you can specify a path to a file that contains the key. or on the command line when creating a route. The server reads the certificates in the chain in the order they are presented in this parameter. For more information.pem For more information. PKCS#7 or PKCS#12 format.conf configuration file. ssl_issuer Certificate chain member for the server. see File Names for Certificates and Keys on page 369. If the digital certificate in ssl_identity already includes this information. TIBCO Enterprise Message Service User’s Guide . Supply the entire chain. The parameters for configuring SSL between routed servers are similar to the parameters used to configure SSL between server and clients. You can copy the digital certificate into the specification for this parameter.pem ssl_issuer = certs\CA_child1. DER and PKCS#12 formats. You can specify the actual key in this parameter. The certificates must be in PEM. TIBCO Enterprise Message Service User’s Guide . For more information. ssl_trusted List of certificates that identify trusted certificate authorities. The values for this parameter are enabled and disabled. signifying the server must verify the other server’s certificate. see Chapter 6. DER or PKCS#7 format. see File Names for Certificates and Keys on page 369. but does not verify the server’s identity. on page 101. For more information. You can either provide the actual certificates. When omitted. or you can specify a path to a file containing the certificate chain. When passwords are set with this tool. You can set passwords using the tibemsadmin tool. the password is obfuscated in the configuration file. The certificates must be in PEM. the server establishes secure communication with the other server. ssl_verify_host Specifies whether the server must verify the other server’s certificate. the default is enabled. Using the EMS Administration Tool. When this parameter is disabled.Configuring Routes and Zones 413 | Table 71 SSL Parameters for Routes (Sheet 2 of 3) Parameter ssl_password Description Private key or password for private keys. ssl_ciphers Specifies a list of cipher suites. TIBCO Enterprise Message Service User’s Guide . ssl_rand_egd The path for the installed entropy gathering daemon (EGD). This parameter accepts both the OpenSSL name for cipher suites. If the names do not match. For information about available cipher suites and their names. This parameter is relevant only when the ssl_verify_hostname parameter is enabled. the default is enabled. When this parameter is disabled. This daemon generates random numbers. but does not verify the server’s name. the connection is rejected. If this parameter is not set. ssl_expected_hostname Specifies the name expected in the CN field of the other server’s certificate. The values for this parameter are enabled and disabled. the server establishes secure communication with the other server. When omitted. or the longer descriptive names. signifying the server must verify the name of the connected host or the name specified in the ssl_expected_hostname parameter against the value in the server’s certificate.414 | Chapter 16 Working With Routes Table 71 SSL Parameters for Routes (Sheet 3 of 3) Parameter ssl_verify_hostname Description Specifies whether the server must verify the name in the CN field of the other server’s certificate. separated by colons (:). if one is installed. the default is the hostname of the other server. see Specifying Cipher Suites on page 376. M and B—connected by routes in a multi-hop zone. When a route becomes disconnected (for example. to server B and its subscriber client. Consider this sequence of events. For example. Figure 30 Routing: Propagating Subscribers A Zone: Z mhop M B Server: A Topic: T1 global Subscriber T1 Server: M Topic: T1 global Subscriber T1 Server: B Topic: T1 global Subscriber T1 Client Producer T1 Client Subscriber T1 TIBCO Enterprise Message Service User’s Guide . When the route reconnects. the server forwards the stored messages. the top of Figure 30 depicts an enterprise with three servers—A. see addprop topic on page 107 and create topic on page 111. Propagating Registered Interest To ensure forwarding of messages along routes. Topic messages can traverse multiple hops.Routed Topic Messages 415 | Routed Topic Messages A server forwards topic messages along routes only when the global property is defined for the topic. The bottom of Figure 30 illustrates the mechanism at work within the servers to route messages from a producer client of server A. through server M. the forwarding server stores topic messages. Servers connected by routes do exchange messages sent to temporary topics. because of network problems). servers propagate their topic subscriptions to other servers. if B fails. M accepts the message on its topic T1. For example. We recommend that you set the maxbytes property of the topic (T1) on each server. then M retains its internal subscriber and continues to store messages for clients of B. 4. server M propagates its interest in T1 to server A. then server M stores messages until B resumes. to prevent unlimited storage growth (which could further disrupt operation). 2. When a producer client of server A sends a message to topic T1. 3. then if the client process exits. In response. 5. delivers) messages from topic T1 to B. then if the client process exits. Server B. TIBCO Enterprise Message Service User’s Guide . This subscriber ensures that A forwards messages from topic T1 to M. B accepts the message on its topic T1. If the client of server B creates a durable subscriber to T1. then M removes its internal subscriber and does not store messages for clients of B—potentially resulting in a gap in the message stream. M creates an internal subscriber to T1 on behalf of server B. meanwhile. When the client restarts. A forwards it to M. the servers delete the entire sequence of internal subscribers. M forwards the stored messages. messages continue to flow through the servers in store-and-forward fashion. In an active-passive route configured on B. and passes it to the client. if B fails. A creates an internal subscriber to T1 on behalf of server M. This subscriber ensures that M forwards (that is.416 | Chapter 16 Working With Routes 1. registers interest in T1 on behalf of the client by creating an internal subscriber object. 6. Server B behaves as a client of server M. maxbytes Combining durable subscribers with routes creates a potential demand for storage—especially in failure situations. Similarly. In response. it generates a new sequence of subscribers. Because a route connects servers M and B. the client might have missed messages. because a route connects servers A and M. All three servers configure a global topic T1. At bottom right of Figure 30. Subscriber Client Exit If the client of server B creates a non-durable subscriber to T1. server B propagates its interest in T1 to server M. Server Failure In an active-active route between servers B and M. it can consume all the messages that B has been storing in the interim. Server M behaves as a client of server A. a client of server B creates a subscriber to T1. if server B fails. the entire sequence of internal subscribers remains intact. and forwards it to B. M creates a new internal subscriber and resumes forwarding messages. When B reconnects. When the client restarts. When B reconnects. this policy could potentially result in a high volume of unwanted network traffic. we configure topic selectors so that each regional server gets only those orders related to customers within its region. example Incoming Orders Central Order Server USA Orders USA Order Processing Canada Orders Canada Order Processing Mexico Orders Mexico Order Processing TIBCO Enterprise Message Service User’s Guide . You can specify message selectors on routes. to narrow the subset of topic messages that traverse each route. Figure 31 Routing: Topic Selectors. Message selectors on routes are different from message selectors on individual subscribers. and separate regional servers for billing those orders. which narrow the subset of messages that the server delivers to the subscriber client. Example Figure 31 illustrates an enterprise with a central server for processing customer orders. For optimal use of network capacity. When each of those other servers requires only a small subset of the messages.Routed Topic Messages 417 | Selectors for Routing Topic Messages Motivation A server forwards a global topic message along routes to all servers with subscribers for that topic. setprop.. [Mexico] url=ssl://mexico:7222 outgoing_topic=orders selector="country=’Mexico’" . TIBCO Enterprise Message Service User’s Guide .. Manipulate selectors on an existing route (using the addprop.conf: [Canada] url=ssl://canada:7222 outgoing_topic=orders selector="country=’Canada’" .. see the documentation for class Message in TIBCO Enterprise Message Service Java API Reference.conf. or with the administrator command create route).418 | Chapter 16 Working With Routes Specifying Selectors Specify message selectors for global topics as properties of routes. topicName is the name of a global topic.. Syntax The message selector properties have the same syntax whether they appear in a command or in a configuration file: incoming_topic=topicName selector="messageSelector" outgoing_topic=topicName selector="messageSelector" The terms incoming and outgoing refer to the perspective of the active server— where the route is defined. [USA] url=ssl://usa:7222 outgoing_topic=orders selector="country=’USA’" . or removeprop administrator commands). Example Syntax In the example of Figure 31. You can define these properties in two ways: • • Define selectors when creating the route (either in routes.. messageSelector is a message selector string. an administrator might configure these routes on the central order server: setprop route Canada outgoing_topic="orders" selector="country=’Canada’" setprop route Mexico outgoing_topic="orders" selector "country=’Mexico’" setprop route USA outgoing_topic="orders" selector="country=’USA’" Those commands would create these entries in routes.. For detailed information about message selector syntax. then the effective selector for T on the route from A to B is (S1 AND S2). the effect is the same. For each actual topic. Wildcards You can specify wildcards in topic names. the server uses logical AND to combine all the selectors that match the topic. or B specifies a route to A with outgoing_topic selectors. TIBCO Enterprise Message Service User’s Guide . and incoming_topic selector S2 for T on server B. If you specify outgoing_topic selector S1 for topic T on server A. you may specify selectors on either or both servers. outgoing_topic Active-Active Configuration In an active-active configuration. Whether A specifies a route to B with incoming_topic selectors.Routed Topic Messages 419 | Symmetry and incoming_topic are symmetric. See also Active and Passive Routes on page 409. 420 | Chapter 16 Working With Routes Routed Queues With respect to routing. This designation indicates that these queues depend upon and reflect their home queue (that is. Servers P and S define routed queues [email protected] and fwd to R .home queue L Producer Q1 M Consumer Q1 Server: S S Q1@R global . R is the owner of Q1.proxy rcvr N Consumer Q1 Owner & Home Server R defines a global queue named Q1. Figure 32 Routing: Queues Server: P P Q1@R global . The concept of zones and hops does not apply to queue messages (only to topic messages).proxy rcvr J Producer Q1 K Consumer Q1 Server: R R Q1 global . The remainder of Figure 32 illustrates the mechanisms that routes queue messages among servers (center) and their clients (right side). R and S— connected by routes. clients of P refer to the routed queue as Q1. TIBCO Enterprise Message Service User’s Guide . Q1 on server R). The left side of Figure 32 depicts an enterprise with three servers—P. Notice that the designation Q1@R is only for the purpose of configuration. queues differ from topics in several respects: • • Servers route queue messages between the queue owner and adjacent servers. K can again receive messages through Q1 on P. That is. when J sends a message to Q1 on server P. or Q1 on S receives it on behalf of N. client K cannot consume the message directly from server P. If server R fails. TIBCO Enterprise Message Service User’s Guide . configure: Q1@R global It is legal to use this notation even for the home queue. when L sends a message to Q1 on server R. P delivers the stored messages to Q1 on R. Now the message is available to receivers on all three servers. for example. Configuration You must explicitly configure each routed queue in queues. see addprop queue on page 106 and create queue on page 110. and ignores the location designation (@R). or the route connection from P to R fails. and immediately gives it to K. P forwards it to the queue owner. Q1 on P can receive it from R on behalf of K. When P and R resume communication. For example. specify the queue name and the server name of the queue owner. To configure a routed queue. M and N continue to receive messages from Q1. The message is not available for consumers until it reaches the home queue. For example. It is illegal to configure a routed queue as exclusive. R and S— although only one client can consume the message. which delivers it to Q1 (the home queue). or the route connection from P to R fails. P continues to store messages from K in its queue. Producers From the perspective of producer clients. Meanwhile. The queue owner recognizes its own name. When P and R resume communication. You may use the administration tool or API to configure routed queues. a routed queue acts as a proxy receiver. server P forwards the message to the home queue—Q1 on server R.Routed Queues 421 | Example When J sends a message to Q1. R. If server P fails. Consumers From the perspective of consumer clients. K cannot receive messages from Q1 until the servers resume communication. on server P. P.conf—clients cannot create routed queues dynamically. Either Q1 on P receives it on behalf of K. or M receives it directly from the home queue. a routed queue stores messages and forwards them to the home queue. Transactions XA sessions and transacted sessions (local and XA transactions) do not support routed queues. servers A and B both configure active routes to one another. A must configure a user named B. TIBCO Enterprise Message Service User’s Guide . However.422 | Chapter 16 Working With Routes Browsing Queue browsers cannot examine routed queues. and B need not configure a user named A. • • Because A enables authorization. A need not identify itself to B. because B disables authorization. That is. or by X. Routing and Authorization User & Password When a server’s authorization parameter is enabled. you can create a browser only on the server that owns the home queue.509 certificate. Figure 33 Routing: Authorization A B authorization=enabled authorization=disabled Q2@B Q2 In Figure 33. other servers that actively connect to it must authenticate themselves by name and password. servers consult the ACL specification before forwarding each message. then for messages to flow from A to B. And for messages to flow from B to A. in Figure 33. For example.Routing and Authorization 423 | ACL When routing a secure topic or queue. Authentication and Permissions. The servers must grant one another appropriate permissions to send. on page 221 TIBCO Enterprise Message Service User’s Guide . you would have to grant topic B publish permission on the topic. See Also Chapter 8. if messages were to flow from B to A (producer connects to B and consumer connects to A). publish or subscribe. you don’t need an ACL for messages to flow from A (where a producer is sending to) to B (where a consumer is consuming from) because B has authorization turned off and messages are being sent to and consumed from queues. If we were to use topics in this example. you would need A to grant B the subscribe and durable permission on the topic (global on both servers). However. then server A's ACL should grant user B send permission on the queue Q2. receive. 424 | Chapter 16 Working With Routes TIBCO Enterprise Message Service User’s Guide . page 431 TIBCO Enterprise Message Service User’s Guide . page 427 Method Description. Topics • • • Overview of Server Management With TIBCO Hawk.| 425 Appendix A Using TIBCO Hawk This appendix describes how to configure TIBCO Hawk so that it can be used to administer and monitor the TIBCO Enterprise Message Service server. see the TIBCO Hawk documentation. For more information about TIBCO Hawk. page 426 Installing the Classes. tibjms.admin. Management methods for shutting down the TIBCO Enterprise Message Service server and performing other administrative functions.admin. queues.HawkListener Description Monitoring methods that allow you to view the status of topics. TIBCO Enterprise Message Service provides classes for administering the EMS server. com.HawkController TIBCO Enterprise Message Service User’s Guide . This class contains all HawkListener monitoring methods as well.tibjms. Once the classes are loaded. and other items on the TIBCO Enterprise Message Service server. If you wish to monitor and manage the server. Table 72 describes the provided classes. If you wish to only monitor the server. Table 72 TIBCO Enterprise Message Service classes in TIBCO Hawk Class com. you can use the HawkListener class. This appendix details how to install the provided classes into the TIBCO Hawk agent and the methods available for monitoring and managing the TIBCO Enterprise Message Service server. you must load the classes provided into the TIBCO Hawk agent. you only need the HawkController class.tibco.hawk.hawk. methods for managing the EMS server are available in the TIBCO Hawk display. routes.426 | Appendix A Using TIBCO Hawk Overview of Server Management With TIBCO Hawk TIBCO Hawk is a tool for monitoring and managing applications and operating systems. To use TIBCO Hawk to manage the TIBCO Enterprise Message Service server.tibco. 0 or later. To set the plugins directory. perform the following: 1. Refer to your TIBCO Hawk documentation for details on installing plugins.5 or later. if you are using an earlier version of TIBCO Hawk. You can use either the HawkListener class if you only want to monitor the server.Installing the Classes 427 | Installing the Classes Installing the provided classes is different for UNIX and Windows platforms. TIBCO Enterprise Message Service User’s Guide . 6.5. 5. and copy it into the hawk\admin-plugins directory. ems\clients\java 3. click the Agent tab.1. locate jms.hma file in the TIBCO Enterprise Message Service installation directory under the ems\samples\admin\hawk subdirectory and copy it into your hawk\admin-plugins directory. Locate the tibemsadmin. For Hawk version 4.jar in the subdirectory. and copy them into the hawk\admin-plugins directory. These instructions are specific to TIBCO Hawk Release 4. or you can specify the HawkController class if you want to monitor and manage the server.jar in the ems\clients\java subdirectory. Windows Installation To install the provided classes for use in a TIBCO Hawk agent running on a Windows platform. If you are using Hawk earlier than 4. Navigate to your plugins directory and open the tibemsadmin. Earlier versions of TIBCO Hawk have a different mechanism for adding plugins. 2. The following sections detail how to install the TIBCO Enterprise Message Service management classes into the TIBCO Hawk agent for each platform.jar and tibjms.hma file in a text editor. Open the TIBCO Hawk Configuration Utility and make certain the admin-plugins directory is set to the location where you have installed TIBCO Hawk plugins. Specify the TIBCO Hawk microagent class you wish to use in the <classname> element. For more information about using the TIBCO Hawk Configuration Utility. Specify the username and password and server URL to use to connect to the TIBCO Enterprise Message Service server in the appropriate <arg> elements. then set the Plugins Directory field to the location where the plugins are located. see TIBCO Hawk Installation and Configuration. locate tibjmsadmin. 4. See Table 73 on page 429. yourcompany. locate tibjmsadmin. 3.jar in the ems/clients/java subdirectory. and copy them into the TIBCO Hawk plugins directory. Usually.cfg file and specify the -hma_plugin_dir option to include the directory where your TIBCO Hawk plugins are located. 4. Specify the TIBCO Hawk microagent class you wish to use in the <classname> element. See the TIBCO Hawk documentation for more information about restarting the service. For more information about editing TIBCO Hawk configuration files on UNIX. a TIBCO Hawk plugins directory is located in /usr/tibco/hawk/plugins. see TIBCO Hawk Installation and Configuration.5.jar and tibjms.428 | Appendix A Using TIBCO Hawk For example: <arguments> <arg>-user</arg> <arg>admin</arg> <arg>-password</arg> <arg>MyPassword</arg> <arg>-server</arg> <arg>tcp://server1. For Hawk version 4. If you are using Hawk earlier than 4.5 or later. and copy it into the TIBCO Hawk plugins directory. Restart the TIBCO Hawk agent service. 7. 5. 2.hma file in a text editor.hma file in the TIBCO Enterprise Message Service installation directory under the ems/samples/hawk subdirectory and copy it into your TIBCO Hawk plugins directory.com:7222</arg> <arg>-timeout</arg> <arg>5</arg> </arguments> You should specify the predefined admin user or a user that is a member of the $admin group. UNIX Installation To install these classes for use in a TIBCO Hawk Agent running on a UNIX platform. Navigate to your plugins directory and open the tibemsadmin. Locate the tibemsadmin. You can use either the HawkListener class if you only TIBCO Enterprise Message Service User’s Guide . Edit the TIBCO Hawk hawkagent.jar in the ems/clients/java subdirectory. perform the following procedure: 1. locate jms. com:7222</arg> <arg>-timeout</arg> <arg>5</arg> </arguments> You should use specify the predefined admin user or a user that is a member of the $admin group. For example: <arguments> <arg>-user</arg> <arg>admin</arg> <arg>-password</arg> <arg>MyPassword</arg> <arg>-server</arg> <arg>tcp://server1. See Table 73 on page 429. As the value for -encryptedPassword.yourcompany. or you can specify the HawkController class if you want to monitor and manage the server. Parameters Table 73 TIBCO Hawk MicroAgent Parameters (Sheet 1 of 2) Parameter -user -password Description The MicroAgent identifies itself with this user name and password when it connects to the EMS server. When absent. Specify the username and password and server URL to use to connect to the TIBCO Enterprise Message Service server in the appropriate <arg> elements. specify this pair.Installing the Classes 429 | want to monitor the server. the default is tcp://localhost:7222. 6. -user -encryptedPassword To use an encrypted password. supply the output you obtain by running the Hawk utility program tibhawkpassword located in your hawk/bin directory: tibhawkpassword -encrypt password where password is your current password. When absent. -server The MicroAgent connects to the EMS server at this URL (host computer and port). the default user name is admin. See the TIBCO Hawk Installation and Configuration Guide for details. When absent. the default password is the empty string. TIBCO Enterprise Message Service User’s Guide . TIBCO Enterprise Message Service User’s Guide . 3600].430 | Appendix A Using TIBCO Hawk Table 73 TIBCO Hawk MicroAgent Parameters (Sheet 2 of 2) Parameter -timeout Description Limits the time (in seconds) that the MicroAgent waits for the EMS server to respond to queries. When absent. the default is 60. Acceptable values are in the range [5. hawk.tibco.HawkListener Methods getMethods() This method returns the list of methods that this TIBCO Hawk class can perform. show server — 145 — 134 150 143 getServerInfo() getNumConnections() getConnections getUsers() getQueues( String regexp) Returns the number of connections. getRoutes() show route show routes 144 (shows information from both commands for each route) getTopics( String regexp) show topic show topics 148 (shows information from both commands for each topic) You can specify a topic name or a pattern to return all matching topic names. Using the EMS Administration Tool. show connections show users show queue show queues (shows information from both commands for each queue) You can specify a queue name or a pattern to return all matching queue names. The table also lists the page where you can find more information about each command in Chapter 6. Table 74 lists the methods of each class and the corresponding tibemsadmin command for the method. TIBCO Enterprise Message Service User’s Guide .Method Description 431 | Method Description The TIBCO Hawk classes have several methods for managing and monitoring a TIBCO Enterprise Message Service server.admin. These methods correspond to commands you can issue in the administration tool. on page 101.tibjms. Table 74 TIBCO Hawk method names (Sheet 1 of 2) TIBCO Hawk Agent Method Name tibemsadmin Command Page com. purge queue purgeQueue( String name) 119 Specify the name of the queue to purge.HawkController Methods (also contains all HawkListener methods) shutdown() purgeDurable( String name. this method breaks the test connection.admin. String subjPattern) getTransports() getTransport( String name) show rvcmlisteners show rvcmlistener 145 145 Shows the name and subject of the specified RVCM listener.hawk.tibco.tibjms.) — isRunning() com. String clientID) shutdown purge durable 152 118 Specify the name of the durable subscription and the client ID associated with the durable subscription (client ID can be null).432 | Appendix A Using TIBCO Hawk Table 74 TIBCO Hawk method names (Sheet 2 of 2) TIBCO Hawk Agent Method Name getDurables( String regexp) tibemsadmin Command show durables Page 139 You can specify a topic name or a pattern to return all matching durable subscriptions. show rvcmtransportledger getCMLedgerInfo( String transport. show stat consumers show stat producers getConsumers() getProducers() getListenPorts() 145 145 — 145 This method returns the list of ports the TIBCO Enterprise Message Service server is configured to listen on. purge topic purgeTopic( String name) 119 Specify the name of the topic to purge. rotatelog rotateLog() 121 TIBCO Enterprise Message Service User’s Guide . (Afterward. Check whether the server is reachable by attempting to connect to it. page 437 TIBCO Enterprise Message Service User’s Guide . page 434 Description of Topic Message Properties. The message properties for messages published on each topic are also described. See Monitoring Server Events on page 355 for more information about monitor topics and messages. Topics • • Description of Monitor Topics.| 433 Appendix B Monitor Messages This appendix lists all topics on which the server publishes messages for system events. destroy $sys.create $sys.monitor. An error occurs on a user connection.route.monitor.limits.producer.monitor.route.disconnect $sys..monitor.queue. Stored messages fall below a destination’s limit.monitor.consumer. A user attempts to connect to the server.connection.error TIBCO Enterprise Message Service User’s Guide .limits. A dynamic queue is created. Maximum bytes for durable subscriptions is reached.topic $sys.monitor.create $sys.monitor.create $sys.connection.flow.434 | Appendix B Monitor Messages Description of Monitor Topics Table 75 describes each monitor topic.monitor.destroy $sys. A route connection is disconnected.disconnect $sys.connection $sys.change Message Is Published When.monitor.engaged $sys. engaging the flow control feature.error $sys.flow.. A consumer is destroyed. $sys.limits.monitor.disengaged $sys. A user connection is disconnected. Server memory limit is reached.monitor.monitor. The administrator has made a change to the configuration.consumer.connection. A consumer is created. An error occurs on a route connection.producer.server $sys.connect $sys. Maximum bytes for queue storage is reached. A route connection is attempted.monitor. A producer is destroyed. Table 75 Monitor topics (Sheet 1 of 3) Topic $sys.route.queue $sys. Stored messages rise above a destination’s limit.admin.monitor.connect $sys.monitor. disengaging the flow control feature. Maximum number of hosts or connections is reached.monitor.monitor. A producer is created.limits.monitor. server.info Message Is Published When..monitor.state $sys. A dynamic topic is created.action $sys. The server state changes. $sys.interest $sys. a log file is rotated..monitor.monitor.monitor.Description of Monitor Topics 435 | Table 75 Monitor topics (Sheet 2 of 3) Topic $sys. An XA transaction commits or rolls back. an administrator shuts down the server.action TIBCO Enterprise Message Service User’s Guide .monitor. for example. A local transaction commits or rolls back.server.route.topic.monitor.create $sys. The server sends information about an event. A change in registered interest occurs on the route.xa. for example.tx. monitor. route. include full message (as a byte array) into each event t — topic.D. external system. receive. information about where the message came from (a producer.T. TIBCO Enterprise Message Service User’s Guide . D signifies the type of destination and whether to include the entire message: • • • • T — topic. The topic $sys.monitor.436 | Appendix B Monitor Messages Table 75 Monitor topics (Sheet 3 of 3) Topic $sys.*. A message is handled by a destination. The message body of any received messages is included in monitor messages on this topic.* monitors all message events (send.E. and so on). $sys.q.News.monitor. do not incude full message into each event E signifies the type of event: • • • • • r s a p * for receive for send for acknowlege for premature exit of message for all event types For example. See Monitoring Messages on page 356 for more information about message monitoring.corp.r.News is the topic for monitoring any received messages to the topic named corp. acknowledge) for all queues matching the name corp.. and optionally the message body.corp.*.destination Message Is Published When. The messages sent to this type of monitor topic include a description of the event. The name of this monitor topic includes two qualifiers (D and E) and the name of the destination you wish to monitor.. depending upon the value of D. do not incude full message into each event Q — queue. The message body is not included in this topic’s messages. include full message (as a byte array) into each event q — queue. the last part of the topic name without the $sys. This property can have the values listed in Table 77 on page 442. Whether the client connection is a connection to a fault-tolerant server. The type of monitoring event (that is. Whether the client connection uses the SSL protocol. Whether the client connection is an XA connection. event_class TIBCO Enterprise Message Service User’s Guide . the value of this property is always set to message. Hostname of the connection that generated the event. For message monitoring. The action that caused the event. This property can have the following values: • • • • • • • Admin Topic Queue Generic Route FT conn_hostname conn_ssl conn_ssl2 conn_type (connection to fault-tolerant server) Unknown conn_username conn_xa event_action User name of the connection that generated the event.Description of Topic Message Properties 437 | Description of Topic Message Properties Table 76 describes the properties that monitor topic messages can contain. Each monitor message can have a different set of these properties. Table 76 Message properties (Sheet 1 of 5) Property conn_connid conn_ft Contents Connection ID of the connection that generated the event.monitor). Whether the server connection uses the SSL protocol. Type of connection that generated the event. 438 | Appendix B Monitor Messages Table 76 Message properties (Sheet 2 of 5) Property event_reason Contents The reason the event occurred (usually an error). Name of the source object involved with the event. the route that the event occurred on. When the full message is to be included for message monitoring. Message timestamp. Message ID. Message delivery mode. You can use the createFromBytes method (in the various client APIs) to recover the message. Message JMSReplyTo. This property can have the following values: • • • • • • XID (global transaction ID) message_id connections unknown (number of connections) (unknown name) Any server property name the name of the user. This values of this property can be the following: • • • persistent non_persistent reliable event_route message_bytes mode msg_seq msg_id msg_timestamp msg_expiration replyTo rv_reply source_id source_name Message sequence number. ID of the source object. this field contains the message as a byte array. or anonymous TIBCO Enterprise Message Service User’s Guide . Message expiration. For routing. Message RV reply subject. The values this property can have are described in Table 78 on page 444. Message count statistic for producer or consumer. Time that the consumer was created (in milliseconds since the epoch). Name of the target destination target_dest_name TIBCO Enterprise Message Service User’s Guide . This property can have the following values: • • • • • • • • • • • • • • • • • • producer consumer topic queue permissions durable server transaction user group connection message jndiname factory file limits route transport (a limit. such as a memory limit) source_value stat_msgs stat_size target_admin target_created Value of source object. Message size statistic for producer or consumer. Whether the target object is the admin connection.Description of Topic Message Properties 439 | Table 76 Message properties (Sheet 3 of 5) Property source_object Contents Source object that was involved with the event. Name of durable subscriber when target is durable subscriber. ID of the target object. TIBCO Enterprise Message Service User’s Guide . This property can have the following values: • • • • • • XID (global transaction ID) message_id connections unknown (number of connections) (unknown name) Any server property name the name of the user. Group name that was target of the event Hostname of the target object. or anonymous target_nolocal NoLocal flag when target is durable subscriber.440 | Appendix B Monitor Messages Table 76 Message properties (Sheet 4 of 5) Property target_dest_type target_durable target_group target_hostname target_id target_name Contents Type of the target destination. Name of the object that was the target of the event. This property can have the following values: • • • • • • • • • • • • • • • • • • producer consumer topic queue permissions durable server transaction user group connection message jndiname factory file limits route transport (a limit. Value of the object that was the target of the event. permission.Description of Topic Message Properties 441 | Table 76 Message properties (Sheet 5 of 5) Property target_object Contents The general object that was the target of the event. queue. such as a memory limit) target_selector target_subscription target_url target_username target_value Selector when the target is a consumer. TIBCO Enterprise Message Service User’s Guide . Username of the target object. such as the name of a topic. Subscription of the target object when target is durable subscriber. URL of the target object. and so on. queue. engaging the flow control feature stored messages fall below a destination’s limit.442 | Appendix B Monitor Messages Table 77 Event Action Property Values (Sheet 1 of 2) Event Action Value accept acknowledge add admin_commit Description connection accepted message is acknowledged user added to a group administrator manually committed an XA transaction administrator manually rolled back an XA transaction transaction committed connection attempted something created something deleted connection disconnected stored messages rise above a destination’s limit. or durable subscriber purged message posted into destination user removed from a group administrator resumed a route admin_rollback commit connect create delete disconnect flow_engaged flow_disengaged interest modify grant premature_exit purge receive remove resume TIBCO Enterprise Message Service User’s Guide . disengaging the flow control feature registered interest for a route something changed permission granted message prematurely exited topic. indicating success an application suspended an XA transaction an application prepared an XA transaction an application called recover (to get a list of XA transactions) an application rolled back an XA transaction txrollback xacommit xacommit_1phase xastart xastart_join xastart_resume xaend_fail xaend_success xaend_suspend xaprepare xarecover xarollback TIBCO Enterprise Message Service User’s Guide .Description of Topic Message Properties 443 | Table 77 Event Action Property Values (Sheet 2 of 2) Event Action Value revoke rollback rotate_log send suspend txcommit Description permission revoked transaction rolled back log file rotated message sent by server to another party administrator suspended a route administrator manually committed a local transaction administrator manually rolled back a local transaction an application committed an XA transaction (2-phase) an application committed an XA transaction (1-phase) an application started a new XA transaction an application has joined (that is. added) a resource to an existing transaction an application resumed a suspended XA transaction an application ended an XA transaction. indicating failure an application ended an XA transaction. bridge closed consumer cycle disabled discarded duplicate error exceeded expired export import invalid_name invalid_password TIBCO Enterprise Message Service User’s Guide . such as route. For all other cases. Connection was closed. Limit exceeded. Message exported to a transport. Feature not enabled. Cyclic route created. Name not valid. global queue or topic.444 | Appendix B Monitor Messages Table 78 Event Reason Property Values (Sheet 1 of 2) Event Reason Value backup_connected backup_disconnected Description The fault-tolerant backup server has connected. this value signifies a message was sent or acknowledged by a consumer. Message has been expired by the server. This occurs when overflowPolicy=discardOld is set on the destination and either the maxmsgs and/or maxbytes limit set for the destination has been exceeded. Connection disconnected due to error. The oldest message on the destination has been discarded to make room for a new message. The fault-tolerant backup server has disconnected. Duplicate. this value signifies a dynamic topic or queue created for a consumer. Invalid password provided. Message imported from a transport. For message monitoring. Message posted to destination as result of bridging. such as route name. Something was expected. this value signifies a dynamic topic or queue created for a producer. but not found. this value signifies a message was sent or received from a route. For message monitoring. Connection active. Not authorized to perform action. For message monitoring. Log file rotated. For all other cases. Could not establish connection. For all other cases. Connection was terminated. this value signifies a message was posted by a producer. Server was shut down. this value signifies a dynamic topic or queue created for a route. Connection unknown. not_authorized not_connected not_found producer reconnect_active reconnect_unknown rotatelog route shutdown standby terminated TIBCO Enterprise Message Service User’s Guide .Description of Topic Message Properties 445 | Table 78 Event Reason Property Values (Sheet 2 of 2) Event Reason Value maxredelivery_exceeded Description Message has exceeded the maxRedelivery count for the queue. Server in standby mode. 446 | Appendix B Monitor Messages TIBCO Enterprise Message Service User’s Guide . Errors TIBCO Enterprise Message Service User’s Guide .| 447 Appendix C Error and Status Messages This appendix lists all possible error messages that the server can output. These strings can include formatting characters. This appendix is alphabetized by category. These strings represent all instances of the error. Some categories have many error instances. The resolution indicates possible recovery actions that administrators should consider. others have only one. alphabetized by category. as they appear in EMS server code. Description Resolution The description explains the error category in more detail. Key to this Appendix Category The category indicates the general class of error. 448 | Appendix C Error and Status Messages Error and Status Messages Category Description A durable consumer was found in the store file for a route that does not exist On server startup a durable consumer was found in the store file for a route that is not listed in the routes. Make routing changes via administration tools.conf file. This happens if the routes. Resolution Errors Category Description Admin command failed An admin tool or program using the admin API attempted an operation that failed for the given reason. %s: create %s failed: illegal to use wildcard %s [%s]. Resolution Errors TIBCO Enterprise Message Service User’s Guide . parameter or configuration that is causing the failure. The user of the tool or API should examine the error and correct the syntax. %s: create %s failed: not allowed to create dynamic %s [%s]. %s: create %s failed: invalid session id=%d. Discarding durable '%s' for route '%s' because the route does not exist. The admin tool or admin API provides the failure reason. %s: create %s failed: invalid temporary %s [%s]. %s: create %s failed: invalid syntax of %s [%s]. %s: create %s failed: invalid %s [%s]. %s: create %s failed: conflicting zone: existing consumer has a different zone %s: create %s failed: detected duplicate durable subscription [%s] for topic [%s].conf file is manually edited. Change the value of the named parameter to an acceptable value. '%s' requires a string argument. see EMS documentation. SSL username error. no password provided Errors Category Description Resolution Backup server '%s' disconnected Lost connection with the backup fault-tolerant server. Ensure the user is defined to EMS by one of the methods allowed by the user_auth parameter in the main configuration file. Errors TIBCO Enterprise Message Service User’s Guide . Determine if the backup server is running. for information about tibemsd command line parameters. If it is running. The user is either specified by the application or in the SSL certificate. LDAP authentication failed for user '%s'. If the user is defined. Unable to initialize connection. reset the password and try again. Errors Category Description Resolution Bad or missing value for command line parameter An invalid value was supplied for a command line parameter. '%s' requires a positive integer argument.Error and Status Messages 449 | Category Description Resolution Authentication error The EMS server failed to authenticate the user or password. Backup server '%s' disconnected. '%s' requires an integer argument. check for a network partition. status = %d LDAP authentication failed for user '%s'. 450 | Appendix C Error and Status Messages Category Description Resolution Errors Banners and debug traces Banner and debug traces Not applicable %s: Message swapping has been %s Invalid session for route configuration. Invalid routed queue information message. please wait. Created %s transport '%s' Send recover request for routed queue flow stall for queue %s Removing routed topic consumer '%s' License has been activated. [%s@%s]: rejected connect from route: invalid password %s: purged durable '%s' %s: %s %s '%s' permissions on %s '%s': %s %s: create %s failed: durable creation access denied for %s [%s]. Async Recs: max=%d avg=%. only %%s is allowed Allocating sync storage to minimum %s. filter '%s' contains an illegal type substitution character. recovery count = %d Error. Hostname: %s TIBCO Enterprise Message Service User’s Guide . Expired % PRINTF_LLFMT d message%s. Discarded % PRINTF_LLFMT d message%s.2f min=%d Process Id: %d Server activating on failure of '%s'. ldap_search_ext_s(%x. Rendezvous Certified Advisory: %s LDAP response resulting from checking if an entry is a member of a dynamic group:' ignoring route '%s' at '%s'. route user does not exist. %s. %s) Flow Stall Recovery Timer: to recover stall of %s on route from %s. %s. Error and Status Messages 451 | Evaluation Software Notice: remaining uptime is %d hours %d minutes. ignoring '%s' Recovered flow stalled consumer for destination: %s:%s %s: revoked all %s permissions on %s '%s' Error sending routing information to '%s'. line=%d: illegal to specify both '%s' and '%s'. Route Recover Minimum Message Count is %u. Send recover request Skipping recover request. LDAP error: %s Clean all flow stalls for route to server %s: %s %s: shutdown server Reading configuration from '%s'. Search reference: %s Route Recover Interval is %u seconds. %s: Maximum statistics memory set to unlimited Configuration warning: file=%s. message count %d TIBCO Enterprise Message Service User’s Guide . [%s@%s]: rejected connect from route: implicit route already exists LDAP response resulting from getting attributes for group '%s': ldap_parse_reference: %s Storage Location: '%s'. Route connect error: route has no zone setting SS: Deleting existing GMD file. fault tolerant mode not supported on '%s'. Exiting. Initialization failed due to errors with transports.5 times the client heartbeat Server connection timeout should be greater than 3. Commit failed due to prior failure or after fault-tolerant switch. Fault tolerant connection failed. Correct the configuration or startup parameters and restart. can't create loop. Initialization failed. Unable to add admin user into admin group: error=(%d) %s Fault tolerant activation has to be greater than 2x heartbeat Client connection timeout should be greater than 3. Initialization of thread pool failed (%s). Startup aborted. Exiting. Failure initializing storage thread: %s. Initialization failed due to errors in SSL. Initialization failed: database file '%s' not found. Fault tolerant heartbeat has to be greater than 0 Initialization failed due to errors in configuration. Server failed to read configuration. The client application should retry the transaction. Exiting. Resolution Errors TIBCO Enterprise Message Service User’s Guide .452 | Appendix C Error and Status Messages Category Description Resolution Errors Basic initialization failed tibemsd was unable to start. Category Description Commit failed due to prior failure or after fault-tolerant switch A warning message indicating that the commit of a client application's transaction failed either because there were earlier errors when processing this transaction or because the transaction was started on the primary server prior to a fault-tolerant failover.5 times the server heartbeat Fault Tolerant configuration error. Initialization has failed. Resolution Errors TIBCO Enterprise Message Service User’s Guide . If the server's topic definitions are as expected. Configured durable '%s' differs from durable in storage. storage version used.Error and Status Messages 453 | Category Description Resolution Compaction failed Compaction of the store file failed.db file or administratively delete the durable and re-define it. Please shutdown and restart tibemsd Errors Category Description Configured durable differs from stored one The durables configuration file specifies a durable with a given name and client identifier with attributes that are different from the identically named durable found in the meta. The most likely cause of this error is running out of memory. this statement can be ignored or remove the ROUTE_DEBUG trace specification to prevent printing. Compaction failed (%s). Correct the durables configuration file to match the durable defined in the meta. This only is printed when the trace includes ROUTE_DEBUG.db file. Shut down tibemsd and see remedies for Out of memory. Resolution Errors Category Description Create of global routed topic failed: not allowed to create dynamic topic A server received an interest notification from another server that does not match the allowed topics in its configuration. Create of global routed topic failed: not allowed to create dynamic topic [%s]. Invalid destination for message. Persisted message possibly corrupt. Resolution Errors Category Description Resolution Errors Database record damaged An error occurred reading one of the tibemsd store files. Inconsistency restoring routed message. Category Description Duplicate message detected Warning generated when tibemsd receives a message with a message id that matches another message's message id. Detected duplicate %s message. otherwise the warning can be ignored. No destination information for consumer. messageID='%s' Resolution Errors TIBCO Enterprise Message Service User’s Guide . Only seen when message id tracking is enabled. Server failed to recover state. Add the specified queue or a pattern that includes it to this daemon if you want the queue to be accessible from this daemon. Create of routed queue failed: not allowed to create dynamic queue [%s]. Send details of the error and the situation in which it occurred to TIBCO Support.454 | Appendix C Error and Status Messages Category Description Create of routed queue failed: not allowed to create dynamic queue A warning indicating that a tibemsd with a route to this daemon has a queue configured to be global but this daemon does not permit the creation of that queue dynamically. line=%d: Ignoring durable. line=%d: ignoring transport '%s' in %s list. line=%d: both tibrv_export and tibrvcm_export are specified. line=%d: Ignoring durable. line=%d: invalid certificate file name. line=%d: value of db_pool_size too big or less than allowed minimum. reset to default Configuration error: file=%s. Configuration error: file=%s. line=%d: illegal to specify prefetch=none for global or routed queue.route. Prefetch reset to default. Configuration warning: file=%s. line=%d: ignoring invalid max connections in the line. line=%d: route '%s' does not have a user configured for authorization. transport not found Configuration error: file=%s. unknown extension or invalid encoding specification Configuration error: file=%s. selector or nolocal. use route property instead. reset to unlimited Configuration error: file=%s. Configuration error: file=%s. SSL Configuration error: file=%s. line=%d: unable to create %s '%s': invalid destination name. invalid parameters or out of memory Configuration error: file=%s. ignoring tibrv_export Configuration error: file=%s. line=%d: value of %s out of range. line=%d: ignored alias '%s' for %s '%s' because such alias already exists Configuration error: file=%s. Configuration error: file=%s. name cannot start with $sys. route does not allow clientid.Error and Status Messages 455 | Category Description Error in configuration file The server encountered an invalid configuration statement in the specified configuration file on the specified line. line=%d: multiple bridge entries for the same destination '%s' are not allowed. Examine the appropriate configuration file and correct the syntax error. line=%d: illegal to specify exclusive for routed queue Configuration warning: file=%s. Resolution Errors TIBCO Enterprise Message Service User’s Guide . line=%d: Rendezvous transport not specified for Rendezvous CM transport '%s' Configuration error: file=%s. reset to default value of %d bytes Configuration error: file=%s. Ignoring msg_pool_block_size. Configuration error: file=%s. unable to process Configuration error: file=%s. line=%d: invalid certificate file name. line=%d: ignored route '%s' because route represents route to this server. ignoring tibrv_import Configuration error: file=%s. line=%d: duplicate value TIBCO Enterprise Message Service User’s Guide . line=%d: ignored alias '%s' for factory because such alias already exists Configuration error: file=%s. Configuration error: file=%s. Resetting value store_minimum_sync to 8M. line=%d: ignored route '%s' because route with such name or URL already exists. Configuration error: file=%s. line=%d: specified value below allowable minimum. reset to default value of %d SSL Configuration error: file=%s. line=%d: value of msg_pool_size invalid or too big or less than allowed minimum of %d. error=%s Configuration error: file=%s. line=%d: duplicate specification of transport type Configuration error: file=%s. Configuration error: file=%s. line=%d: invalid private key file name.456 | Appendix C Error and Status Messages Configuration error: file=%s. line=%d: client_trace error: %s Configuration error: file=%s. line=%d: value of max_msg_memory less than allowed. line=%d: Illegal to specify routed queue as a bridge source Configuration error: file=%s. line=%d: unable to process selector in route parameters. line=%d: ignoring invalid topic selector specifications in route parameters Configuration error: file=%s. line=%d: %s Configuration error: file=%s. reset to %dMB Configuration error: file=%s. Configuration error: file=%s. Resetting value store_minimum to 8M. Configuration error: file=%s. line=%d: specified value below allowable minimum. unknown extension or invalid encoding specification Configuration error: file=%s. line=%d: ignored route '%s' because route has invalid zone information. unknown extension or invalid encoding specification Configuration conflict: file=%s. line=%d: bridge has no targets. line=%d: both tibrv_import and tibrvcm_import are specified. line=%d: value of msg_pool_block_size already set at line=%d. Configuration error: file=%s. line=%d: Ignoring durable. line=%d: invalid property value Configuration error: file=%s. line=%d: failed to create ACL entry. line=%d: Ignoring durable. line=%d: Ignoring durable. name is invalid. Configuration error: file=%s. Configuration error: file=%s. Configuration error: file=%s. duplicate of earlier entry. Configuration error: file=%s. Configuration error: file=%s. line=%d. line=%d: invalid boolean property value Fault tolerant reread error: file=%s. unable to proceed. name is missing or invalid. line=%d: invalid property value Fault standby lock check error: file=%s. line=%d: Ignoring durable. Configuration error: file=%s. unable to proceed. reason=%s Unable to export message to SmartSockets. Error=%s Configuration error: file=%s. line=%d: invalid property value exit_on_nonretryable_disk_error: file=%s.Error and Status Messages 457 | Configuration error: file=%s. line=%d: ignoring duplicate transport name '%s' in %s list Configuration error: file=%s. topic is invalid. line=%d: error in the bridge description. line=%d: errors in line. line=%d: ignoring duplicate user TIBCO Enterprise Message Service User’s Guide . Use fsync error: file=%s. line=%d: Unable to create destination defined by the bridge source Unable to create Rendezvous Certified transport '%s' because it references undefined Rendezvous transport '%s' Configuration error: file=%s. line=%d: error in permissions Configuration error: file=%s. some options may have been ignored Error: unable to add bridge specified in file=%s. line=%d: invalid property value Use fsync (min disk) error: file=%s. line=%d: Ignoring durable. line=%d: error in the transport description. line=%d: ignoring duplicate %s '%s' specified earlier Configuration error: file=%s. line=%d: ignored unknown permission '%s' Configuration error: file=%s. topic is missing or invalid. line=%d: ignoring invalid reconnect attempt count Configuration error: file=%s. line=%d: ignoring errors in permission line Configuration error: file=%s. line=%d: ignoring invalid value in the line Configuration error: file=%s. line=%d: illegal to use predefined name %s Configuration error: file=%s. line=%d: ignoring invalid connect attempt timeout Configuration error: file=%s. line=%d: ignoring user out of group context Configuration error: file=%s. line=%d: ignoring invalid line Configuration error: file=%s. line=%d: ignoring unrecognized property '%s' Configuration error: file=%s. line=%d: ignoring invalid connect attempt delay Configuration error: file=%s. line=%d: ignoring invalid reconnect attempt delay Configuration error: file=%s. line=%d: invalid value of db_pool_size. line=%d: ignoring invalid ft reconnect timeout in the line Configuration error: file=%s. reset to default of %d bytes Configuration error: file=%s. line=%d: ignoring invalid reconnect attempt timeout Configuration error: file=%s. line=%d: ignoring invalid ft activation in the line Configuration error: file=%s. line=%d: ignoring invalid ft heartbeat in the line Configuration error: file=%s. line=%d: ignoring invalid line: invalid syntax in the line Configuration error: file=%s. line=%d: ignoring invalid entry syntax Configuration error: file=%s. line=%d: ignoring unknown property '%s' Configuration error: file=%s. line=%d: invalid line syntax or line out of order TIBCO Enterprise Message Service User’s Guide . line=%d: ignoring invalid line in route parameters Configuration error: file=%s. line=%d: ignoring invalid value of %s Configuration error: file=%s. line=%d: Invalid clientid value Configuration error: file=%s. line=%d: invalid line syntax or line out of order Configuration error: file=%s. line=%d: ignoring invalid line in factory parameters Configuration error: file=%s. line=%d: ignoring invalid disk stat period Configuration error: file=%s. line=%d: ignoring invalid factory load balancing metric Configuration error: file=%s. line=%d: ignoring invalid connect attempt count Configuration error: file=%s.458 | Appendix C Error and Status Messages Configuration error: file=%s. line=%d: multiple targets specified. Configuration error: file=%s. line=%d: invalid value of route_recover_count. line=%d: invalid value of reserve_memory. line=%d: invalid property value Configuration error: file=%s. line=%d: invalid value of %s. line=%d: invalid transport parameter '%s' Configuration error: file=%s. line=%d: invalid value of route_recover_interval. unable to continue. line=%d: invalid property value. reset to no minimum. line=%d: invalid syntax of %s. Configuration error: file=%s. Configuration error: file=%s. line ignored TIBCO Enterprise Message Service User’s Guide . reset to unlimited Configuration error: file=%s. ignoring it Configuration error: file=%s. line=%d: multiple principals specified. line=%d: invalid value of %s. line=%d: invalid value of max memory. reset to default Configuration error: file=%s. line=%d: maximum number of listen interfaces reached. line ignored Configuration error: file=%s. reset to default. line=%d: invalid trace_client_host value Configuration error: file=%s. line=%d: multiple targets specified. reset to 256MB Configuration error: file=%s. Configuration error: file=%s. reset to default %d Configuration error: file=%s. line=%d: line too long. line=%d: invalid value of %s. line=%d: invalid value '%s' Configuration error: file=%s. line=%d: invalid value of max_msg_memory. reset to unlimited Configuration error: file=%s. reset to zero Configuration error: file=%s. line ignored Configuration error: file=%s. line=%d: invalid value. line=%d: Invalid selector value Configuration error: file=%s. line=%d: invalid value of '%s' Configuration error: file=%s. line=%d: invalid value of %s Configuration error: file=%s. reset to unlimited Configuration error: file=%s.Error and Status Messages 459 | Configuration error: file=%s. line=%d: invalid transport type '%s' Configuration error: file=%s. line ignored Configuration error: file=%s. line=%d: invalid password Configuration error: file=%s. SSL Configuration error: file=%s. unable to create Rendezvous transport Configuration error: file=%s. line=%d: ignoring rvcmlistener. Configuration error: file=%s. SSL Configuration error: file=%s. line=%d: duplicate value SSL Configuration error: file=%s. line=%d: ignoring rvcmlistener. line=%d: invalid value of DH key size. too long Configuration error: file=%s. invalid destination Configuration error: file=%s. Configuration warning: file=%s. line=%d: %s '%s' not found Configuration error: No topic exists for configured durable '%s%s%s'. first token is invalid Configuration error: file=%s. line=%d: invalid property value SSL Configuration error: file=%s. reset to 16MB Configuration error: file=%s. line=%d: ignoring invalid line in route parameters: invalid zone type. line=%d: invalid renegotiate size value TIBCO Enterprise Message Service User’s Guide . line=%d: no valid user or group found in acl entry Configuration conflict: file=%s. line=%d: no target found in acl entry Configuration error: file=%s. SmartSockets file '%s' not found. duplicate Configuration error: file=%s.460 | Appendix C Error and Status Messages Configuration error: file=%s. line=%d: ignoring invalid line in route parameters: zone name exceeding %d bytes Routing Configuration error: file=%s. wildcards are not permitted SmartSockets configuration directory name is too long. third token is invalid Configuration error: file=%s. line=%d: Overriding value of msg_pool_size already set at line=%d. line=%d: ignoring rvcmlistener. line=%d: parameter '%s' is deprecated Configuration error: file=%s. line=%d: invalid property value Configuration warning: file=%s. line=%d: out of memory. line=%d: ignoring rvcmlistener. line=%d: no permissions found in acl entry Configuration error: file=%s. second token is invalid Configuration error: file=%s. line=%d: ignoring rvcmlistener. line=%d: value of reserve_memory too small. line=%d: ignoring rvcmlistener. errors already occurred in this transaction.db. Configuration error: file=%s. line ignored Topic '%s' not valid in configured durable '%s'. Category Description Error writing commit request. line=%d: value is invalid or less than minimum %d. minimum is %d (in seconds) Configuration error: file=%s. Zone '%s' is defined as type '%s' in configuration but also is defined as type '%s' in meta. minimum is %dKb SSL Configuration error: file=%s. Resolution Errors TIBCO Enterprise Message Service User’s Guide . ignoring Configuration error: file=%s. line=%d Configuration error: Store definition failed Error occurred writing store definition into file. line=%d: value of %s less than allowed minimum of %dKB. reset to 0 Configuration error: file=%s. reset to unlimited Configuration error: Invalid line: file=%s. line=%d: invalid renegotiate value. Examine previous error statements to determine the cause of the operation failure and correct that before attempting the transaction again. line=%d: user '%s' not found. line=%d: syntax error in the line. line=%d Configuration error: Invalid store parameter: file=%s. reset to 0 Configuration error: file=%s. line=%d: invalid renegotiate size value. errors already occurred in this transaction A client application's attempt to commit a transaction failed because the server encountered an error during an operation associated with the transaction.Error and Status Messages 461 | SSL Configuration error: file=%s. line=%d: Unrecognized attribute Configuration error: file=%s. line=%d: syntax errors in line. ignoring Configuration error: file=%s. line=%d: value less than allowed minimum. line=%d Configuration error: Missing store header: file=%s. Error writing commit request. Check that the user that started the tibemsd has permission to change the configuration files and that there is sufficient disk space on the device. I/O error occurred saving group information I/O error occurred saving bridge information I/O error occurred saving group information I/O error occurred saving route information I/O error occurred writing into file '%s' Resolution Errors TIBCO Enterprise Message Service User’s Guide . Error occurred writing route into file. Error occurred writing group '%s' into file Error occurred writing into the file '%s'. Error occurred saving acl information Error occurred saving bridges information Error occurred saving durables information Error occurred saving factories information Error occurred saving file '%s' Error occurred saving group information Error occurred saving %s information Error occurred saving main configuration file '%s' Error occurred saving routes information Error occurred saving tibrvcm information Error occurred while updating main configuration file '%s'. Error occurred writing destination '%s' into file Error occurred writing factory into file. Error occurred writing bridges into file. Configuration has not been saved.462 | Appendix C Error and Status Messages Category Description Error writing configuration file tibemsd was unable to update one of its configuration files following a configuration change. Exception writing transaction rollback record: %s. %s. Failed writing purge state for queue '%s': I/O error or out of disk space. Exception trying to create confirm record. %s. Exception trying to export message to RV.Error and Status Messages 463 | Category Description Resolution Error writing to store file tibemsd was unable to write data to one of its store files. Exception trying to create valid messages record. Exception trying to create ack record. Failed writing block data to '%s': %s Failed writing message to '%s': I/O error or out of disk space. Exception writing transaction commit record: %s. Failed writing purge state for topic consumer: I/O error or out of disk space. %s. Exception writing transaction begin record: %s. Errors TIBCO Enterprise Message Service User’s Guide .conf file to a port that is not in use. %s. Exception trying to create message from store: %s Exception trying to create transaction record. Errors Category Description Resolution Failed to open TCP port tibemsd was unable to open the tcp port. Ensure that the directory containing the store files is mounted and accessible to the tibemsd. Exception writing transaction prepare record: %s. Failed writing message to '%s': %s. Binding connection to TCP port %d failed:%d (%s). Shutdown process that is using the port or change the value of the 'listen' parameter in the server's tibemsd. and that there is free space available on the device Error writing xa prepare request. Unable to preallocate async storage file '%s'. I/O error occurred reading from the file '%s'. Fault Tolerant error. the file is not being used by another tibemsd or some other process. Failed to create file '%s' failed to open file '%s'. I/O error occurred reading from the file '%s'. error '%s'. Unable to open store file '%s'. Unable to open metadata file '%s'. Fault tolerant reconnect timeout is set to a large value of %d seconds. file may be locked. Check that the path name is correct and the directory exists. Failed to rename file %s into %s: %s Unable to open metadata file '%s'. Exiting on non-retryable disk error: %d Errors TIBCO Enterprise Message Service User’s Guide . failed to open log file '%s'. can't create connection to '%s'. error '%s'. Unable to preallocate sync storage file '%s'. the user that started tibemsd has permission to read the specified directory and path. Consider reducing the timeout unless it is important that the newly active server maintains state for clients that do not reconnect following a failover. file may be locked. Failed to read message from store. Errors Category Description Resolution File access error tibemsd was unable to open the specified file. Configuration file '%s' not found.464 | Appendix C Error and Status Messages Category Description Resolution Fault tolerant reconnect timeout is set to a large value of %d seconds Warning that fault tolerant reconnect timeout is set to a large number of seconds. Unable to open store file '%s'. the file exists if it isn't one that the tibemsd can create. Unable to handle transacted data message. error=%s. Error bridging transacted data message. '%s'. Send the error statement and a description of the environment to TIBCO Support. Error processing xa commit request. %s. Unable to process sequence for message. Unable to initialize fault tolerant connection. %s. **Error** unable to process message. Problem trying to recover routed consumer for queue %s: setting recover message.transaction marked ROLLBACKONLY. error = %s Admin user not found during initialization Asynchronous producer is sending a message into non-failsafe destination. Error processing xa rollback request. Error processing xa prepare request. remote server returned '%s' Unable to process producer message. Unable to create internal session Problem setting flow stall recover message on route queue:%s: %s Failed to handle connection init: %s. Unable to handoff connection init message: %s. Category Description Resolution Errors Internal error that should be status-driven The server detected an internal consistency. %s. '%s'. failed to add sender name. Unable to send recover ack on flow stall: %s Handling of route flow stall recovery request from %s failed: unable to get message property %s: %s TIBCO Enterprise Message Service User’s Guide . Error decoding sequence data in route ack response. This is not yet supported.Error and Status Messages 465 | Exception trying to read message from store. Error decoding sequence data in xa rollback request. Error: %s Failed to send the flow stall recover request: %s. %s. Error processing xa end . 466 | Appendix C Error and Status Messages Handling of route flow stall recovery request failed: Unable to get message properties:%s Failed to send acknowledge to the stall recover request of server %s. Exception restoring persisted message. exiting. status: %s unable to create recovered connection id=% PRINTF_LLFMT d. Exception trying to initialize route. '%s'. Exception creating zone. Failure processing system request. will try later. Failure queuing message to add to dead queue: %s. Failure discarding topic overflow: %s. Exception trying to process message from store. Error: %s failed to send recover ack on stalled flow: invalid consumer unable to create recovered connection. Exception sending session init response Exception sending queue acknowledge response Exception trying to initialize connection. Failure queuing message for removal from system: %s. Failure verifying uniqueness of routed message: %s. Failure bridging incoming message: %s. Failure processing transaction message. Exception creating session. can't send response. TIBCO Enterprise Message Service User’s Guide . Exception creating zone: adding zone to state. Exception sending flow recover acknowledge Exception sending routing information to %s. Exception preparing message for client send. Exception in startup. Exception trying to initialize connection. %s. Exception trying to process message. status: %s Exception creating purge record. Failure queuing incoming message for processing: %s. Invalid listen specification: '%s'. Category Description Invalid connection Warning indicating that tibemsd was attempting to reestablish delivery of messages across a route to another tibemsd but was unable to find the connection for that route. %s: create %s failed: Not permitted to use reserved queue [%s]. %s: %s failed: illegal to use wildcard %s [%s]. Recovery flow stall for destination %s failed: invalid route connection Resolution Errors Category Description Resolution Errors Invalid destination An application is attempting to use a destination name that is not valid. Invalid request to create temporary destination. Either reduce the tibemsd's memory requirement by consuming messages or removing messages from its queues. Alter application code to use an acceptable destination name. or increase the amount of memory available to the tibemsd by shutting down other processes on the machine or increasing the machine's memory. Category Description Resolution Invalid listen specification The server could not parse the listen parameter in the tibemsd. Exception adding message write context: %s. Errors TIBCO Enterprise Message Service User’s Guide .Error and Status Messages 467 | Failure scheduling message hold release: %s. %s: %s failed: %s [%s] not configured.conf file Correct the listen parameter to match the form [protocol]://[url] as specified in the manual. Invalid session in rollback request. Category Description LDAP error . Invalid session in recover request. ldap_url_parse failed. Unable to destroy session. Filter '%s' contains an illegal type substitution character.468 | Appendix C Error and Status Messages Category Description Resolution Errors Invalid session tibemsd received a request that referred to a session that doesn't currently exist. max allowed is: %d Filter '%s' too long. returned: %d Lookup of group '%s' produced incorrect or no results Missing LDAP URL Resolution Errors TIBCO Enterprise Message Service User’s Guide . only %%s is allowed Filter '%s' contains too many occurrences of %%s. Invalid session in commit transaction record.should always display LDAP error An attempt to authenticate a client's userid and password using the external LDAP server failed. Examine the error code printed by the messaging server and consult the manual for the external LDAP server. max length is %d characters Invalid search scope: %s LDAP Configuration error: file=%s. Cannot find session for ack Cannot find session for ack range %s: destroy %s failed: invalid session id=%d. Invalid session in xa start request. Invalid session in commit request. Invalid session in xa end request. Send details of the error and the situation in which it occurred to TIBCO Support. invalid session. line=%d: invalid property value LDAP is not present LDAP search resulted %d hits. Cannot find transaction referred to in commit request. Errors Category Description Resolution Errors Missing configuration An essential attribute has not been configured. Category Description Missing transaction A client application attempted to change the state of a transaction that the tibemsd does not have in its list of current transactions. Cannot find transaction referred to in commit transaction record. Cannot find transaction referred to in xa commit request.conf file so that a value for the attribute is provided. Configuration error with storage databases. if not then check the client code to see if it or its transaction manager are calling the transaction operations in the correct order. Change the tibemsd. License violation: %s. Check tibemsd trace logs to see if the transaction had been committed or rolled back by an administrator. This error only occurs with the evaluation version of the server or in an embedded form. TIBCO Enterprise Message Service User’s Guide Resolution Errors . Cannot find transaction referred to in rollback transaction record. Cannot find transaction referred to in prepare request. Configuration error with metadata database. To correct this error either replace your evaluation version with a production version or contact the vendor who supplied the embedded version.Error and Status Messages 469 | Missing %s parameter Zero entries returned from getting attributes for group '%s': Failed adding user '%s' into LDAP user cache Category Description Resolution LICENSE WARNING The server detected a violation of its license. Cannot find transaction referred to in rollback request. Cannot process xa end for non-existent transaction. %s trying to recreate persistent message. Received prepare request for transaction already prepared. %s '%s': out of memory Resolution Errors TIBCO Enterprise Message Service User’s Guide . Cannot find transaction referred to in xa rollback request. check the operating system limits on the server process to determine if this is the cause. can not create routed queue consumer Unable to create admin group: out of memory during initialization Error: unable to create alias for %s '%s': no memory Error: unable to create alias: out of memory Unable to create import event for %s '%s' on transport '%s' Unable to create internal connection. line=%d. error=(%d) %s Unable to create internal connection: out of memory during initialization Error: unable to create %s '%s': no memory Error: unable to create route while parsing file=%s.470 | Appendix C Error and Status Messages Cannot find transaction referred to in xa prepare request. Error during routed queue configuration. If there are sufficient memory and swap space. Unable to create SmartSockets subscriber on transport '%s'. can not create routed queue consumer Could not initialize monitor Error: out of memory processing admin request Error during route configuration. Compare this with how much memory and swap space the host actually has. reduce the load on this server by moving some topics and queues to another server. If the limits are set to their maximum and this error occurs. Category Description Out of memory The server failed to allocate memory as it was attempting to perform an operation. Check how much memory the server process is using according to the operating system. Cannot find transaction referred to in xa start request. %s to create message from store. No memory generating dynamic route durable. Out of memory: unable to process SS message type on export No memory for creating connection. No memory. out of memory Failed to create reserve memory. Out of memory processing %s on %s '%s' Out of memory processing administrative request Out of memory processing message tracing TIBCO Enterprise Message Service User’s Guide . Fault Tolerant configuration. Out of memory while parsing bridges file Out of memory while parsing factories file Out of memory while parsing routes file No memory performing routing operation. Out of memory importing SS message No memory in IO thread to create pool. Failed writing message to '%s': No memory for operation. no memory! Fault Tolerant error.Error and Status Messages 471 | Unable to create temporary destination. LDAP initialization failed. Unable to process message imported on transport '%s'. No memory authenticating user '%s' No memory authenticating via LDAP Out of memory while building admin response message Out of memory while building JNDI response message Out of memory creating global import event on transport '%s' Out of memory creating import event for %s '%s' on transport '%s' Out of memory creating SS transport %s No memory creating stalled flows in destination Out of memory during initialization Out of memory exporting SS message. no memory. Exiting. TIBCO Enterprise Message Service User’s Guide . No memory to create client connection No memory to create configured durable '%s%s%s'. No memory to extract routing info from incoming message. No memory trying to create message producer. No memory to create consumer. No memory trying to add message to dead queue. Out of memory restoring routed consumer Out of memory sending monitor message. No memory trying to cleanup route. No memory to restore held message from store. No memory trying to add message to system. No memory trying to create global topic destination.472 | Appendix C Error and Status Messages No memory processing purge record. No memory to create destination for message. No memory to create connection. No memory sending queue acknowledge response. No memory to create message from store. No memory to create configured durables No memory to create confirm record. No memory to create destination for consumer or browser. No memory to finish restoring message from store. No memory to restore routed message from store. No memory to create destination for producer. No memory trying to create destination. No memory while processing route interest Out of memory processing transports Out of memory processing transports configuration Out of memory reading configuration. No memory sending topic routing information. No memory to create ack record. Error and Status Messages 473 | No memory to create producer. No memory trying to create routed tmp queue destination. No memory to create session. No memory restoring valid sequence number info. No memory trying to create transaction. No memory trying to initialize connection. No memory to create valid messages record. No memory trying to process system request. No memory trying to create queue browser. No memory trying to parse configured durable. No memory to process route interest No memory to process SSL renegotiation request. No memory trying to process data message. No memory to create transaction record. No memory trying to export message to SS. No memory trying to import message from RV%s. No memory trying to export message to RV. No memory trying to create response message. No memory trying to import message from RVCM. No memory trying to create tmp destination for consumer. No memory trying to process queue message. No memory to create zone. No memory trying to process topic consumer. No memory trying to process xa end. No memory trying to import message from SS. TIBCO Enterprise Message Service User’s Guide . No memory trying to process topic message. No memory trying to initialize route connection. No memory to create routed consumer No memory to create routed queue consumers No memory trying to create routed queue destination. Out of memory queuing imported message for processing. Out of memory preparing to write message. will try again. Out of memory creating RV gateway thread list. TIBCO Enterprise Message Service User’s Guide . Out of memory preparing message for writing. no memory. Out of memory assembling list of message to store. No memory trying to setup queue route configuration No memory trying to setup route configuration No memory trying to setup topic route configuration Route recovery of destination %s on route from %s will fail: No memory Route recovery of destination %s on route from %s will fail: No memory to create timer Route recovery of destination %s on route from %s will fail: %s Failed to initialize OpenSSL environment: out of memory Exception trying to create ack record for prepared transaction. No memory trying to recover routed consumer. No memory trying to send recover/rollback response. Out of memory creating connection thread list. No memory trying to recover route stall. Out of memory creating SmartSockets gateway thread list. No memory to restore prepared transactions. No memory trying to retrieve for queue browser. Out of memory gathering consumers for incoming message. Out of memory processing route consumer. Exception trying to create ack record. No memory to restore messages. no memory. out of memory trying to send topic interest to routes No memory to set clientID for connection.474 | Appendix C Error and Status Messages No memory trying to read message from store. No memory trying to send recover/rollback response. No memory trying to recover route stall. Error and Status Messages 475 | Out of memory delaying bridged flow control response. Category Description Protocol error. Incorrect xid in xa end request. This error is most likely caused by an external transaction manager that allowed two separate client applications to use the same XA transaction identifier (XID). incorrect XID in XA request The tibemsd received an XA End instruction from the third party Transaction Manager which referred to a different transaction from the one currently in use by the session. Cannot process xa start for a session when another transaction is already active on that session Cannot process xa start with TMNOFLAGS when the transaction is already active. Out of memory delaying set of flow control responses. Resolution Errors TIBCO Enterprise Message Service User’s Guide . Out of memory delaying one flow control response. Out of memory trying to delete held message. transaction in incorrect state A client application's attempt to start an XA transaction failed because the transaction already exists and is not in the correct state. Out of memory trying to clear message hold. Report this to the your Transaction Manager vendor. Out of memory preparing to delay flow control response. Resolution Errors Category Description Protocol error. Consult the manual for the transaction manager or report this to the transaction manager vendor. invalid consumer Unable to server the flow stall recover request from server %s. Invalid xid in xa start request. Invalid xid in xa end request. Unable to confirm session. invalid request. Invalid xid in xa prepare request. Invalid destination information for producer. Invalid xid in prepare request. Unable to recover consumer. Invalid xid in rollback request. Unable to init session. Invalid request to delete temporary destination. Invalid flag in xa start request. Unable to recover consumer. invalid client request. invalid request. Invalid xid in xa rollback request.476 | Appendix C Error and Status Messages Category Description Resolution Errors Protocol message format error tibemsd received a message with either missing or incomplete data. Unable to serve the flow stall recover request from server %s. Unable to unsubscribe consumer. Invalid flag in xa end request. Invalid xid in commit transaction record. invalid request. Invalid xid in xa commit request. Invalid request to delete temporary destination: not owner connection. invalid consumer. TIBCO Enterprise Message Service User’s Guide . Unable to process msg for export. invalid request. Unable to start consumer. Unable to create consumer. Send details of the error and the situation in which it occurred to TIBCO Support. Invalid xid in rollback transaction record. invalid session. invalid destination. %s: %s failed: illegal to use %s [%s] in standby mode. Invalid xid in commit request. Invalid client connect detected. To activate a change of the server listen parameter requires a restart of the server. Reconfigure the client to connect to a fully licensed tibemsd. Category Description Protocol sequence error A non-embedded java client is attempting to connect to a tibemsd that is part of an embedded JMS environment. Received unexpected message type %d No destination in incoming data message. Resolution Errors Category Description Rejected attempt to connect via SSL to TCP port A client application attempted to connect to the server's TCP port using the SSL protocol. Problem decoding sequence data in xa end. Rejected attempt to connect via SSL to TCP port Resolution Errors TIBCO Enterprise Message Service User’s Guide . Problem decoding sequence data in rollback. %s:%s queue browser failed: queue name is missing in request message Received admin request with replyTo not set Received JNDI request with replyTo not set. No closure.Error and Status Messages 477 | Malformed routed message Problem decoding sequence data in confirm. Change the client application's URL from ssl to tcp or change the server's listen parameter from tcp to ssl. Rejected attempt to connect via TCP to SSL port Resolution Errors Category Description Rejected connect from route: invalid cycle in route The multi-hop route support of the server does not support configuring a cycle. See Rendezvous documentation for details of what the error means and how to remedy it. it detected a configuration that would create a cycle. Resolution Errors Category Description Resolution Rendezvous transport error tibemsd encountered a Rendezvous error. Remove one of the routes that creates the cycle. To activate a change of the server listen parameter requires a restart of the server.478 | Appendix C Error and Status Messages Category Description Rejected attempt to connect via TCP to SSL port A client application attempted to connect to the server's SSL port using the TCP protocol. [%s@%s]: rejected connect from route: invalid cycle in route: %s Illegal. route to '%s' creates a cycle. Terminate the connection Illegal. Unable to confirm RVCM message. %s Unable to create dispatcher for import event for %s '%s' on transport '%s'. error is %s Unable to create inbox for import event for %s '%s' on transport '%s' Unable to create Rendezvous Certified transport '%s': %s Unable to create Rendezvous Certified transport '%s' because unable to create Rendezvous transport '%s' Unable to create Rendezvous transport '%s': %s Unable to create TIBCO Rendezvous Certified Listener for %s '%s' on transport '%s': %s Errors TIBCO Enterprise Message Service User’s Guide . Change the client application's URL from tcp to ssl or change the server's listen parameter from ssl to tcp. However. route to '%s' creates a cycle. Zone change not allowed while there are durable subscribers. but now %s type %s. error=%s. Error code: %d '%s' Category Description Restoring consumer failed Seen when tibemsd starts up and detects that the zone for a route as specified in routes. Error code: %d '%s' Unable to stop the CM Listener for %s '%s' (RVCM Transport '%s'). error='%s' Unable to restart the CM Listener for %s '%s' (RVCM Transport '%s'). Unable to pre-register certified listener '%s' on transport '%s': %s Rendezvous send failed on transport '%s'. Either delete the route or change its zone back and restart the tibemsd.conf has been changed. Please delete the route first and create new one. Error code: %d '%s' Unable to create the timer for the restart of the CM Listener for %s '%s' (RVCM Transport '%s'). Restoring consumer failed: Conflicting zone for route to [%s]: The route was initially zone %s type %s. Failed to disallow Rendezvous Certified Message listener '%s': %s Unable to export topic message. Resolution Errors TIBCO Enterprise Message Service User’s Guide . Unable to handoff confirm RVCM message: %s.Error and Status Messages 479 | Failed to confirm RVCM message: %s. Failed to convert reply subject '%s'.480 | Appendix C Error and Status Messages Category Description Running on reserve memory Warnings indicating that the tibemsd has run out of memory and is now using its reserve memory Either reduce the tibemsd's memory requirement by consuming messages or removing messages from its queues. or increase the amount of memory available to the tibemsd by shutting down other processes on the machine or increasing the machine's memory. error=%d Unable to import SmartSockets message on transport %s: failed to convert reply subject '%s'. Pending msg count = %d Pending msg count = %d Resolution Errors Category Description Resolution SmartSockets transport error tibemsd encountered a SmartSockets error. Status=%s Unable to confirm SS message. ignoring new message. error=%s.%s Errors TIBCO Enterprise Message Service User’s Guide . See SmartSockets documentation for details of what the error means and how to remedy it. %s Unable to connect to SmartSockets RTserver via transport: '%s': %d . Unable to create SmartSockets subscriber on transport '%s': failed to convert %s '%s'. error=%s. Error translating EMS message body into SS message. error=%s Unable to export EMS message into SmartSockets on transport '%s'. no more send requests accepted. Status=%s Error translating EMS message properties into SS message. Running on reserve memory. Running on reserve memory. Status=%s Error translating EMS message headers into SS message. error=%s Unable to import SmartSockets message on transport %s: failed to convert subject '%s'. Unable to export EMS message into SmartSockets on transport '%s'. Failed to convert subject '%s'. error='%s'. GMD seq=%d TIBCO Enterprise Message Service User’s Guide .%s Unable to create open callback on transport: '%s': %d . '%s' SS Unsubscribe failed: for '%s' on transport '%s' SS error: %s GMD delivery failed on transport '%s'. can not register EMS message.%s Unable to import SmartSockets message on transport %s: failed to retrieve SS subject. '%s' SmartSockets TipcSrvConnFlush failed. can not add to undelivered EMS queue.Error and Status Messages 481 | Unable to register GMD failure callback: '%s': %d . Error=%d. reason='%s' for process '%s' Unable to process undelivered SS GMD message. Unable to import SS message. '%s' SmartSockets TipcMsgSetLbMode failed.%s Unable to create SS callback for %s '%s' on transport '%s' SS error: %s Unable to create SS message type on export Unable to create SmartSockets subscriber for %s '%s' on transport '%s'. error retrieving delivery mode. Failed to create SmartSockets transport %s Unable to handoff confirm SS message: %s. tport='%s'. tport='%s'. %s. Unable to import SS message. SS message seq=%d. error='%s'. error: %s Unable to create SmartSockets transport '%s': %d . error retrieving number of fields.%s Unable to set SS message type on export Unable to set Username/Password for SmartSockets transport '%s': %d . GMD seq=%d Unable to process undelivered SS GMD message. '%s' SmartSockets TipcSrvConnMsgSend failed. Unable to initialize SmartSockets transport '%s': error=%d: %s Unable to set SmartSockets Dispatcher for transport: '%s': %d . Unable to import SS message. SS Subject CB destroy Failed: for '%s' on transport '%s' SS error: %s SS Subject CB lookup Failed: for '%s' on transport '%s' SS error: %s SmartSockets TipcMsgSetDeliveryMode failed.%s Failed to confirm SS message. Failed to process ft ssl password Failed to process ssl password Ignoring SSL listen port %s Failed to initialize SSL: can not load certificates and/or private key and/or CRL file(s) Failed to initialize OpenSSL environment: error=%d. tport='%s'. failed to build EMS message. tport='%s'. Please check per-process and system-wide limits on the number of open files. Errors Category Description Resolution System call error. error='%s'. Failed to initialize SSL: server private key not specified. Client connection not created. Examine the OpenSSL error and the EMS User's Guide chapter describing the use of SSL. %s. Report the error to your system administrator and ask them to remedy the problem. Accept() failed: too many open files. should be errno-driven A low-level system function has failed. error='%s'. message=%s. Could not obtain hostname Errors TIBCO Enterprise Message Service User’s Guide . GMD seq=%d Category Description Resolution SSL initialization failed The server failed attempting to initialize the OpenSSL library.482 | Appendix C Error and Status Messages Unable to process undelivered SS GMD message. Accept() failed: %d (%s) Cannot retrieve user name of the current process. Error=%s Failed to initialize SSL: unable to obtain password Failed to initialize SSL: server certificate not specified. GMD seq=%d Unable to convert undelivered SS GMD message into EMS message. Failed to initialize SSL. Category Description Resolution Errors Unnecessary or duplicate message tibemsd received a message with either missing or incomplete data.Error and Status Messages 483 | Could not resolve hostname '%s'. Unable to open socket for listening: %d (%s). Unable to listen for connections: %d (%s). Errors TIBCO Enterprise Message Service User’s Guide . Possibly default hostname is not configured properly while multiple network interfaces are present. %s. Run the server with the -help option and compare it with the command line containing the unrecognized option. %s. Send details of the error and the situation in which it occurred to TIBCO Support. Unrecognized option: '%s'. Error trying to enter standby for '%s'. Error processing xa start request. Category Description Resolution Unrecognized option The server's command line contains an unrecognized option. 484 | Appendix C Error and Status Messages TIBCO Enterprise Message Service User’s Guide . Customer agrees to pay TIBCO for any Maintenance or Services provided by TIBCO related to a breach of the foregoing on a time. (d) use the Software for purposes of providing a service bureau. License Grant. statement of work or other work-request document incorporating the term of this End User License Agreement (each. decompile. Customer agrees not to (a) make more copies than the Number of Units plus a reasonable number of backups. negligence. new versions and/or new releases of the Software provided from time to time under Maintenance shall be used only as replacements to existing copies. or (e) is used in violation of any other term of this End User License Agreement. Upon your acceptance as indicated above. While TIBCO continues to own the Software. or commercially share the Software or any of Customer's rights under this Agreement (for the purposes of the foregoing a change in control of Customer is deemed to be an assignment). without limitation. and TIBCO provides Customer no warranty with respect to such Software. Maintenance Fees for lapsed Maintenance or the changing of the level of Maintenance shall be mutually agreed upon between Customer and TIBCO. misuse. reverse engineer. EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY. modify. TIBCO reserves the right to make changes only to the most currently available version. the following shall govern your use of the Software except to the extent all or any portion of the Software (a) is subject to a separate written agreement. IF YOU DO NOT AGREE TO THESE TERMS. and use thereof shall be governed by the terms of this Agreement. Upgrades. or refund of the Software and applicable Maintenance fees. non-transferable. if the Software is being provided for demonstration. Customer shall designate at TIBCO's support website https://support. (c) has not been installed. Fees for Services shall be due and payable in United States dollars net 30 from the date of TIBCO's invoice. or any similar services. repaired. travel. distribute to any third party. rent. Limited Warranty. End User License Agreement READ THIS END USER LICENSE AGREEMENT CAREFULLY. including. and (c) that such use shall automatically terminate upon the earlier of thirty days from the date Customer receives the right to install the Software. bug fixes. The Software is the property of TIBCO or its licensors and is protected by copyright and other laws.tibco. (b) that the Software will not be used or deployed in a production or development environment. or consultants under written contract with Customer agreeing to be bound by terms at least as protective of TIBCO as those in this End User License Agreement ("Authorized Users"). Thereafter Maintenance will be automatically renewed for successive one (1) year terms at the then current rates. decrypt. disassemble. If Customer obtained the Software directly from TIBCO. repair. and other expenses reasonably incurred in connection therewith. then TIBCO warrants that for a period of thirty (30) days from the Purchase Date: (i) the media on which the Software is furnished will be free of defects in materials and workmanship under normal use. or third-party application integration or application service provider-type services. or any activity for which failure of the Software might result in death or serious bodily injury to Customer or a third party. (b) deemed accepted upon delivery. and (ii) the Software will substantially conform to its Documentation. contractors. (d) has been subjected to abnormal physical or electrical stress. at TIBCO's option. TIBCO will use reasonable efforts to support the previously released version of the Software for a maximum of six months. This limited warranty extends only to the original Customer hereunder. and shall not be deemed to increase the Number of Units. title and intellectual property or other right or interest therein. If Customer obtained the Software from a TIBCO reseller or distributor. make error corrections to. in machine-readable. in which event this End User License Agreement shall terminate upon refund thereof. a "Work Order"). (e) use the Software in connection with ultrahazardous activities. all Services and any work product therefrom shall be (a) performed on a time and materials basis. or by a separate mutually executed work order. Customer's sole and exclusive remedy and the entire liability of TIBCO and its licensors under this limited warranty will be. Each contact may contact TIBCO for problem resolution during TIBCO's published support hours corresponding to the level of Maintenance purchased. Services. the number of authorized contacts as permitted by TIBCO based on the level of Maintenance purchased (contacts are changeable upon 48-hours prior written notice to TIBCO). evaluation. providing third-party hosting. or accident. or (f) directly or indirectly. including all right. notwithstanding that each shall be construed to incorporate all applicable provisions of this End User License Agreement. lease. Unless otherwise expressly agreed to in a Work Order.com/eSupport/newuser. transfer. or evaluation purposes. the terms of any warranty shall be as provided by such reseller or distributor. BY DOWNLOADING OR INSTALLING THE SOFTWARE. End User License Agreement | 485 TIBCO Software Inc. object code form and solely for Customer's internal business use. YOU AGREE TO BE BOUND BY THIS AGREEMENT. THE SOFTWARE. TIBCO hereby grants to Customer a limited. except by TIBCO. materials. (b) has been altered or modified. pledge. TIBCO shall provide support for generally available Software ("Maintenance") on an annual basis commencing on the Purchase Date. Customer may request additional services ("Services") either in an Ordering Document. (c) sublicense. except for the first paragraph of the Limited Warranty and any right of return or refund. assign. Beta and Evaluation Licenses. in whole or in part. and (c) exclusively owned by TIBCO (except for Confidential Information of Customer). TIBCO shall use reasonable efforts to correct or circumvent the problem according to its published maintenance objectives. Technical Support. (b) provide access to the Software to anyone other than employees. This warranty does not apply to any Software which (a) is licensed for beta. lodging. Each Work Order is intended to constitute an independent and distinct agreement of the parties. DO NOT DOWNLOAD OR INSTALL THE SOFTWARE AND RETURN IT TO THE VENDOR FROM WHICH IT WAS PURCHASED. Restrictions. travel. or Customer's receipt of notice of termination from TIBCO. enhancements. or maintained in accordance with instructions supplied by TIBCO. Provided Customer has paid applicable support fees (not included with Software fees unless separately listed). beta testing.html. non-exclusive. in which case the terms of such addenda shall control over inconsistent terms with regard to such portion(s). create derivative works based on. testing or demonstration purposes for which TIBCO does not receive a license fee. replacement. plus meals. Upon notice from a contact of a Software problem which can be reproduced at a TIBCO Maintenance facility. or (b) is provided by a third party under the terms set forth in an Addenda at the end of this Agreement. then Customer agrees (a) to use the Software solely for such purposes.TIBCO Software Inc. operated. Notwithstanding the foregoing. patches. lodging and other reasonable expenses basis. or otherwise attempt to discover the source code or underlying ideas or algorithms of the Software. MAINTENANCE AND SERVICES ARE PROVIDED "AS TIBCO Enterprise Message Service User’s Guide . license to use the Number of Units set forth in the Ordering Document. translate. If the Customer is an agency. To the extent required by law. EXEMPLARY OR ANY SIMILAR TYPE DAMAGES ARISING OUT OF THIS AGREEMENT. INCIDENTAL. Customer agrees to observe obligations of confidentiality with respect to such information. concepts or processes utilized in provided software or related documentation. or any copyright. THE ABOVE LIMITATION MAY NOT APPLY TO CUSTOMER. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES. (ii) rightfully received from a third party not in breach of any obligation of confidentiality. release. Government Use. on payment of TIBCO's applicable fee. and any modification thereto. or other entity of the United States Government ("Government"). (iii) independently developed by one party without use of the Confidential Information of the other. BUSINESS INTERRUPTION. and any methods. SPECIAL. Export. disclosure or transfer of the Software. or any related documentation of any kind. and refund to Customer the unamortized portion of the license fees paid to TIBCO by Customer based on a five-year straight-line depreciation. then TIBCO agrees at its own expense to defend or. TIBCO has the exclusive right to control such defense and/or settlement. TIBCO Enterprise Message Service User’s Guide . Except with respect to the Software. EXCEED THE PRICE PAID BY CUSTOMER UNDER THE APPLICABLE ORDERING DOCUMENT. "Confidential Information" means the terms of this End User License Agreement. EVEN IF A PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. WHETHER IN CONTRACT. BREACH OF WARRANTY. EXCEPT AS PROVIDED UNDER INDEMNITY OR RESULTING FROM A BREACH OF CONFIDENTIALITY (THE "EXCLUDED MATTERS"). including technical data or manuals. duplication. export control laws. MAINTENANCE OR SERVICES WILL MEET CUSTOMER'S REQUIREMENTS. NO WARRANTY IS MADE REGARDING THE RESULTS OF ANY SOFTWARE. CERTAIN THIRD PARTY SOFTWARE MAY BE PROVIDED TO CUSTOMER ALONG WITH CERTAIN TIBCO SOFTWARE AS AN ACCOMMODATION TO CUSTOMER. SATISFACTORY QUALITY OR ARISING FROM A COURSE OF DEALING. provided that TIBCO is promptly notified in writing of such claim. ALL EXPRESS OR IMPLIED CONDITIONS. or any trade secret of a third party. THE USE OR THE INABILITY TO USE THE SOFTWARE. OR TRADE PRACTICE. MAINTENANCE OR SERVICES OR THAT THE SOFTWARE WILL OPERATE WITHOUT ERRORS.7202 for military agencies. Canada. re-export. This Section states the entire liability of TIBCO with respect to the infringement of any intellectual property rights. Japan. is subject to U. or import Software. NONINFRINGEMENT. Use of the Software and related documentation by the Government is further restricted in accordance with the terms of this Agreement. Limitation of Liability. Australia. Software. If Confidential Information is communicated orally. litigation or threat thereof. or any member of the European Union. TORT (INCLUDING ACTIVE OR PASSIVE NEGLIGENCE). related documentation or related performance test results derived by Customer. TIBCO may cancel this End User License Agreement upon sixty days prior written notice to Customer. any provided software. department. all information marked by the disclosing party as proprietary or confidential. The Software is commercial computer software and commercial computer software documentation. CONSEQUENTIAL. OR THAT ERRORS OR BUGS IN THE SOFTWARE WILL BE CORRECTED. WITHOUT LIMITATION. costs and fees reasonably incurred (including reasonable attorneys' fees) that are attributable to such claim or action and which are assessed against Customer in a final judgment. CUSTOMER MAY CHOOSE NOT TO USE THIRD PARTY SOFTWARE PROVIDED AS AN ACCOMMODATION BY TIBCO. IN NO EVENT WILL EITHER PARTY OR TIBCO'S LICENSORS BE LIABLE FOR ANY LOST DATA. TIBCO. at Customer's request. In the event of any such claim. DISTRIBUTOR. The parties agree to protect the Confidential Information of the other in the same manner it protects the confidentiality of similar information and data of its own (and at all times exercising at least a reasonable degree of care). DAMAGE TO REPUTATION. OR ANY OTHER INDIRECT. any claim or action brought against Customer to the extent it is based on a claim that the unmodified Software infringes any patent issued by the United States. OR THAT THE SOFTWARE'S FUNCTIONALITY. at its sole option and expense. or (v) produced in compliance with applicable law or court order.486 | TIBCO Software Inc. Such damages shall include reasonable expenses incurred in seeking both legal and equitable remedies. reproduction. ARE HEREBY EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE LAW. EXTENSIONS OR ADDITIONS TO THIS WARRANTY. REPRESENTATIONS. Export Administration Act and its associated regulations. PUNITIVE. AGENT OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS. THIS THIRD PARTY SOFTWARE IS PROVIDED "AS IS". Indemnity. In no event shall Customer settle any claim. EXCEPT FOR THE EXCLUDED MATTERS. and TIBCO will indemnify and hold Customer harmless from and against any damages. including the U. (iv) known to the recipient at the time of disclosure (other than under a separate confidentiality obligation). NO TIBCO DEALER. provided the other party is given reasonable notice of the same. to settle. CLAIMS BY THIRD PARTIES OR OTHERWISE. action or proceeding without TIBCO's prior written approval. ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY. THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF ITS ESSENTIAL PURPOSE. Customer agrees to comply strictly with all such regulations and agrees to obtain all necessary licenses to export. AND WARRANTIES INCLUDING. shall (a) procure for Customer the right to continue to use the Software or (b) replace or modify the Software with functionally equivalent software. The foregoing indemnity shall not apply to the extent any infringement could have been avoided by use of the then-current release. is restricted in accordance with Federal Acquisition Regulation ("FAR") 12. including technical data.S. and Customer hereby expressly waives any other liabilities or obligations of TIBCO with respect thereto. Both parties agree to indemnify the other for any damages the other may sustain resulting from their unauthorized use and/or disclosure of the other's Confidential Information. and may be subject to export or import regulations in other countries. TIBCO shall provide Customer with the interface information needed to achieve interoperability between the Software and another independently created program.S. such communication shall be confirmed as "Confidential" in writing within thirty days of such disclosure. LOST PROFITS. OR THE PROVISION OF ANY MAINTENANCE OR SERVICES. Confidential Information shall remain the sole property of the disclosing party and shall not be disclosed to any non-Authorized User of either TIBCO or Customer without the prior written consent of the disclosing party. IN NO EVENT SHALL A PARTY BE LIABLE TO THE OTHER. End User License Agreement IS". at its option. If such settlement or modification is not commercially reasonable (in the reasonable opinion of TIBCO). modification. If Customer obtained the Software from TIBCO directly. FITNESS FOR A PARTICULAR PURPOSE. and Customer shall provide reasonable assistance (at TIBCO's expense) in the defense thereof. Confidentiality.212 for civilian agencies and Defense Federal Acquisition Regulation Supplement ("DFARS") 227. PROBLEMS OR INTERRUPTIONS. USAGE. the use. items will not be deemed Confidential Information if (i) available to the public other than by a breach of an agreement with TIBCO. LOST REVENUE. "Processor Source Locked" means the number of connections to a single database made possible by (or licensed for) the relevant TIBCO Software regardless of how many Processors are used by the system or environment which is accessing the database. the remaining provisions of this Agreement shall remain in full force and effect. Fees on the Ordering Document (all to be paid on the latter of thirty days from Invoice by TIBCO or the date set forth in the Ordering Document) do not include sales. In connection with this End User License Agreement the following capitalized terms shall have the following meaning: "Connection" means for TIBCO SmartSockets and TIBCO SmartMQ. if applicable. "License Type" means the environment in which the TIBCO Software may be used (including without limitation. and test environments. cold back-up.TIBCO Software Inc. oral or written. for any other amounts coming due hereafter. No delay in the performance of any obligation by either party. Platform and Unit. Customer may terminate this End User License Agreement in its entirety at any time by destroying all copies of the Software. consumption. hot standby. description of Services. which is not processing live data. Customer hereby agrees to provide TIBCO. as well as the sections entitled "Confidentiality". Except as set forth in the Section entitled "Limited Warranty" all fees paid under or in connection with this End User License Agreement are non-refundable and no right of set-off exists. unless countersigned by an officer of TIBCO. Term and Termination. upon ten days prior written notice. at which time. "Limited Warranty" and "Limitation of Liability" shall survive any such termination. Maintenance or Services. "Developer" means a Named User of a TIBCO Software product for use only in Non-Production. unless expressly superseded by a signed written agreement between the parties. and all other representations. Non-Production environments include development. Customer's obligation to pay accrued charges and any fees due as of the date of termination. not necessarily named at the time of a license grant. within sixty (60) days after the end of the Enterprise Term. regardless of whether or not the individual is actively using the TIBCO Software at any given time. This End User License Agreement shall be governed by and construed in accordance with the laws of the State of California. excepting all obligations to make payment. An Ordering Document shall be deemed accepted only by issuance of a TIBCO invoice and solely for purposes of administrative convenience. Customer must cease using and return or destroy all copies of the Software. (c) by either party upon prior written notice at least ninety (90) days prior to the end of any annual Maintenance term. "MSU" means Millions of Service Units per hour. (b) upon the filing for bankruptcy or insolvency of the other party. Customer hereby grants TIBCO and its independent auditors the right to audit Customer's compliance with this End User License Agreement. for any reason. All payments of fees due shall be made in U. "Processor" means a central processing unit ("CPU") on which the TIBCO Software is licensed to run and which for the purposes of counting Processors on multicore chips. the Number of Units then deployed in Production and Non-Production use by Customer becomes fixed and Customer may not thereafter deploy additional Units. Authority. and such delivery shall be deemed complete when the Software is made available for download by Customer. high availability. negotiations and undertakings relating to the subject matter hereof. dollars. withholding. value-added or similar taxes. and that Customer agrees to be bound by this End User License Agreement. net 30 from TIBCO's invoice. and Customer agrees to pay all sales. which is not running any operations of the Customer and which has not been deployed to permit any users to access live data. "Documentation" means text material that accompanies the TIBCO Software on delivery. regardless of any statement on any Ordering Document to the contrary. or. "Named User" means an identifiable individual. Upon termination of this End User License Agreement in its entirety. statements. deployed by Customer for a period of one (1) year (unless otherwise set forth in an Ordering Document) from the Effective Date (the "Enterprise Term"). Number of Units. "Production" means an operational environment into which the licensed TIBCO Software has been installed. and including. switches. If any portion hereof is found to be void or unenforceable. A service charge of one and one-half percent per month will be applied to all invoices that are not paid on time. which is processing live data and which has been deployed so that the intended users of the TIBCO Enterprise Message Service User’s Guide . and supersedes all proposals. the number of Processors is the number of CPUs times the number of cores multiplied by . firmware or hardware.. "Customer" means the original purchaser or licensee of the Software and any permitted successors and assigns. any network protocol link established with such Software (directly or indirectly) to any other entity. or in an Ordering Document. "Platform" means the operating system set forth in an Ordering Document. General. based on the then current MSU rating established by IBM for IBM and IBM compatible hardware which is used for software pricing (not necessarily a direct indication of relative processor capacity) as set forth in IBM's generally available Large System Performance Reference. as reported by Licensee upon expiration of a Project or Enterprise Term. All orders of Software. Definitions. use.75. "Non-Production" means a non-operational environment into which the TIBCO Software may be installed. with written notice of the Number of Units deployed at the end of the Enterprise Term by License Type. The United Nations Convention on Contracts for the International Sale of Goods is excluded from application hereto. If any portion of this End User License Agreement is found to be void or unenforceable. "Connected Processor" means a Processor that produces information or messages consumed by the relevant Software (excluding Processors on devices such as routers. the remaining provisions shall remain in full force and effect. This Agreement constitutes the entire agreement between the parties with respect to the use of the Software. withholding. exclusive of TIBCO's income tax. During the Enterprise Term. is acquired by. Customer's right to deploy an unlimited Number of Units does not extend to any entity which acquires. shall constitute a breach of this End User License Agreement to the extent caused by force majeure. Maintenance or Services by Customer to TIBCO shall be deemed to occur with or without reference to. use. net 30 from Purchase Date. value-added. End User License Agreement | 487 Orders. United States of America.S. Termination of Maintenance or Services shall not terminate this End User License Agreement. under the terms of this End User License Agreement. Maintenance and Services. Software shall be delivered electronically. Maintenance or Services may be terminated: (a) by either party upon a default of the other. merged into. "Enterprise" means an unlimited Number of Units of the TIBCO Software set forth in an Ordering Document. level of Maintenance. as if performed wholly within the state and without giving effect to the principles of conflict of law. goods and services. None of the terms of the Ordering Document (other than the Software product name. or otherwise combined with Customer. designated by Customer to access the TIBCO Software. or (d) by Customer (for Services). including but not limited to software. HTTP or application servers configured to substantially pass-through information or messages to TIBCO Software). excise and any other similar taxes or government charges. proxies. Production. such default remaining uncured for fifteen days from written notice from the non-defaulting party. Non-Production). and fees due in connection therewith) shall apply for any reason or purpose whatsoever. You hereby represent and warrant that you have full power and authority to accept the terms of this End User License Agreement on behalf of Customer. "Ordering Document" means any purchase order or similar document or agreement requesting Software. Customer agree to pay all reasonable costs incurred (including reasonable attorneys' fees) in collecting past due amounts. "Number of Units" means the cumulative number of copies of TIBCO Software licensed for use by type of Unit as set forth in this Agreement. 30 Copyright© 1999-2003 The OpenLDAP Foundation. ITS CONTRIBUTORS. "Purchase Date" means the date of the Ordering Document is accepted by TIBCO. California. within sixty (60) days after the end of the Project Term. Processor. BUT NOT LIMITED TO. merged into. "Unit" means a license restriction describing the manner in which a copy (or multiple copies) of the TIBCO Software may be deployed (including. STRICT LIABILITY. EXEMPLARY. and may not be used or accessed by any other TIBCO Software. including its Documentation. DATA. TIBCO InConcert bundles TIBCO Rendezvous). End User License Agreement environment are able to access the live data. OR PROFITS. (b) that TIBCO BusinessPartner be used solely to communicate with Customer's implementation of TIBCO BusinessConnect. the provision of which by TIBCO is made solely as an accommodation and in lieu of Customer purchasing a license to Third Party Software directly from the third party vendor. and to provide TIBCO the names thereof (with an address and contact name) within sixty days of the end of each quarter. Version 5. LOSS OF USE.0. OR THE AUTHOR(S) OR OWNER(S) OF THE SOFTWARE BE LIABLE FOR ANY DIRECT. TIBCO BusinessPartner: Customer may sublicense to third parties ("Partners") up to the total Number of Copies of TIBCO BusinessPartner. INCIDENTAL. Connected Processor. Customer hereby agrees to provide TIBCO. and (c) for such Partner to direct all technical support and Maintenance questions directly to Customer. All Rights Reserved. to be deployed by Customer solely in connection with the undertaking described under an Ordering Document for a period of one (1) year (unless otherwise set forth in this Agreement) from the Effective Date (the "Project Term"). OpenLDAP 2. to any third party any rights to or immunities under TIBCO's intellectual property or proprietary rights in the TIBCO Software. Customer agrees to keep records of the Partners to which it distributes TIBCO BusinessPartner. "Trading Partner" means an entity or individual with which the Licensee engages in electronic commerce by means of TIBCO Software in accordance with this Agreement. BUT NOT LIMITED TO. and Processor Source Locked) and is the mechanism used to determine the Number of Units licensed pursuant to an Ordering Document.4.3 This product includes zlib software.1. Use of such embedded or bundled TIBCO Software is solely to enable the functionality of the TIBCO Software licensed on the Cover Page. October 2006 Third Party Software Notices Java Secure Socket Extension (JSSE) 1. the Number of Units then deployed in Production and Non-Production use by Customer becomes fixed and Customer may not thereafter deploy additional Units.3 This product includes code licensed from RSA Security. EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. obligations of use with respect to the TIBCO Software. Inc. SPECIAL. THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS CONTRIBUTORS `ÀS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES. in whole and in part. at which time. provided that for every such sublicense. the TIBCO Software or any modifications thereto to become subject to the terms of the GPL. "Project" means an unlimited Number of Units for the License Type listed in this Agreement. Customer's right to deploy an unlimited Number of Units does not extend to any entity which acquires. copyright 1995–2003 Jean-loup Gailly and Mark Adler. WHETHER IN CONTRACT. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES. such Partner agrees in writing (a) to be bound by terms and conditions at least as protective of TIBCO as the terms of this Agreement. Embedded/Bundled Products. THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. "Third Party Software" means third-party software identified by its company and/or product name. IN NO EVENT SHALL THE OPENLDAP FOUNDATION. Some TIBCO Software embeds or bundles other TIBCO Software (e. OR CONSEQUENTIAL DAMAGES (INCLUDING. or otherwise combined with Customer. Customer must ensure that its use does not: (i) create. is acquired by.2. "Server Instance" means a computer with 1 CPUs (unless otherwise specified in the Agreement) performing common services for multiple other machines. USA. During the Project Term. or could be interpreted or asserted to cause. and provided further that prior to delivery of TIBCO BusinessPartner to a Partner. OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY. Redwood City. ADDENDA: Third Party License Agreements TIBCO Enterprise Message Service User’s Guide .. or (ii) grant. without limitation. INDIRECT. INCLUDING. zlib 1. OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE. Open Source Software: If Customer uses Open Source software in conjunction with the TIBCO Software. You also may not combine the TIBCO Software with programs licensed under the GNU General Public License ("GPL") in any manner that could cause.488 | TIBCO Software Inc. or for any other purpose. with written notice of the Number of Units deployed at the end of the Project Term by Unit and License Type. the Number of Copies Customer is licensed to use shall be reduced by the same number. Special Product Provisions. or purport to grant. "Software" means the most current generally available object code version (as of the Purchase Date) of the software products listed in an Ordering Document (except as provided for beta or evaluation licenses). Named User. or purport to create.g. OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE. both the conditions of the OpenSSL License and the original SSLeay license apply to the toolkit. If this package is used in a product. For written permission. 3. INDIRECT. STRICT LIABILITY. Redistributions in binary form must reproduce the above copyright notice. this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.com)" THIS SOFTWARE IS PROVIDED BY ERIC YOUNG `ÀS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES.openssl. Redistribution and use in source and binary forms. lhash.org/)" 4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: "This product includes software written by Tim Hudson (tjh@cryptsoft. OR CONSEQUENTIAL DAMAGES (INCLUDING. Redistribution and use in source and binary forms.. OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY. EXEMPLARY.com).com).Third Party Software License Agreements | 489 Third Party Software License Agreements The following are the software licenses for the Third Party Software provided in connection with the software. are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice. EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. please contact openssl-core@openssl. INDIRECT.9. Actually both licenses are BSD-style Open Source licenses. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES. this list of conditions and the following disclaimer. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT. BUT NOT LIMITED TO. WHETHER IN CONTRACT. with or without modification. OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT.com). not just the SSL code. etc. (eay@cryptsoft. All rights reserved. LOSS OF USE. All advertising materials mentioning features or use of this software must display the following acknowledgement: "This product includes cryptographic software written by Eric Young (eay@cryptsoft. INCLUDING. 2.openssl. 5. All rights reserved. i. BUT NOT LIMITED TO. DATA. See below for the actual license texts. OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY. Redistributions in binary form must reproduce the above copyright notice. be it the RC4. Eric Young should be given attribution as the author of the parts of the library used. THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. The implementation was written so as to conform with Netscapes SSL. Original SSLeay License Copyright (C) 1995-1998 Eric Young (eay@cryptsoft. BUT NOT LIMITED TO. 6. This library is free for commercial and non-commercial use as long as the following conditions are aheared to. This can be in the form of a textual message at program startup or in documentation (online or textual) provided with the package. Redistributions of source code must retain the copyright notice. SPECIAL. RSA.com).8c The OpenSSL toolkit stays under a dual license. Open SSL v2/v3 0. and as such any Copyright notices in the code are not to be removed. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. OpenSSL License Copyright (c) 1998-2006 The OpenSSL Project. EXEMPLARY.com). Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www. This product includes software written by Tim Hudson (tjh@cryptsoft. are permitted provided that the following conditions are met: 1. DES. The SSL documentation included with this distribution is covered by the same copyright terms except that the holder is Tim Hudson (tjh@cryptsoft. this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 3. EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.org. The following conditions apply to all code found in this distribution. with or without modification. OR PROFITS.com)" The word 'cryptographic' can be left out if the rouines from the library being used are not cryptographic related :-). WHETHER IN CONTRACT. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. INCIDENTAL. This package is an SSL implementation written by Eric Young (eay@cryptsoft. this list of conditions and the following disclaimer. Copyright remains Eric Young's. STRICT LIABILITY. BUT NOT LIMITED TO. SPECIAL.e. (http://www. LOSS OF USE. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES. This product includes cryptographic software written by Eric Young TIBCO Enterprise Message Service User’s Guide .org. OR PROFITS. OR CONSEQUENTIAL DAMAGES (INCLUDING. 4. INCLUDING. code. INCIDENTAL.org/)" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT `ÀS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES. DATA. 2. In case of any license issues related to OpenSSL please contact openssl-core@openssl. Copyright (c) 1999.2001 Hummingbird Communications Ltd. Each revision is distinguished by a version number. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM. OR CONSEQUENTIAL DAMAGES (INCLUDING. Permission to copy and distribute verbatim copies of this document is granted. WHETHER IN CONTRACT. OpenLDAP is a registered trademark of the OpenLDAP Foundation. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. All Rights Reserved. this code cannot simply be copied and put under another distribution licence [including the GNU Public Licence.2000. use or other dealings in this Software without prior written authorization of the copyright holder. California. USA. INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY. Except as contained in this notice. and OSF. Copyright 1999-2003 The OpenLDAP Foundation. EXPRESS OR IMPLIED.2000.] Copyright (c) 1999. Redistributions must contain a verbatim copy of this document. WITHOUT WARRANTY OF ANY KIND. BUT NOT LIMITED TO. and the following disclaimer in the documentation and/or other materials provided with the distribution.2001 Silicon Graphics. The OpenLDAP Foundation may revise this license from time to time. the OSF logo. and Xinerama are trademarks of the Open Group. OpenLDAP 2. modify.2001 Compaq Computer Corporation Copyright (c) 1999.2001 IBM Corporation Copyright (c) 1999. to deal in the Software without restriction. Permission is hereby granted.2000. OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY. Redwood City. THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. Redistributions in binary form must reproduce applicable copyright statements and notices. written prior permission. OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES.2001 Sun Microsystems. X Window System. this list of conditions. and to permit persons to whom the Software is furnished to do so. WHETHER IN AN ACTION OF CONTRACT. OSF/1. and 3. INCLUDING.30 The OpenLDAP Public License Version 2. THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS CONTRIBUTORS `ÀS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES. the name of a copyright holder shall not be used in advertising or otherwise to promote the sale. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES. INDIRECT. Title to copyright in this Software shall at all times remain with copyright holders. Inc. ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.4. Redistributions in source form must retain copyright statements and notices. are permitted provided that the following conditions are met: 1. 17 August 2003 Redistribution and use of this software and associated documentation ("Software"). OR THE AUTHOR(S) OR OWNER(S) OF THE SOFTWARE BE LIABLE FOR ANY DIRECT. to any person obtaining a copy of this software and associated documentation files (the "Software").2000. including without limitation the rights to use. TIBCO Enterprise Message Service User’s Guide . Copyright (c) 1999. copy. free of charge. and/or sell copies of the Software. DATA OR PROFITS. OR PROFITS. You may use this Software under terms of this license revision or under the terms of any subsequent revision of the license. THE SOFTWARE IS PROVIDED "AS IS". Inc. use or other dealing in this Software without specific.2001 The Open Group All rights reserved. OSF/Motif and Motif are registered trademarks. SPECIAL. BUT NOT LIMITED TO.1. provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. 2.1. X Open ICU 1. INCIDENTAL. OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE. ITS CONTRIBUTORS.2000. EXEMPLARY.2001 Hewlett-Packard Company Copyright (c) 1999.2 Source License COPYRIGHT AND PERMISSION NOTICE Copyright (c) 1999.8. STRICT LIABILITY. The names of the authors and copyright holders must not be used in advertising or otherwise to promote the sale.2000. X Window System is a trademark of The Open Group. with or without modification. IN NO EVENT SHALL THE OPENLDAP FOUNDATION. i. DATA. NEGLIGENCE OR OTHER TORTIOUS ACTION. All other trademarks and registered trademarks mentioned herein are the property of their respective owners. distribute.2000. merge. OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE.490 | Third Party Software License Agreements The licence and distribution terms for any publically available version or derivative of this code cannot be changed. EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.e. LOSS OF USE. publish. LBX. in the Source form of any Derivative Works that You distribute. irrevocable copyright license to reproduce. whether by contract or otherwise. and configuration files. publicly display. 4. elaborations. or for any such Derivative Works as a whole. including but not limited to software source code. whether in Source or Object form. non-exclusive. all copyright. source code control systems. within the Source form or documentation. and distribution of the Work otherwise complies with the conditions stated in this License. and distribution as defined by Sections 1 through 9 of this document. Subject to the terms and conditions of this License. You may add Your own attribution notices within Derivative Works that You distribute. and conversions to other media types. provided that such additional attribution notices cannot be construed as modifying the License. and attribution notices from the Source form of the Work. sublicense.org/licenses/ TERMS AND CONDITIONS FOR USE. direct or indirect. publicly perform. that is based on (or derived from) the Work and for which the editorial revisions. import. or written communication sent to the Licensor or its representatives. no-charge. and otherwise transfer the Work.0 and Apache Xerces for Java 2. or merely link (or bind by name) to the interfaces of. or distribution of Your modifications. in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works. "Contribution" shall mean any work of authorship. and (b) You must cause any modified files to carry prominent notices stating that You changed the files.Third Party Software License Agreements | 491 Apache Xalan-Java 2. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form.0. to cause the direction or management of such entity. use. without any additional terms or conditions. trademark. are controlled by. patent. 2. any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License. then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file. made available under the License. 3. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement. AND DISTRIBUTION 1. then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.6. prepare Derivative Works of. Derivative Works shall not include works that remain separable from. royalty-free. "Work" shall mean the work of authorship. Definitions. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use. have made. an original work of authorship. Subject to the terms and conditions of this License. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium. verbal. generated documentation. Grant of Copyright License. each Contributor hereby grants to You a perpetual.2 Apache License Version 2. and in Source or Object form. if and wherever such third-party notices normally appear. provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License. where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. or other modifications represent. reproduction. Grant of Patent License. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. reproduction. or. and (c) You must retain. excluding those notices that do not pertain to any part of the Derivative Works. or are under common control with that entity. as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). within a display generated by the Derivative Works. and issue tracking systems that are managed by. and (d) If the Work includes a "NOTICE" text file as part of its distribution. The contents of the NOTICE file are for informational purposes only and do not modify the License. alongside or as an addendum to the NOTICE text from the Work. or on behalf of. no-charge. that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. and distribute the Work and such Derivative Works in Source or Object form. worldwide. each Contributor hereby grants to You a perpetual. sell. royalty-free. "control" means (i) the power. documentation source. whether in Source or Object form. provided Your use. or (iii) beneficial ownership of such entity. including but not limited to compiled object code. For the purposes of this definition. Unless You explicitly state otherwise. excluding those notices that do not pertain to any part of the Derivative Works. offer to sell. but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution. "Source" form shall mean the preferred form for making modifications.6. annotations. "License" shall mean the terms and conditions for use. Redistribution. reproduction. as a whole. including but not limited to communication on electronic mailing lists. REPRODUCTION. "submitted" means any form of electronic. the Work and Derivative Works thereof. January 2004 http://www. TIBCO Enterprise Message Service User’s Guide . "Derivative Works" shall mean any work.apache. or (ii) ownership of fifty percent (50%) or more of the outstanding shares. Submission of Contributions. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control. the Licensor for the purpose of discussing and improving the Work. For the purposes of this License. non-exclusive. 5. including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof. with or without modifications." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. worldwide. For the purposes of this definition. if provided along with the Derivative Works. irrevocable (except as stated in this section) patent license to make. TIBCO Enterprise Message Service User’s Guide . nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS. However. shall any Contributor be liable to You for damages. either express or implied. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License. defend. including. not on behalf of any other Contributor. copy. While redistributing the Work or Derivative Works thereof.9 Copyright (C) 1998-2002 Daniel Veillard. or product names of the Licensor. subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. and hold each Contributor harmless for any liability incurred by. unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.6.0 (the "License"). trademarks. software distributed under the License is distributed on an "AS IS" BASIS. and only if You agree to indemnify. In no event and under no legal theory. and/or sell copies of the Software. Accepting Warranty or Additional Liability. whether in tort (including negligence). to any person obtaining a copy of this software and associated documentation files (the "Software"). OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. indemnity. contract. You may obtain a copy of the License at http://www. including without limitation the rights to use. attach the following boilerplate notice. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. computer failure or malfunction. or other liability obligations and/or rights consistent with this License. indirect. or any and all other commercial damages or losses). libxml 2.org/licenses/LICENSE-2. 8. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. Disclaimer of Warranty. You may act only on Your own behalf and on Your sole responsibility. NON-INFRINGEMENT. Except as contained in this notice. except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. free of charge. or claims asserted against. DAMAGES OR OTHER LIABILITY. either express or implied. in accepting such obligations. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. sublicense.0 Unless required by applicable law or agreed to in writing. service marks. merge. even if such Contributor has been advised of the possibility of such damages. without limitation. or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill. and to permit persons to whom the Software is furnished to do so. INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY. WITHOUT WARRANTY OF ANY KIND. or otherwise. 6.apache. Limitation of Liability. the name of Daniel Veillard shall not be used in advertising or otherwise to promote the sale. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND. IN NO EVENT SHALL THE DANIEL VEILLARD BE LIABLE FOR ANY CLAIM. to deal in the Software without restriction. acceptance of support. All Rights Reserved. You may choose to offer. 7. with the fields enclosed by brackets "[]" replaced with your own identifying information. THE SOFTWARE IS PROVIDED "AS IS". WHETHER IN AN ACTION OF CONTRACT. distribute. Unless required by applicable law or agreed to in writing. incidental. ARISING FROM. work stoppage. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.492 | Third Party Software License Agreements Notwithstanding the above. MERCHANTABILITY. To apply the Apache License to your work. Permission is hereby granted. Trademarks. any warranties or conditions of TITLE. warranty. use or other dealings in this Software without prior written authorization from him. This License does not grant permission to use the trade names. TORT OR OTHERWISE. or FITNESS FOR A PARTICULAR PURPOSE. and charge a fee for. publish. modify. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND. such Contributor by reason of your accepting any such warranty or additional liability. Version 2. including any direct. special. 9. EXPRESS OR IMPLIED. See the License for the specific language governing permissions and limitations under the License. you may not use this file except in compliance with the License. 264 autocommit command 107 compiling samples 77 compliant_queue_ack parameter 167 compression.db file 394 authorization parameter 167 AUTO_ACKNOWLEDGE mode 37.conf file 203 add member command 106 addprop factory command 106 addprop queue command 106 addprop route command 107 addprop topic command 107 admin connect 108 password 95 user 104 admin user 95 anonymous user and security 95 async-msgs.| 493 Index A acl. 38 client_connection_timeout parameter 198 client_heartbeat parameter 198 client_heartbeat_server parameter 176 client_timeout_server_connection parameter 177 client_trace parameter 185 cm_name parameter 303 commit command 107 compact command 108 .conf file 205 D daemon parameter 302 default_ttl parameter 303 definitions of properties 47 delete all command 112 delete bridge command 112 delete connection command 112 delete durable command 112 delete factory command 112 delete group command 113 delete jndiname command 113 delete message command 113 delete queue command 113 delete route command 113 TIBCO Enterprise Message Service User’s Guide C CLIENT_ACKNOWLEDGE mode 37. message 35 configuring external directory for authentication 235 LDAP 235 connect admin 108 connect command 108 console_trace parameter 184 create bridge command 109 create durable command 109 create factory command 109 create group command 109 create jndiname command 109 create queue command 110 create route command 110 create rvcmlistener command 111 create topic command 111 create user command 111 customer support xxviii B bridges. conf file 215 import queue property 54 topic property 54 .conf file 202 H heartbeat failover and 390 help command 118 F factories.conf file 208 failover and heartbeat 390 failsafe property 47 fault tolerance 11.494 | Index delete rvcmlistener command 114 delete subscriber 112 delete topic command 114 delete user command 114 detailed_statistics parameter 187 disabled security 94 disconnect command 114 DUPS_OK_ACKNOWLEDGE mode 37. 119 durables. 71 ft_activation parameter 178 ft_active parameter 178 ft_heartbeat parameter 178 ft_reconnect_timeout parameter 178 ft_ssl_ciphers parameter 181 ft_ssl_expected_hostname parameter 181 ft_ssl_identity parameter 179 ft_ssl_issuer parameter 179 ft_ssl_password parameter 179 ft_ssl_private_key parameter 179 ft_ssl_rand_egd parameter 180 ft_ssl_trusted parameter 180 ft_ssl_verify_host parameter 180 ft_ssl_verify_hostname parameter 180 E echo command 115 EMS server starting 90 stopping 91 emsntsreg 92 exclusive property 56 exit command 115 expiration property 60 EXPLICIT_CLIENT_ACKNOWLEDGE mode 38 EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE mode 38 explicit_config_only parameter 303 export topic property 55 export property 55 export_headers parameter 304 export_properties parameter 304 G global property 52 grant admin command 117 grant queue command 116 group 235 groups. 411 fault-tolerant URL 209 TIBCO Enterprise Message Service User’s Guide I ibrvcm. 383 fault-tolerant switchover 28.conf file 216 dynamic queues 44 dynamic topics 44 files. 38 durable subscriber 5. 398. sample 76 flow control 71 flow_control parameter 167 flowControl property 53. 118. 277 definition 22. 277 max_connections parameter 174 max_msg_memory parameter 174 max_stat_memory parameter 187 maxbytes property 49 maxmsgs 50 maxmsgs property 50 maxRedelivery property 56 message compression 35 maximum size 23 message listener 38 message pool 175 meta.db file 394 msg_pool_block_size parameter 175 msg_pool_size parameter 175 msg_swapping parameter 174 TIBCO Enterprise Message Service User’s Guide . 288. 68.Index 495 | import property 54 info command 118 inheritance property 66 inheritance of property 44 J JMS_TIBCO_SS_CORRELATION_ID property 342 JMS_TIBCO_SS_DELIVERY_MODE property 342 JMS_TIBCO_SS_EXPIRATION property 342 JMS_TIBCO_SS_LB_MODE property 342 JMS_TIBCO_SS_MESSAGE_ID property 342 JMS_TIBCO_SS_PRIORITY property 342 JMS_TIBCO_SS_SENDER property 341 JMS_TIBCO_SS_SENDER_TIMESTAMP property 342 JMS_TIBCO_SS_SEQ_NUM property 342 JMS_TIBCO_SS_TYPE_NUM property 342 JMS_TIBCO_SS_USER_PROP property 342 ldap_tls_cert_file parameter 194 ldap_tls_cipher_suite parameter 194 ldap_tls_key_file parameter 194 ldap_tls_rand_file parameter 194 ldap_url parameter 192 ldap_user_attribute parameter 195 ldap_user_base_dn parameter 195 ldap_user_class parameter 194 ldap_user_filter parameter 195 ldap_user_scope parameter 195 ledger_file parameter 303 library files 253 linking 253 load balancing 4. 211. 56. 329 load balancing URL 209 log_trace parameter 183 logfile parameter 183 logfile_max_size parameter 184 M L LDAP 235 ldap_all_groups_filter parameter 197 ldap_all_users_filter parameter 196 ldap_cache_enabled parameter 193 ldap_cache_ttl parameter 193 ldap_conn_type parameter 193 ldap_credential parameter 192 ldap_dynamic_group_attribute parameter 198 ldap_dynamic_group_class parameter 197 ldap_dynamic_member_url_attribute parameter 198 ldap_group_base_dn parameter 196 ldap_group_filter parameter 196 ldap_group_scope parameter 196 ldap_principal parameter 192 ldap_static_group_attribute parameter 197 ldap_static_group_class parameter 197 ldap_static_member_attribute parameter 197 ldap_tls_cacert_dir parameter 193 ldap_tls_cacert_file parameter 193 MapMessage 22. 122 password parameter 170 permission secure property and 48 prefetch property 57 properties queue 46 topic 46 property 16 definitions 47 export 55 import 54 inheritance 44. 66 purge all queues command 118 purge all topics command 118 purge durable command 118 S sample files 76 samples compiling 77 secure property 48 secure property and permission 48 security and anonymous user 95 disabled 94 main configuration file 231 sender_name property 52 sender_name_enforced property 53 server starting 90 stopping 91 server parameter 170 server_connection_timeout parameter 199 Q queue import property 54 queue properties 46 queue property list 46 queue_import_dm parameter 304 TIBCO Enterprise Message Service User’s Guide .conf file 203 R O overflowPolicy 50 overflowPolicy property 50 rate_interval parameter 186 remove member command 119 removeprop factory command 119 removeprop queue command 119 removeprop route command 119 removeprop topic command 120 request_old parameter 303 reserve memory 175 reserve_memory parameter 175 revoke topic command 121 rotatelog command 121 round-robin queue (non-exclusive) 56 routes.conf file 206 rv_tport parameter 303 P password admin 95 setting 104.496 | Index N network parameter 302 NO_ACKNOWLEDGE mode 37 No-Acknowledgement Receipt Mode 37 npsend_check_mode parameter 169 queues dynamic 44 static 44 temporary 45 queues. db file 394 TIBCO Enterprise Message Service User’s Guide .Index 497 | server_heartbeat parameter 199 server_heartbeat_client parameter 177 server_heartbeat_server parameter 177 server_rate_interval parameter 186 server_timeout_client_connection parameter 176 server_timeout_server_connection parameter 177 service parameter 302 set password command 122 set server command 123 setprop factory command 128 setprop queue command 128 setprop route command 129 setprop topic command 129 shared storage 391 show bridge command 129 show bridges command 130 show config command 130 show connections command 134 show db command 137 show durable command 137 show factories command 140 show group command 140 show groups command 141 show jndiname command 140 show jndinames command 140 show members command 141 show message command 141 show messages command 141 show parents command 141 show queue command 142 show queues command 143 show route command 144 show routes command 144 show rvcmlisteners command 145 show rvcmtransportledger command 145 show server command 145 show stat command 145 show topic command 146 show topics command 148 show transactions command 149 show transport command 150 show transports command 150 show user command 150 show users command 150 showacl admin command 150 showacl group command 151 showacl queue command 151 showacl topic command 151 showacl user command 152 shutdown command 152 ssl_auth_only parameter 192 ssl_cert_user_specname parameter 189 ssl_crl_path parameter 191 ssl_crl_update_interval parameter 191 ssl_dh_size parameter 188 ssl_password parameter 190 ssl_rand_egd parameter 191 ssl_rand_file parameter 191 ssl_require_client_cert parameter 188 ssl_server_ciphers parameter 188 ssl_server_identity parameter 189 ssl_server_issuer parameter 190 ssl_server_key parameter 190 ssl_server_trusted parameter 191 ssl_use_cert_username parameter 188 starting the EMS server 90 startup_abort_list parameter 170 static queues 44 static topics 44 statistics parameter 186 statistics_cleanup_interval parameter 187 stopping the EMS server 91 store parameter 173 store_minimum parameter 173 subscriber 240 delete 112 durable 118. contacting xxviii sync_ledger parameter 303 sync-msgs. 119 support. conf file 202 trace property 54 trace_client_host parameter 185 track_correlation_ids parameter 181 track_message_id parameter 181 transaction commit command 153 transaction rollback command 153 transports. 108.conf file 212 type parameter 302 U UNIX system using for user authentication 235 updatecrl command 153 url formats 209 user 234 admin 95 externally authenticated 235 user admin 104 user_auth parameter 172 users.conf file 201 W whoami command 153 TIBCO Enterprise Message Service User’s Guide .498 | Index T tcp 79. 257 tibemsd.conf file 157 tibemsMsg_GetStringProperty 279 tibemsMsg_SetBooleanProperty 279 tibrv_transports parameter 182 tibrv_xml_import_as_string parameter 182 tibss_config_dir parameter 183 tibss_transports parameter 182 time command 152 topic export property 55 topic import property 54 topic property list 46 topic_import_dm parameter 304 topics dynamic 44 static 44 temporary 45 topics. 259 technical support xxviii temp_destination_timeout parameter 303 temporary queues 45 temporary topics 45 tibemsd 252.