tib ems dotnet ref
TRANSCRIPT
TIBCO Enterprise Message Service™
.NET ReferenceSoftware Release 4.4November 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 Adapter, Rendezvous 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
| iii
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivTIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivThird Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Excluded Features and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Object Serialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Strings and Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
.NET Compact Framework (CF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 2 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Parts of a Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Body Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Setting Message Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15EMS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15JMS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Message Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Data Type Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Message.Acknowledge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Message.ClearBody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Message.ClearProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Message.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Message.GetDeliveryModeName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Message.Get Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
TIBCO Enterprise Message Service .NET Reference
iv | Contents
Message.PropertyExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Message.Set Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Message.ToString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33BytesMessage.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34BytesMessage.ReadBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36BytesMessage.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37BytesMessage.WriteBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39BytesMessage.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43MapMessage.Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44MapMessage.ItemExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45MapMessage.Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46MapMessage.SetBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50StreamMessage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52StreamMessage.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53StreamMessage.ReadBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54StreamMessage.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55StreamMessage.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56StreamMessage.WriteBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59TextMessage.ClearBody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59TextMessage.Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Message.EmptyEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Message.EmptyEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Message.EmptyEnum.MoveNext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Message.EmptyEnum.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Chapter 3 Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Destination Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
TemporaryQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72TemporaryQueue.Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
TemporaryTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
TIBCO Enterprise Message Service .NET Reference
Contents | v
TemporaryTopic.Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Chapter 4 Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80MessageConsumer.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82MessageConsumer.Receive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83MessageConsumer.ReceiveNoWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
QueueReceiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
TopicSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
EMSMessageHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
EMSMessageEventArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88EMSMessageEventArgs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
IMessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90IMessageListener.OnMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Chapter 5 Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94MessageProducer.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97MessageProducer.Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
QueueSender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100QueueSender.Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
TopicPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103TopicPublisher.Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Chapter 6 Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
QueueRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108QueueRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109QueueRequestor.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110QueueRequestor.Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
TopicRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112TopicRequestor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113TopicRequestor.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114TopicRequestor.Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Chapter 7 Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Connection.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Connection.CreateSession. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
TIBCO Enterprise Message Service .NET Reference
vi | Contents
Connection.Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Connection.Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
QueueConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126QueueConnection.CreateQueueSession. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
TopicConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128TopicConnection.CreateTopicSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
EMSExceptionHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
EMSExceptionEventArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131EMSExceptionEventArgs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
IExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133IExceptionListener.OnException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Chapter 8 Connection Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
ConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138ConnectionFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141ConnectionFactory.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142ConnectionFactory.CreateConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142ConnectionFactory.GetSSLProxyHost. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143ConnectionFactory.GetSSLProxyPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143ConnectionFactory.GetSSLProxyPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143ConnectionFactory.GetSSLProxyUser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143ConnectionFactory.SetCertificateStoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144ConnectionFactory.SetClientID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145ConnectionFactory.SetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146ConnectionFactory.SetConnAttemptCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147ConnectionFactory.SetConnAttemptDelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148ConnectionFactory.SetConnAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149ConnectionFactory.SetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150ConnectionFactory.SetMetric. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151ConnectionFactory.SetReconnAttemptCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152ConnectionFactory.SetReconnAttemptDelay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153ConnectionFactory.SetReconnAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154ConnectionFactory.SetServerUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155ConnectionFactory.SetSSLAuthOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156ConnectionFactory.SetSSLProxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157ConnectionFactory.SetSSLProxyAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158ConnectionFactory.SetSSLTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159ConnectionFactory.SetTargetHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159ConnectionFactory.SetUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160ConnectionFactory.SetUserPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
QueueConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
TIBCO Enterprise Message Service .NET Reference
Contents | vii
QueueConnectionFactory.CreateQueueConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162QueueConnectionFactory.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
TopicConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164TopicConnectionFactory.CreateTopicConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165TopicConnectionFactory.Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
FactoryLoadBalanceMetric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Chapter 9 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Session.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Session.Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Session.CreateBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Session.CreateBytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Session.CreateConsumer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Session.CreateDurableSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Session.CreateMapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Session.CreateObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Session.CreateProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Session.CreateQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Session.CreateStreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Session.CreateTemporaryQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Session.CreateTemporaryTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Session.CreateTextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Session.CreateTopic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Session.Recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Session.Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Session.Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Session.Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
QueueSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
TopicSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
SessionMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Chapter 10 Queue Browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
QueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202QueueBrowser.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204QueueBrowser.GetEnumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205QueueBrowser.MoveNext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206QueueBrowser.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Chapter 11 Name Server Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
ILookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210ILookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
TIBCO Enterprise Message Service .NET Reference
viii | Contents
ILookupContext.Lookup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212ILookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
LookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215LookupContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217LookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218LookupContext.Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219LookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
LookupContextFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221LookupContextFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222LookupContextFactory.CreateContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
LdapLookupConsts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
LdapLookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226LdapLookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227LdapLookupContext.Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228LdapLookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
LdapLookupSSLParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231LdapLookupSSLParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231LdapLookupSSLParams.SetSSLQueryClientCertificateCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232LdapLookupSSLParams.SetSSLVerifyServerCertificateCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Chapter 12 SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
EMSSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236EMSSSL.GetAuthOnly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.GetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.GetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.GetTargetHostName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242EMSSSL.SetAuthOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242EMSSSL.SetCertificateStoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243EMSSSL.SetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244EMSSSL.SetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244EMSSSL.SetTargetHostName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
EMSSSLFileStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246EMSSSLFileStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247EMSSSLFileStoreInfo.ClearTrustedCerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247EMSSSLFileStoreInfo.SetSSLClientIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248EMSSSLFileStoreInfo.SetSSLPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249EMSSSLFileStoreInfo.SetSSLTrustedCertificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
EMSSSLSystemStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251EMSSSLSystemStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252EMSSSLSystemStoreInfo.SetCertificateName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253EMSSSLSystemStoreInfo.SetCertificateStoreLocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
TIBCO Enterprise Message Service .NET Reference
Contents | ix
EMSSSLSystemStoreInfo.SetCertificateStoreName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
EMSSSLHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
EMSSSLHostNameVerifierArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
EMSSSLStoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Chapter 13 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
DeliveryMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
IEMSSerialziable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261IEMSSerialziable.Deserialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262IEMSSerialziable.Serialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
MessageDeliveryMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Tibems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Tibems.CalculateMessageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Tibems.CreateFromBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Tibems.GetAllowCloseInCallback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Tibems.GetAsBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Tibems.GetConnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Tibems.GetConnectAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Tibems.GetConnectionActiveURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Tibems.GetEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Tibems.GetExceptionOnFTSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Tibems.GetMessageEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Tibems.GetMessageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Tibems.GetPingInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Tibems.GetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Tibems.GetReconnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Tibems.GetReconnectAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Tibems.GetSessionDispatcherDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Tibems.GetSocketReceiveBufferSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Tibems.GetSocketSendBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Tibems.MakeWriteable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Tibems.SetAllowCloseInCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Tibems.SetConnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Tibems.SetConnectAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Tibems.SetEncoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Tibems.SetExceptionOnFTSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Tibems.SetMessageEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Tibems.SetPingInterval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Tibems.SetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Tibems.SetReconnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Tibems.SetReconnectAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Tibems.SetSessionDispatcherDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Tibems.SetSocketReceiveBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
TIBCO Enterprise Message Service .NET Reference
x | Contents
Tibems.SetSocketSendBufferSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Chapter 14 Exception. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
EMSException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
AuthenticationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
CannotProceedException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
CommunicationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
ConfigurationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
IllegalStateException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
InvalidClientIDException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
InvalidDestinationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
InvalidNameException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
InvalidSelectorException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
MessageEOFException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
MessageFormatException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
MessageNotReadableException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
MessageNotWriteableException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
NameNotFoundException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
NamingException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
ResourceAllocationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
SecurityException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
ServiceUnavailableException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
TransactionInProgressException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
TransactionRolledBackException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
TIBCO Enterprise Message Service .NET Reference
| xi
Tables
Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Table 2 Syntax Typographical Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Table 3 Feature Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Table 4 EMS Assembly DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Table 5 Message Header Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Table 6 Message Property Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Table 7 Data Type Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 8 BytesMessage Read Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Table 9 BytesMessage Write Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 10 Destination Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
TIBCO Enterprise Message Service .NET Reference
xii | Tables
TIBCO Enterprise Message Service .NET Reference
TIBCO Enterprise Message Service .NET Reference
| xiii
Preface
TIBCO Enterprise Message Service™ software lets application programs send and receive messages according to the Java Message Service (JMS) protocol. It also integrates with TIBCO Rendezvous and TIBCO SmartSockets message products.
Topics
• Related Documentation, page xiv
• Typographical Conventions, page xv
• How to Contact TIBCO Customer Support, page xvii
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.
TIBCO Enterprise Message Service .NET Reference
xiv | Related Documentation
Related Documentation
This section lists documentation resources you may find useful.
TIBCO Enterprise Message Service DocumentationThe 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, its features, and configuration.
• TIBCO Enterprise Message Service Installation Read the relevant sections of this manual before installing this product.
• TIBCO Enterprise Message Service Application Integration Guide This manual presents detailed instructions for integrating TIBCO Enterprise Message Service with third-party products.
• TIBCO Enterprise Message Service C & COBOL API Reference This reference is available in HTML and PDF formats.
• TIBCO Enterprise Message Service Java API Reference This reference is available as JavaDoc, and you can access the reference only through the HTML documentation interface.
• TIBCO Enterprise Message Service .NET API Reference This reference is available in PDF and HTML format.
• TIBCO Enterprise Message Service Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.
Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products:
• TIBCO Rendezvous™ software
• TIBCO SmartSockets™ software
TIBCO Enterprise Message Service .NET Reference
Preface | xv
Third Party Documentation• Java™ Message Service specification, available through
java.sun.com/products/jms/index.html
• Java™ Message Service by Richard Monson-Haefel and David A. Chappell, O’Reilly and Associates, Sebastopol, California, 2001.
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention Use
code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:
Use MyCommand to start the TIBCO foo process.
bold code
font Bold code font is used in the following ways:
• In procedures, to indicate what a user types. For example: Type the username admin.
• In large code samples, to indicate the parts of the sample that are of particular interest.
• In command syntax, to indicate the default value.
italic font Italic font is used in the following ways:
• To indicate a document title. For example: See TIBCO BusinessWorks Concepts for more details.
• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.
• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname
TIBCO Enterprise Message Service .NET Reference
xvi | Typographical Conventions
Key combinations
Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.
Table 1 General Typographical Conventions
Convention Use
Table 2 Syntax Typographical Conventions
Convention Use
[ ] An optional item in a command or code syntax.
For example:
MyCommand [optional_parameter] required_parameter
| A logical ’OR’ that separates multiple items of which only one may be chosen.
For example, you can select only one of the following parameters:
MyCommand para1 | param2 | param3
bold code
font The default parameter.
For example, if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]
{ } A logical group of items. Other syntax notations may appear within each logical group.
For example, the following command requires two parameters, 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. 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, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4.
MyCommand param1 [param2] {param3 | param4}
TIBCO Enterprise Message Service .NET Reference
Preface | xvii
How to Contact TIBCO Customer Support
For comments or problems with this manual or the software it addresses, please contact TIBCO Support Services as follows.
• For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site:
http://www.tibco.com/services/support/default.jsp
• If you already have a valid maintenance or support contract, visit this site:
http://support.tibco.com
Entry to this site requires a username and password. If you do not have a username, you can request one.
TIBCO Enterprise Message Service .NET Reference
xviii | How to Contact TIBCO Customer Support
| 1
Chapter 1 Introduction
This chapter presents concepts specific to the TIBCO Enterprise Message Service™ .NET API and .NET Compact Framework API. For more general information and concepts pertaining to TIBCO Enterprise Message Service (EMS) software, see the TIBCO Enterprise Message Service User’s Guide.
Topics
• Overview, page 2
• Excluded Features and Restrictions, page 3
• Strings and Character Encodings, page 4
• .NET Compact Framework (CF), page 5
TIBCO Enterprise Message Service .NET Reference
2 | Chapter 1 Introduction
Overview
TIBCO Enterprise Message Service .NET API implements (and extends) the JMS 1.1 specification. It is compatible with the JMS 1.0.2 specification.
This implementation consists of fully-managed .NET code.
TIBCO Enterprise Message Service .NET API closely mimics the Java API. This parallelism eases porting of programs between the two programming languages.
The .NET API incorporates .NET-style event handling and enumerated constants (to enable compiler type checking). These features encourage programmers to use a .NET idiom, even while their Java-oriented versions remain available for quick porting.
EMS .NET Compact Framework API brings the power of EMS to any hand-held device or embedded system that supports .NET Compact Framework.
TIBCO Enterprise Message Service .NET Reference
Excluded Features and Restrictions | 3
Excluded Features and Restrictions
This section summarizes features that are not available in either the .NET library, or the .NET Compact Framework library.
Object SerializationThe .NET library supports serialization for all objects. In contrast, the .NET Compact Framework library supports serialization for a restricted set of objects. For details, see ObjectMessage on page 48.
Object serialization differs among the various EMS language APIs in ways that are incompatible. An ObjectMessage contains a serialized object. Therefore EMS programs can only send an ObjectMessage to another program written in the same language; for example, Java to Java, C to C, .NET to .NET, and .NET Compact Framework to .NET Compact Framework. In particular, notice that a .NET Compact Framework client and a full .NET client cannot exchange an ObjectMessage.
Table 3 Feature Support
Feature .NET.NETCompact Framework
XA protocols for external transaction managers — —
ConnectionConsumer, ServerSession, ServerSessionPool — —
Compression Yes —
SSL Yes —
Modify socket buffer sizes (see Tibems.SetSocketReceiveBufferSize on page 302 and Tibems.SetSocketSendBufferSize on page 303).
Yes —
Daemon threads (see Tibems.SetSessionDispatcherDaemon on page 301).
Yes —
TIBCO Enterprise Message Service .NET Reference
4 | Chapter 1 Introduction
Strings and Character Encodings
.NET programs represent strings within messages as byte arrays. Before sending an outbound message, EMS programs translate strings to their byte representation using an encoding, which the program specifies. Conversely, when EMS programs receive inbound messages, they reconstruct strings from byte arrays using the same encoding.
When a program specifies an encoding, it applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The method BytesMessage.WriteUTF always uses UTF-8 as its encoding.
For a list of standard encoding names, see www.iana.org.
OutboundMessages
Programs can determine the encoding of strings in outbound messages in three ways:
• Use the default global encoding—namely, UTF-8.
• Set a non-default global encoding (for all outbound messages) using Tibems.SetEncoding on page 293.
• Set the encoding for an individual message using Tibems.SetMessageEncoding on page 295.
OutboundMessages
An inbound message from another EMS client explicitly announces its encoding. A receiving client decodes the message using the proper encoding.
TIBCO Enterprise Message Service .NET Reference
.NET Compact Framework (CF) | 5
.NET Compact Framework (CF)
This section presents recommendations for using the EMS .NET Compact Framework API to develop applications for handheld devices.
Threads .NET Compact Framework does not support background threads. To avoid problems with threads, we recommend that programs release all EMS resources before terminating. For example, close EMS connections when they are no longer needed (see Connection.Close on page 121).
Clock Resolution Clock resolution affects the granularity of all time-related calls and parameters—for example MessageConsumer.Receive(timeout), connect delays. On some handheld devices, clock resolution is coarser than one might expect. Check the resolution on your target device before selecting time values.
ObjectSerialization
See Object Serialization on page 3.
ExcludedFeatures
See Excluded Features and Restrictions on page 3.
DLL Import the correct EMS assembly (see Table 4).
Table 4 EMS Assembly DLL
Version DLL
Full .NET API TIBCO.EMS.dll
.NET Compact Framework API TIBCO.EMS-CF.dll
TIBCO Enterprise Message Service .NET Reference
6 | Chapter 1 Introduction
TIBCO Enterprise Message Service .NET Reference
| 7
Chapter 2 Messages
Message objects carry application data between client program processes. This chapter presents the structure of messages, JMS message selector syntax to specify a subset of messages based on their property values, the message classes and their methods.
Topics
• Parts of a Message, page 8
• Body Types, page 9
• Headers, page 10
• Properties, page 15
• Message Selectors, page 18
• Data Type Conversion, page 21
• Message, page 22
• BytesMessage, page 32
• MapMessage, page 41
• ObjectMessage, page 48
• StreamMessage, page 50
• TextMessage, page 58
• Message.EmptyEnum, page 61
TIBCO Enterprise Message Service .NET Reference
8 | Chapter 2 Messages
Parts of a Message
Messages consist of three parts:
• Body The body of a message bears the information content of an application. Several types of message body organize that information in different ways; see Body Types on page 9.
• Header Headers associate a fixed set of header field names with values. Clients and providers use headers to identify and route messages.
• Properties Properties associate an extensible set of property names with values. The EMS server uses properties to attach ancillary information to messages. Client applications can also use properties—for example, to customize message filtering.
TIBCO Enterprise Message Service .NET Reference
Body Types | 9
Body Types
EMS follows JMS in defining five types of message body:
• MapMessage The message body is a mapping from field names to values. Field names are strings. EMS supports an extended set of values types (extending JMS). Programs can access fields either by name, or sequentially (though the order of that sequence is indeterminate).
• ObjectMessage The message body is one serializable object.
• StreamMessage The message body is a stream of values. Programs write the values sequentially into the stream, and read values sequentially from the stream.
• TextMessage The message body is one character string (of any length). This text string can represent any text, including an XML document.
• BytesMessage The message body is a stream of uninterpreted bytes. Programs can use this body type to emulate body types that do not map naturally to one of the other body types.
TIBCO Enterprise Message Service .NET Reference
10 | Chapter 2 Messages
Headers
Headers associate a fixed set of header field names with values. Clients and providers use headers to identify and route messages.
Programs can access headers as .NET properties of the message object.
Table 5 Message Header Names
Header Description
JMS Headers
These .NET properties correspond to message headers defined in the JMS specification.
Programs can get all supported message header properties (see Message.Get Property on page 28).
Programs can effectively set only three message header properties—ReplyTo, CorrelationID and MsgType (see Message.Set Property on page 30). For all other header properties, the provider ignores or overwrites values set by client programs.
CorrelationID string {get; set;}
Correlation ID refers to a related message. For example, when a consumer responds to a request message by sending a reply, it can set the correlation ID of the reply to indicate the request message.
The JMS specification allows three categories of values for the correlation ID property:
• Message ID A message ID is a unique string that the provider assigns to a message. Programs can use these IDs to correlate messages. For example, a program can link a response to a request by setting the correlation ID of a response message to the message ID of the corresponding request message. (See also MessageID on page 12.)
Message ID strings begin with the prefix ID: (which is reserved for this purpose).
• String Programs can also correlate messages using arbitrary strings, with semantics determined by the application.
These strings must not begin with the prefix ID: (which is reserved for message IDs).
• Byte Array This implementation does not support byte array values for the correlation ID property. The JMS specification does not require support.
TIBCO Enterprise Message Service .NET Reference
Headers | 11
CorrelationIDAsBytes byte[] {get; set;}
The JMS specification describes this optional utility, but EMS does not support it. Attempting to access this header results in System.InvalidOperationException.
DeliveryMode int {get; set;}
This header instructs the server concerning persistent storage for the message.
Sending calls record the delivery mode for each message, based on either a property of the producer (DeliveryMode on page 94), or on a parameter to the sending call.
For values, see the class DeliveryMode on page 260.
MsgDeliveryMode MessageDeliveryMode {get; set;}
This parallel .NET property accesses the same header using enumerated values (instead of ordinary integers). We recommend it over the ordinary integer-valued accessor, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.
For values, see the class MessageDeliveryMode on page 264.
Destination Destination {get; set;}
Sending calls record the destination (queue or topic) of the message in this header (ignoring and overwriting any existing value). The value is based on either a property of the producer (Destination on page 95), or on a parameter to the send call.
Listeners that consume messages from several destinations can use this property to determine the actual destination of a message.
Table 5 Message Header Names
Header Description
TIBCO Enterprise Message Service .NET Reference
12 | Chapter 2 Messages
Expiration long {get; set;}
Sending calls record the expiration time (in milliseconds) of the message in this field:
• If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT).
• If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.
The server discards a message when its expiration time has passed. However, the JMS specification does not guarantee that clients do not receive expired messages.
See TimeToLive on page 96.
MessageID string {get; set;}
Sending calls assign a unique ID to each message, and record it in this header.
All message ID values start with the 3-character prefix ID: (which is reserved for this purpose).
Applications that do not require message IDs can reduce overhead costs by disabling IDs; see DisableMessageID on page 95. When the producer disables IDs, the value of this header is null.
MsgType string {get; set;}
Some JMS providers use a message repository to store message type definitions. Client programs can store a value in this field to reference a definition in the repository. EMS supports this header, but does not use it.
The JMS specification does not define a standard message definition repository, nor does it define a naming policy for message type definitions.
Some providers require message type definitions for each application message. To ensure compatibility with such providers, client programs can set this header, even if the client application does not use it.
To ensure portability, clients can set this header with symbolic values (rather than literals), and configure them to match the provider’s repository.
Table 5 Message Header Names
Header Description
TIBCO Enterprise Message Service .NET Reference
Headers | 13
Priority int {get; set;}
Sending calls record the priority of a message in this header, based on either a property of the producer (Priority on page 95), or on a parameter to the send call.
The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification does not require all providers to implement priority ordering of messages. (EMS supports priorities, but other JMS providers might not.)
Redelivered bool {get; set;}
The server sets this header to indicate whether a message might duplicate a previously delivered message:
• false—The server has not previously attempted to deliver this message to the consumer.
• true—It is likely (but not guaranteed) that the server has previously attempted to deliver this message to the consumer, but the consumer did not return timely acknowledgement.
See also, QueueSession on page 196.
ReplyTo Destination {get; set;}
Sending clients can set this header to request that recipients reply to the message:
• When the value is a destination object, recipients can send replies to that destination. Such a message is called a request.
• When the value is null, the sender does not expect a reply.
When sending a reply, clients can refer to the corresponding request by setting the CorrelationID field.
Table 5 Message Header Names
Header Description
TIBCO Enterprise Message Service .NET Reference
14 | Chapter 2 Messages
Timestamp long {get; set;}
Sending calls record a UTC timestamp in this header, indicating the approximate time that the server accepted the message.
The value is in milliseconds since January 1, 1970 (as in Java).
Applications that do not require timestamps can reduce overhead costs by disabling timestamps; see DisableMessageTimestamp on page 95. When the producer disables timestamps, the value of this header is zero.
Table 5 Message Header Names
Header Description
TIBCO Enterprise Message Service .NET Reference
Properties | 15
Properties
Properties associate an extensible set of property field names with values. The EMS server uses properties to attach ancillary information to messages.
Client applications can also use properties—for example, to customize message filtering; see Message Selectors on page 18.
Setting Message PropertiesProperty names must conform to the syntax for message selector identifiers; see Identifiers on page 18.
Property values must not be null, nor the empty string.
Sending programs can set property values before sending a message.
Receiving programs cannot ordinarily set property values on inbound messages. However, the clearProperties method removes all existing the properties from a message, and lets the program set property values.
EMS PropertiesThe JMS specification reserves the property name prefix JMS_vendor_name_ for provider-specific properties (for EMS, this prefix is JMS_TIBCO_). Properties that begin with this prefix refer to features of EMS; client programs may use these properties to access those features, but not for communicating application-specific information among client programs.
Table 6 Message Property Names
Property Description
JMS_TIBCO_CM_PUBLISHER Correspondent name of an RVCM sender for messages imported from TIBCO Rendezvous.
JMS_TIBCO_CM_SEQUENCE Sequence number of an RVCM message imported from TIBCO Rendezvous.
JMS_TIBCO_COMPRESS Senders may set this property to request that EMS compress the message before sending it to the server.
JMS_TIBCO_DISABLE_SENDER Senders may set this property to prevent the EMS server from including the sender name in the message when the server sends it to consumers; see JMS_TIBCO_SENDER.
TIBCO Enterprise Message Service .NET Reference
16 | Chapter 2 Messages
JMS_TIBCO_IMPORTED When the EMS server imports a message from an external message service (such as TIBCO Rendezvous or TIBCO SmartSockets), it sets this property to true.
JMS_TIBCO_MSG_EXT Producers can set this property to true to indicate that a message uses EMS extensions to the JMS specification for messages.
The server sets this property to true when importing a message from an external message service, since the message might use those extensions.
JMS_TIBCO_MSG_TRACE When a producer sets this property, the EMS server generates trace output when the message arrives from the producer, and whenever a consumer receives it.
• When the property value is null, the trace output contains the message ID and sequence number.
• When the property value is body, the trace output includes the message body as well.
JMS_TIBCO_PRESERVE_UNDELIVERED When this property is true, the server preserves a record of undeliverable messages by delivering them to the undelivered message queue, $sys.undelivered.
JMS_TIBCO_SENDER The EMS server fills this property with the user name (string) of the client that sent the message. This feature applies only when the sender_name property of the message’s destination is non-null. The sender can disable this feature (overriding the destination property sender_name) by setting a non-null value for the message property JMS_TIBCO_DISABLE_SENDER.
JMS_TIBCO_SS_SENDER When the EMS server imports a message from TIBCO SmartSockets, it sets this property to the SmartSockets sender header field (in SmartSockets syntax).
Table 6 Message Property Names
Property Description
TIBCO Enterprise Message Service .NET Reference
Properties | 17
JMS PropertiesThe JMS specification reserves the property name prefix JMSX for properties defined by JMS. Client programs may use these properties to access those features, but not for communicating application-specific information among client programs.
To determine the set of JMS properties that a connection supports, call the method JMSXPropertyNames on page 125. For information about these properties, see the JMS specification.
TIBCO Enterprise Message Service .NET Reference
18 | Chapter 2 Messages
Message Selectors
A message selector is string that lets a client program specify a set of messages, based on the values of message headers and properties. A selector matches a message if, after substituting header and property values from the message into the selector string, the string evaluates to true. Consumers can request that the server deliver only those messages that match a selector.
The syntax of selectors is based on a subset of SQL92 conditional expression syntax.
Identifiers
Identifiers can refer to the values of message headers and properties, but not to the message body. Identifiers are case-sensitive.
Basic Syntax An identifier is a sequence of letters and digits, of any length, that begins with a letter. As in Java, the set of letters includes _ (underscore) and $ (dollar).
Illegal Certain names are exceptions, which cannot be used as identifiers. In particular, NULL, TRUE, FALSE, NOT, AND, OR, BETWEEN, LIKE, IN, IS, and ESCAPE are defined to have special meaning in message selector syntax.
Value Identifiers refer either to message header names or property names. The type of an identifier in a message selector corresponds to the type of the header or property value. If an identifier refers to a header or property that does not exist in a message, its value is NULL.
Literals
String Literal A string literal is enclosed in single quotes. To represent a single quote within a literal, use two single quotes; for example, 'literal''s'. String literals use the Unicode character encoding. String literals are case sensitive.
Exact NumericLiteral
An exact numeric literal is a numeric value without a decimal point, such as 57, -957, and +62; numbers in the range of long are supported.
ApproximateNumeric Literal
An approximate numeric literal is a numeric value with a decimal point (such as 7., -95.7, and +6.2), or a numeric value in scientific notation (such as 7E3 and -57.9E2); numbers in the range of double are supported. Approximate literals use the floating-point literal syntax of the Java programming language.
Boolean Literal The boolean literals are TRUE and FALSE (case insensitive).
TIBCO Enterprise Message Service .NET Reference
Message Selectors | 19
Internal computations of expression values use a 3-value boolean logic similar to SQL. However, the final value of an expression is always either TRUE or FALSE—never UNKNOWN.
Expressions
Selectors asExpressions
Every selector is a conditional expression. A selector that evaluates to true matches the message; a selector that evaluates to false or unknown does not match.
ArithmeticExpression
Arithmetic expressions are composed of numeric literals, identifiers (that evaluate to numeric literals), arithmetic operations, and smaller arithmetic expressions.
ConditionalExpression
Conditional expressions are composed of comparison operations, logical operations, and smaller conditional expressions.
Order ofEvaluation
Order of evaluation is left-to-right, within precedence levels. Parentheses override this order.
Operators
Case Insensitivity Operator names are case-insensitive.
Logical Operators Logical operators in precedence order: NOT, AND, OR.
ComparisonOperators
Comparison operators: =, >, >=, <, <=, <> (not equal).
These operators can compare only values of comparable types. (Exact numeric values and approximate numerical values are comparable types.) Attempting to compare incomparable types yields false. If either value in a comparison evaluates to NULL, then the result is unknown (in SQL 3-valued logic).
Comparison of string values is restricted to = and <>. Two strings are equal if and only if they contain the same sequence of characters.
Comparison of boolean values is restricted to = and <>.
ArithmeticOperators
Arithmetic operators in precedence order:
• +, - (unary)
• *, / (multiplication and division)
• +, - (addition and subtraction)
Arithmetic operations obey numeric promotion rules of the Java programming language.
TIBCO Enterprise Message Service .NET Reference
20 | Chapter 2 Messages
BetweenOperator
arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 AND arithmetic-expr3
The BETWEEN comparison operator includes its endpoints. For example:
• age BETWEEN 5 AND 9 is equivalent to age >= 5 AND age <= 9
• age NOT BETWEEN 5 AND 9 is equivalent to age < 5 OR age > 9
StringSet Membership
identifier [NOT] IN (string-literal1, string-literal2, ...)
The identifier must evaluate to either a string or NULL. If it is NULL, then the value of this expression is unknown.
Pattern Matching identifier [NOT] LIKE pattern-value [ESCAPE escape-character]
The identifier must evaluate to a string.
The pattern-value is a string literal, in which some characters bear special meaning:
• _ (underscore) can match any single character.
• % (percent) can match any sequence of zero or more characters.
• escape-character preceding either of the special characters changes them into ordinary characters (which match only themselves).
Null Header orProperty
identifier IS NULL
This comparison operator tests whether a message header is null, or a message property is absent.
identifier IS NOT NULL
This comparison operator tests whether a message header or message property is non-null.
White Space
White space is any of the characters space, horizontal tab, form feed, or line terminator—or any contiguous run of characters in this set.
TIBCO Enterprise Message Service .NET Reference
Data Type Conversion | 21
Data Type Conversion
Table 7 summarizes legal datatype conversions. The symbol X in Table 7 indicates that a value written into a message as the row type can be extracted as the column type. This table applies to all message values—including map pairs, headers and properties—except as noted below.
Notes • Message properties cannot have byte array values.
• Values written as strings can be extracted as a numeric or boolean type only when it is possible to parse the string as a number of that type.
Table 7 Data Type Conversion
bool byte short char int long float double string byte[]
bool X X
byte X X X X X
short X X X X
char X X
int X X X
long X X
float X X X
double X X
string X X X X X X X X
byte[] X
TIBCO Enterprise Message Service .NET Reference
22 | Chapter 2 Messages
MessageClass
Declaration public class Message : ICloneable
Subclasses BytesMessage on page 32MapMessage on page 41ObjectMessage on page 48StreamMessage on page 50TextMessage on page 58
Purpose Messages carry information among EMS client programs.
Remarks All other message types extend this root class.
Field Description
Constants defined as .NET fields.
DEFAULT_DELIVERY_MODE int DeliveryMode.PERSISTENT
When neither the sending call nor the producer supplies a delivery mode, this default applies.
DEFAULT_MSG_DELIVERY_MODE MessageDeliveryMode MessageDeliveryMode.Persistent
Enumerated version of the same value.
DEFAULT_PRIORITY int 4
When neither the sending call nor the producer supplies a priority, this default applies.
See also Priority on page 13.
DEFAULT_TIME_TO_LIVE long 0
When neither the sending call nor the producer supplies a priority, this default applies. The default value, zero, indicates that messages do not expire.
See also Expiration on page 12.
TIBCO Enterprise Message Service .NET Reference
Message | 23
JMS Headers as.NET Properties
This table lists the JMS headers that are available as .NET properties of message objects. For details, see Headers on page 10.
Header
CorrelationID
CorrelationIDAsBytes
DeliveryMode
MsgDeliveryMode
Destination
Expiration
MessageID
MsgType
Priority
Redelivered
ReplyTo
Timestamp
Method Description Page
Message.Acknowledge Acknowledge messages. 25
Message.ClearBody Clear the body of a message. 26
Message.ClearProperties Clear the properties of a message. 26
Message.Clone Create a copy of the message object. 26
Message.GetDeliveryModeName Convert a delivery mode constant to a string. 27
Message.Get Property Get the value of a message property. 28
Message.PropertyExists Test whether a named property has been set on a message.
29
TIBCO Enterprise Message Service .NET Reference
24 | Chapter 2 Messages
Message.Set Property Set the value of a message property. 30
Message.ToString Return a string representation of a message object.
31
Method Description Page
TIBCO Enterprise Message Service .NET Reference
Message.Acknowledge | 25
Message.AcknowledgeMethod
Declaration virtual void Acknowledge();
Purpose Acknowledge messages.
Remarks The behavior of this call depends on the acknowledgement mode of the Session.
• In ClientAcknowledge mode, this call acknowledges all messages that the program has consumed within the session. (This behavior complies with the JMS specification.)
• In ExplicitClientAcknowledge mode, this call acknowledges only the individual message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)
• In ExplicitClientDupsOkAcknowledge mode, this call lazily acknowledges only the individual message. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)
• In all other modes, this call has no effect. In particular, modes that specify transactions or implicit acknowledgement do not require the consuming program to call this method. However, calling it does not produce an exception. (This behavior complies with the JMS specification.)
Consumed Three events mark a message as consumed—that is, eligible for acknowledgment using this method:
• Just before the provider raises an EMSMessageHandler event, it marks the message argument as consumed.
• Just before the provider calls an IMessageListener.OnMessage callback, it marks the message argument as consumed.
• Just before a receive call returns a message, it marks that message as consumed.
Redelivery The server might redeliver unacknowledged messages.
See Also MessageConsumer.Receive on page 83Session on page 170AcknowledgeMode on page 171SessionAcknowledgeMode on page 171QueueSession on page 196
TIBCO Enterprise Message Service .NET Reference
26 | Chapter 2 Messages
Message.ClearBodyMethod
Declaration virtual void ClearBody();
Purpose Clear the body of a message.
Remarks Clearing the body of a message leaves its header and property values unchanged.
If the message body was read-only, this method makes it writable. The message body appears and behaves identically to an empty body in a newly created message.
Message.ClearPropertiesMethod
Declaration virtual void ClearProperties();
Purpose Clear the properties of a message.
Remarks Clearing the property values of a message leaves its header values and body unchanged.
Message.CloneMethod
Declaration virtual Object Clone();
Implements ICloneable.Clone
Purpose Create a copy of the message object.
TIBCO Enterprise Message Service .NET Reference
Message.GetDeliveryModeName | 27
Message.GetDeliveryModeNameMethod
Declaration static string GetDeliveryModeName(MessageDeliveryMode deliveryMode );
static string GetDeliveryModeName(int deliveryMode );
Purpose Convert a delivery mode constant to a string.
Parameters
Remarks Programs can obtain the delivery mode of a message by accessing the DeliveryMode header property of the message object.
This method is an extension to the JMS specification.
See Also DeliveryMode on page 260MessageDeliveryMode on page 264
Parameter Description
deliveryMode Convert this delivery mode to a string.
TIBCO Enterprise Message Service .NET Reference
28 | Chapter 2 Messages
Message.Get PropertyMethod
Declaration bool GetBooleanProperty(string name);byte GetByteProperty(string name);short GetShortProperty(string name);int GetIntProperty(string name);long GetLongProperty(string name);float GetFloatProperty(string name);double GetDoubleProperty(string name);string GetStringProperty(string name);Object GetObjectProperty(string name);
Purpose Get the value of a message property.
Parameters
Remarks The JMS specification defines eight methods to get properties with different value types—converting between compatible types. It also defines a ninth method to get values of the eight primitive types as if they were objects. All nine of these methods convert property values to the corresponding type (if possible).
When the message does not have a property set for the name, these rules apply:
• GetStringProperty and GetObjectProperty return null.
• GetBooleanProperty returns false.
• Numeric methods throw EMSException.
See Also Message.Set Property on page 30
Parameter Description
name Get the property with this name.
Property names must obey the JMS rules for a message selector identifier (see Message Selectors on page 18). Property names must not be null, and must not be empty strings.
TIBCO Enterprise Message Service .NET Reference
Message.PropertyExists | 29
Message.PropertyExistsMethod
Declaration virtual bool PropertyExists(string name );
Purpose Test whether a named property has been set on a message.
Parameters
Remarks This call returns true if the property has a value on the message; otherwise it returns false.
Parameter Description
name Test whether the message has a property with this name.
TIBCO Enterprise Message Service .NET Reference
30 | Chapter 2 Messages
Message.Set PropertyMethod
Declaration void SetBooleanProperty(string name, bool val);void SetByteProperty(string name, byte val);void SetShortProperty(string name, short val);void SetIntProperty(string name, int val);void SetLongProperty(string name, long val);void SetFloatProperty(string name, float val);void SetDoubleProperty(string name, double val);void SetStringProperty(string name, string val);void SetObjectProperty(string name, Object val);
Purpose Set the value of a message property.
Parameters
Remarks The JMS specification defines eight methods to set properties with different primitive value types. It also defines a ninth method to set a property to an object representation of any of the eight primitive types.
See Also Message.Get Property on page 28
Parameter Description
name Set a property with this name.
Property names must obey the JMS rules for a message selector identifier (see Message Selectors on page 18). Property names must not be null, and must not be empty strings.
val Set the property to this value.
TIBCO Enterprise Message Service .NET Reference
Message.ToString | 31
Message.ToStringMethod
Declaration override string ToString();
Purpose Return a string representation of a message object.
Remarks The string includes the body type, headers (name-value pairs), properties (name-value pairs), and body content.
TIBCO Enterprise Message Service .NET Reference
32 | Chapter 2 Messages
BytesMessageClass
Declaration class BytesMessage : Message
Purpose A message containing a stream of uninterpreted bytes.
Remarks Messages with this body type contain a single value, which is a byte stream.
Superclasses Message on page 22
Method Description Page
BytesMessage Construct an empty bytes message for a session. 33
BytesMessage.Read Read primitive data types from the byte stream in the message body.
34
BytesMessage.ReadBytes Read bytes to a byte array from the byte stream in the message body.
36
BytesMessage.Write Write primitive data types to the byte stream in the message body.
37
BytesMessage.WriteBytes Write bytes from a byte array to the byte stream in the message body.
39
BytesMessage.Reset Set the read position to the beginning of the byte stream, and mark the message body as read-only.
40
Member Description
Properties
BodyLength long {get;}
Programs can get the length of the message body (in bytes). Programs cannot set this .NET property.
TIBCO Enterprise Message Service .NET Reference
BytesMessage | 33
BytesMessageConstructor
Declaration BytesMessage(Session session);
Purpose Construct an empty bytes message for a session.
Parameters Parameter Description
session The Session of the message.
TIBCO Enterprise Message Service .NET Reference
34 | Chapter 2 Messages
BytesMessage.ReadMethod
Declaration bool ReadBoolean();sbyte ReadByte();byte ReadUnsignedByte();short ReadShort();ushort ReadUnsignedShort();char ReadChar();int ReadInt();long ReadLong();float ReadFloat();double ReadDouble();String ReadUTF();
Purpose Read primitive data types from the byte stream in the message body.
Remarks The JMS specification defines these eleven methods to extract data from the byte stream of a BytesMessage.
Each call reads a unit of data from the stream, and advances the read position so that the next read call gets the next datum.
Parameter Description
value The method reads a datum from the message, and stores it in this location.
length ReadUTF reads a UTF-8 string. Since the length of the string cannot be determined in advance, the method stores the actual length of the string in this location.
Table 8 BytesMessage Read Methods
Method # Bytes Interpret As
ReadBoolean 1 bool
ReadByte 1 sbyte
ReadUnsignedByte 1 byte
ReadShort 2 short
ReadUnsignedShort 2 ushort
ReadChar 2 char
TIBCO Enterprise Message Service .NET Reference
BytesMessage.Read | 35
See Also BytesMessage.ReadBytes on page 36
ReadInt 4 int
ReadLong 8 long
ReadFloat 4 float
ReadDouble 8 double
ReadUTF varies String
Encoded as UTF-8
Table 8 BytesMessage Read Methods
Method # Bytes Interpret As
TIBCO Enterprise Message Service .NET Reference
36 | Chapter 2 Messages
BytesMessage.ReadBytesMethod
Declaration int ReadBytes(byte[] value);
int ReadBytes(byte[] value, int length);
Purpose Read bytes to a byte array from the byte stream in the message body.
Parameters
Remarks Each call reads bytes from the stream into the byte array, and advances the read position.
When the program supplies a length argument, the call attempts to read length bytes; otherwise it attempts to read value.length bytes.
Returns This call returns the actual number of bytes read. When the call cannot read even one byte, it returns -1.
Parameter Description
value The program supplies a byte array. The call fills it with bytes from the byte stream.
length Read (at most) this number of bytes from the stream.
When present, the length argument must be between zero and value.length (inclusive); otherwise the call throws a System.IndexOutOfRangeException (and does not read any bytes).
TIBCO Enterprise Message Service .NET Reference
BytesMessage.Write | 37
BytesMessage.WriteMethod
Declaration void WriteBoolean(bool value);void WriteByte(byte value);void WriteShort(short value);void WriteChar(char value);void WriteInt(int value);void WriteLong(long value);void WriteFloat(float value);void WriteDouble(double value);void WriteUTF(string value);void WriteObject(Object value);
Purpose Write primitive data types to the byte stream in the message body.
Remarks The JMS specification defines these ten methods to insert data into the byte stream of a BytesMessage.
Each call writes a data value to the stream, and advances the write position so that the next write call appends to the new end of the stream.
Parameter Description
value Write this value to the message.
Table 9 BytesMessage Write Methods
Method # Bytes Notes
WriteBoolean 1
WriteByte 1
WriteShort 2
WriteChar 2
WriteInt 4
WriteLong 8
WriteFloat 4
WriteDouble 8
WriteUTF varies Encoded as UTF-8
TIBCO Enterprise Message Service .NET Reference
38 | Chapter 2 Messages
See Also BytesMessage.WriteBytes on page 39
WriteObject varies Converts an object to a primitive value (if possible), and writes that value to the byte stream.
Table 9 BytesMessage Write Methods
Method # Bytes Notes
TIBCO Enterprise Message Service .NET Reference
BytesMessage.WriteBytes | 39
BytesMessage.WriteBytesMethod
Declaration void WriteBytes(byte[] value);
void WriteBytes(byte[] value, int offset, int length);
Purpose Write bytes from a byte array to the byte stream in the message body.
Parameters
Remarks Each call writes bytes from the byte array into the stream, and advances the write position.
When the program supplies offset and length arguments, the call attempts to write the specified bytes to the stream; otherwise it attempts to write the entire byte array.
Offset & Length When present, the offset and length arguments must conform to these restrictions:
• offset must be in the range [0, value.length-1]
• length must be in the range [0, value.length]
• offset+length must be in the range [0, value.length]
That is, these two arguments must specify a span of bytes within the value argument. Otherwise the call throws a System.IndexOutOfRangeException (and does not write any bytes).
Parameter Description
value Write bytes from this byte array to the message.
offset Begin with the byte at this offset within the byte array.
length Write this number of bytes from the byte array.
TIBCO Enterprise Message Service .NET Reference
40 | Chapter 2 Messages
BytesMessage.ResetMethod
Declaration void Reset();
Purpose Set the read position to the beginning of the byte stream, and mark the message body as read-only.
Remarks Reset prepares a message body for reading, as if the message were newly received. Contrast Message.ClearBody on page 26, which clears a message body in preparation for writing, as if it were newly created.
TIBCO Enterprise Message Service .NET Reference
MapMessage | 41
MapMessageClass
Declaration class MapMessage : Message
Purpose A message containing a set of name-value pairs.
Remarks Messages with this body type contain several values, indexed by name.
Superclasses Message on page 22
Method Description Page
MapMessage Construct an empty map message for a session. 43
MapMessage.Get Get primitive data types from a map message. 44
MapMessage.ItemExists Test that a named pair is set. 45
MapMessage.Set Set a name-value pair in a map message. 46
MapMessage.SetBytes Set a name-value pair to a byte array value. 47
Member Description
Properties
FieldCount int {get;}
Programs can get the number of data items in the message body. Programs cannot set this .NET property.
MapNames System.Collections.IEnumerator {get;}
Programs can get an enumerator that produces the names of all the data items in the message body.
TIBCO Enterprise Message Service .NET Reference
42 | Chapter 2 Messages
Extensions TIBCO Enterprise Message Service extends the JMS MapMessage and StreamMessage body types in two ways. These extensions allow TIBCO Enterprise Message Service to exchange messages with TIBCO Rendezvous and TIBCO SmartSockets programs, which have certain features not available within the JMS specification.
• You can insert another MapMessage or StreamMessage instance as a submessage into a MapMessage or StreamMessage, generating a series of nested messages, instead of a flat message.
• You can use arrays as well as primitive types for the values.
These extensions add considerable flexibility to the two body types. However, they are extensions and therefore not compliant with JMS specifications. Extended messages are tagged as extensions with the vendor property tag JMS_TIBCO_MSG_EXT.
For more information on message compatibility with Rendezvous messages, see Message Body on page 315 in TIBCO Enterprise Message Service Release Notes.
TIBCO Enterprise Message Service .NET Reference
MapMessage | 43
MapMessageConstructor
Declaration MapMessage(Session session);
Purpose Construct an empty map message for a session.
Parameters Parameter Description
session The Session of the message.
TIBCO Enterprise Message Service .NET Reference
44 | Chapter 2 Messages
MapMessage.GetMethod
Declaration bool GetBoolean(string name);byte GetByte(string name);short GetShort(string name);char GetChar(string name);int GetInt(string name);long GetLong(string name);float GetFloat(string name);double GetDouble(string name);string GetString(string name);byte[] GetBytes(string name);Object GetObject(string name);
Purpose Get primitive data types from a map message.
Parameters
Remarks The JMS specification defines eleven methods to extract data from the name-value pairs of a MapMessage. Ten of these methods extract primitive data values. The GetObject method gets these values as if they were objects.
Returns Each call finds the named pair (if it exists) and returns its value.
When the message does not have a field set for the name, these calls return null.
Parameter Description
name Get the value associated with this name.
TIBCO Enterprise Message Service .NET Reference
MapMessage.ItemExists | 45
MapMessage.ItemExistsMethod
Declaration bool ItemExists(string name);
Purpose Test that a named pair is set.
Parameters Parameter Description
name Test for a pair with this name.
TIBCO Enterprise Message Service .NET Reference
46 | Chapter 2 Messages
MapMessage.SetMethod
Declaration void SetBoolean(string name, bool value);void SetByte(string name, byte value);void SetShort(string name, short value);void SetChar(string name, char value);void SetInt(string name, int value);void SetLong(string name, long value);void SetFloat(string name, float value);void SetDouble(string name, double value);void SetString(string name, String value);void SetObject(string name, Object value);
Purpose Set a name-value pair in a map message.
Parameters
Remarks The JMS specification defines eleven methods to set name-value pairs in a MapMessage (these ten, plus MapMessage.SetBytes on page 47).
The first nine of these methods set pairs with primitive value types. The SetObject method first converts an object to a primitive type (if possible), and then places that value in the pair.
See Also MapMessage.SetBytes on page 47
Parameter Description
name Set the pair with this name.
Field names must not be null, and must not be empty strings.
value Associate this value with the name.
TIBCO Enterprise Message Service .NET Reference
MapMessage.SetBytes | 47
MapMessage.SetBytesMethod
Declaration void SetBytes(string name, byte[] value);
void SetBytes(string name, byte[] value, int offset, int length);
Purpose Set a name-value pair to a byte array value.
Parameters
Remarks When the program supplies offset and length arguments, the call extracts the specified bytes and uses them as the value; otherwise it uses the entire byte array.
When present, the offset and length arguments must be between zero and value.length (inclusive), and their sum must also fall within the same range. That is, these two arguments must specify a span of bytes within the value argument. Otherwise the call throws an System.IndexOutOfRangeException (and does not set any value).
See Also MapMessage.Set on page 46
Parameter Description
name Set the pair with this name.
value Associate bytes from this byte array as the value of the name.
offset Begin with the byte at this offset within the byte array.
length Write this number of bytes from the byte array.
TIBCO Enterprise Message Service .NET Reference
48 | Chapter 2 Messages
ObjectMessageClass
Declaration class ObjectMessage : Message
Purpose A message containing a serializable object.
Remarks Setting the content of a MessageObject stores a snapshot of the object. subsequent changes to the original object do not affect the message.
.NETCompact
Framework
Object serialization differs among the various EMS language APIs in ways that are incompatible. An ObjectMessage contains a serialized object. Therefore EMS programs can only send an ObjectMessage to another program written in the same language; for example, Java to Java, C to C, .NET to .NET, and .NET Compact Framework to .NET Compact Framework. In particular, notice that a .NET Compact Framework client and a full .NET client cannot exchange an ObjectMessage.
Furthermore, the .NET Compact Framework supports only a limited set of objects for TheObject in an ObjectMessage—namely, bool, int, long, short, double, float, byte, bytes, char, string, short[], int[], long[], float[], double[], MapMessage, StreamMessage, and program-defined classes that implement IEMSSerialziable. Attempting to set the value to an unsupported object type results in MessageFormatException. This restriction applies only to .NET Compact Framework (the full .NET EMS API is exempt).
Superclasses Message on page 22IEMSSerialziable on page 261MessageFormatException on page 318
Member Description
Properties
TheObject Object {get; set;}
Programs can get and set the object in an ObjectMessage.
Method Description Page
ObjectMessage Constructor. 49
TIBCO Enterprise Message Service .NET Reference
ObjectMessage | 49
ObjectMessageConstructor
Declaration public ObjectMessage(Session session,object obj );
public ObjectMessage(Session session );
Purpose Create an object message.
Parameters
See Also .NET Compact Framework on page 48Session.CreateObjectMessage on page 184
Parameter Description
session Associate the new message with this session.
obj Use this object as the value of the new message.
When absent, construct an empty object message.
TIBCO Enterprise Message Service .NET Reference
50 | Chapter 2 Messages
StreamMessageClass
Declaration class StreamMessage : Message
Purpose A message containing a stream of data items.
Remarks Each datum in the stream must be a primitive type, or an object representation of a primitive type.
Superclasses Message on page 22
Extensions TIBCO Enterprise Message Service extends the MapMessage and StreamMessage body types in two ways. These extensions allow TIBCO Enterprise Message Service to exchange messages with TIBCO Rendezvous and ActiveEnterprise formats that have certain features not available within the JMS specification.
Member Description
Properties
FieldCount int {get;}
Programs can get the number of data items in the message body. Programs cannot set this property.
Method Description Page
StreamMessage Construct an empty stream message for a session. 52
StreamMessage.Read Read primitive data types from a stream message. 53
BytesMessage.ReadBytes Read a byte array from a stream message. 54
StreamMessage.Reset Set the read position to the beginning of the stream, and mark the message body as read-only.
55
StreamMessage.Write Write primitive data types to a stream message. 56
BytesMessage.WriteBytes Write bytes from a byte array to a stream message. 57
TIBCO Enterprise Message Service .NET Reference
StreamMessage | 51
• You can insert another MapMessage or StreamMessage instance as a submessage into a MapMessage or StreamMessage, generating a series of nested messages, instead of a flat message.
• You can use arrays as well as primitive types for the values.
These extensions add considerable flexibility to the two body types. However, they are extensions and therefore not compliant with JMS specifications. Extended messages are tagged as extensions with the vendor property tag JMS_TIBCO_MSG_EXT.
For more information on message compatibility with Rendezvous messages, see Message Body on page 315 in TIBCO Enterprise Message Service User’s Guide.
TIBCO Enterprise Message Service .NET Reference
52 | Chapter 2 Messages
StreamMessageConstructor
Declaration StreamMessage(Session session);
Purpose Construct an empty stream message for a session.
Parameters Parameter Description
session The Session of the message.
TIBCO Enterprise Message Service .NET Reference
StreamMessage.Read | 53
StreamMessage.ReadMethod
Declaration bool ReadBoolean();sbyte ReadByte();short ReadShort();char ReadChar();int ReadInt();long ReadLong();float ReadFloat();double ReadDouble();String ReadString();Object ReadObject();
Purpose Read primitive data types from a stream message.
Remarks The JMS specification defines these methods to extract data from a StreamMessage. (See also StreamMessage.ReadBytes on page 54.)
Each call reads a unit of data from the stream, and advances the read position so that the next read call gets the next datum.
See Also StreamMessage.ReadBytes on page 54
TIBCO Enterprise Message Service .NET Reference
54 | Chapter 2 Messages
StreamMessage.ReadBytesMethod
Declaration int ReadBytes(byte[] value);
Purpose Read a byte array from a stream message.
Parameters
Remarks Each call reads bytes from the stream into the byte array, and advances the read position.
This call returns the actual number of bytes read. When the call cannot read even one byte, it returns -1.
A program that calls this method must call it repeatedly until it returns -1, indicating that the program has extracted the complete set of bytes. Only then may the program call another read method.
Parameter Description
value The program supplies a byte array. The call fills it with bytes from the stream message.
TIBCO Enterprise Message Service .NET Reference
StreamMessage.Reset | 55
StreamMessage.ResetMethod
Declaration void Reset();
Purpose Set the read position to the beginning of the stream, and mark the message body as read-only.
Remarks Reset prepares a message body for reading, as if the message were newly received. Contrast Message.ClearBody on page 26, which clears a message body in preparation for writing, as if it were newly created.
TIBCO Enterprise Message Service .NET Reference
56 | Chapter 2 Messages
StreamMessage.WriteMethod
Declaration void WriteBoolean(bool value);void WriteByte(byte value);void WriteShort(short value);void WriteChar(char value);void WriteInt(int value);void WriteLong(long value);void WriteFloat(float value);void WriteDouble(double value);void WriteString(string value);void WriteObject(Object value);
Purpose Write primitive data types to a stream message.
Remarks The JMS specification defines these methods to insert data into a StreamMessage. (See also StreamMessage.WriteBytes on page 57.)
Each call writes a data value to the stream, and advances the write position so that the next write call appends to the new end of the stream.
WriteObject converts an object to a primitive value (if possible), and writes that value to the stream message.
Parameters
See Also StreamMessage.WriteBytes on page 57
Parameter Description
value Write this datum.
TIBCO Enterprise Message Service .NET Reference
StreamMessage.WriteBytes | 57
StreamMessage.WriteBytesMethod
Declaration void WriteBytes(byte[] value);
void WriteBytes(byte[] value, int offset, int length);
Purpose Write bytes from a byte array to a stream message.
Parameters
Remarks Each call writes bytes from the byte array into the stream, and advances the write position.
When the program supplies offset and length arguments, the call attempts to write the specified bytes to the stream; otherwise it attempts to write the entire byte array.
When present, the offset and length arguments must be between zero and value.length (inclusive), and their sum must also fall within the same range. That is, these two arguments must specify a span of bytes within the value argument. Otherwise the call throws an IndexOutOfRangeException (and does not write any bytes).
Parameter Description
value Write bytes from this byte array to the message.
offset Begin with the byte at this offset within the byte array.
length Write this number of bytes from the byte array.
TIBCO Enterprise Message Service .NET Reference
58 | Chapter 2 Messages
TextMessageClass
Declaration class TextMessage : Message
Purpose A message containing a text string.
Remarks A TextMessage object is used to send a message containing a String. It inherits from the Message interface and adds a text message body. This message type can be used to transport text-based messages, including those with XML content.
When a client receives a TextMessage, it is in read-only mode. If a client attempts to write to the message at this point, a MessageNotWriteableException is thrown. Calling TextMessage.ClearBody allows you to both read from and write to the message.
Superclasses Message on page 22
Member Description
Properties
Text string {get; set;}
Programs can get and set the text string in a TextMessage.
Method Description Page
TextMessage Create a text message object.. 59
TextMessage.ClearBody Clear the body of a text message.. 59
TextMessage.Clone Create a copy of the text message object.. 60
TIBCO Enterprise Message Service .NET Reference
TextMessage | 59
TextMessageConstructor
Declaration public TextMessage(Session session,string text );
public ObjectMessage(Session session );
Purpose Create a text message object.
Parameters
See Also Session.CreateTextMessage on page 190
TextMessage.ClearBody
Declaration override void ClearBody();
Purpose Clear the body of a text message.
Remarks Clearing the body of a text message leaves its header and property values unchanged.
If the text message body was read-only, this method makes it writable. The message body appears and behaves identically to an empty body in a newly created message.
See Also Message.ClearBody on page 26
Parameter Description
session Associate the new message with this session.
text Use this string as the value of the new message.
TIBCO Enterprise Message Service .NET Reference
60 | Chapter 2 Messages
TextMessage.Clone
Declaration override object Clone();
Implements ICloneable.Clone.
Purpose Create a copy of the text message object.
TIBCO Enterprise Message Service .NET Reference
Message.EmptyEnum | 61
Message.EmptyEnumClass
Declaration class Message.EmptyEnum : IEnumerator
Purpose Specifies an empty enumerator
Remarks Messages with this body type contain a single value, which is a string.
Requirements Namespace: TIBCO.EMSAssembly: TIBCO.EMS (in TIBCO.EMS.dll)
Member Description
Properties
Current object Current {get;}
Implements IEnumerator.Current.
Trying to get the current object in enumerator will throw an InvalidOperationException.
Method Description Page
Message.EmptyEnum Construct an empty enumerator. 62
Message.EmptyEnum.MoveNext Advances the enumerator to the next element of the collection.
62
Message.EmptyEnum.Reset Reset the enumerator. 62
TIBCO Enterprise Message Service .NET Reference
62 | Chapter 2 Messages
Message.EmptyEnumConstructor
Declaration Message.EmptyEnum();
Purpose Construct an empty enumerator.
Message.EmptyEnum.MoveNextMethod
Declaration bool MoveNext();
Purpose Advances the enumerator to the next element of the collection.
Remarks Implements IEnumerator.MoveNext. MoveNext() will always returns false.
Message.EmptyEnum.Reset
Declaration void Reset();
Purpose Reset the enumerator.
Remarks Implements IEnumerator.Reset. Reset() does nothing since the enumerator is empty.
TIBCO Enterprise Message Service .NET Reference
| 63
TIBCO Enterprise Message Service .NET Reference
64 | Chapter 2 Messages
TIBCO Enterprise Message Service .NET Reference
| 65
Chapter 3 Destination
Topics
• Destination Overview, page 66
• Destination, page 69
• Queue, page 70
• TemporaryQueue, page 72
• TemporaryTopic, page 74
• Topic, page 76
TIBCO Enterprise Message Service .NET Reference
66 | Chapter 3 Destination
Destination Overview
Destination objects represent destinations within the EMS server—the queues and topics to which programs send messages, and from which they receive messages.
Queues deliver each message to exactly one consumer. Topics deliver each message to every subscriber. Queues and topics can be static, dynamic or temporary.
Table 10 Destination Overview
Aspect Static Dynamic Temporary
Purpose Static destinations let administrators configure EMS behavior at the enterprise level. Administrators define these administered objects, and client programs use them—relieving program developers and end users of the responsibility for correct configuration.
Dynamic destinations give client programs the flexibility to define destinations as needed for short-term use.
Temporary destinations are ideal for limited-scope uses, such as reply subjects.
Scope of Delivery
Static destinations support concurrent use. That is, several client processes (and in several threads within a process) can create local objects denoting the destination, and consume messages from it.
Dynamic destinations support concurrent use. That is, several client processes (and in several threads within a process) can create local objects denoting the destination, and consume messages from it.
Temporary destinations support only local use. That is, only the client connection that created a temporary destination can consume messages from it.
However, servers connected by routes do exchange messages sent to temporary topics.
TIBCO Enterprise Message Service .NET Reference
Destination Overview | 67
Creation Administrators create static destinations using EMS server administration tools or API.
If the server configuration permits dynamic destinations, client programs can create one in two steps:
1. Create a local destination object; see Session on page 170.
2. Send a message to that destination, or create a consumer for it. Either of these actions automatically creates the destination in the server.
Client programs create temporary destinations; see Session on page 170.
Lookup Client programs lookup static destinations by name. Successful lookup returns a local object representation of the destination; see LookupContext.Lookup on page 219.
Client programs lookup dynamic destinations by name. Successful lookup returns a local object representation of the destination; see LookupContext.Lookup on page 219.
Not applicable.
Table 10 Destination Overview
Aspect Static Dynamic Temporary
TIBCO Enterprise Message Service .NET Reference
68 | Chapter 3 Destination
Duration A static destination remains in the server until an administrator explicitly deletes it.
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 durable subscribers exist for the topic
• Queue queue, no messages are stored in the queue
A temporary destination remains in the server either until the client that created it explicitly deletes it, or until the client disconnects from the server.
Table 10 Destination Overview
Aspect Static Dynamic Temporary
TIBCO Enterprise Message Service .NET Reference
Destination | 69
DestinationClass
Declaration class Destination
Purpose Root behavior of all destinations.
Subclasses Queue on page 70TemporaryQueue on page 72
Topic on page 76TemporaryTopic on page 74
Remarks Administrators define destinations in the server. Client programs access them using methods of LookupContext.
Programs do not create instances of this class; instead, they create instances of its subclasses.
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
70 | Chapter 3 Destination
QueueClass
Declaration class Queue : Destination
Purpose Queues deliver each message to exactly one consumer.
Subclasses TemporaryQueue on page 72
Member Description
Properties
QueueName string {get;}
The lookup name of the queue object. Each queue has a name that is unique among all queues.
Method Description Page
Queue Constructor. 71
TIBCO Enterprise Message Service .NET Reference
Queue | 71
QueueConstructor
Declaration Queue(string name);
Purpose Create a queue object.
Remarks This constructor creates only local objects (within the program). It does not attempt to lookup the corresponding server object until the program creates a MessageConsumer or a MessageProducer that uses the queue. That automatic lookup can result in either of two outcomes:
• If lookup succeeds, it binds the local queue object to the server queue object.
• If lookup fails, the server creates a new dynamic queue.
See Also Session.CreateQueue on page 186LookupContext on page 215
Parameter Description
name Find or create a queue with this name.
TIBCO Enterprise Message Service .NET Reference
72 | Chapter 3 Destination
TemporaryQueueClass
Declaration class TemporaryQueue : Queue
Purpose Programs can use temporary queues as reply destinations.
Remarks Programs create temporary queues using Session.CreateTemporaryQueue.
A temporary queue exists only for the duration of the session’s connection, and is available only within that connection.
Only consumers associated with the same connection as the temporary queue can consume messages from it.
See Also Session.CreateTemporaryQueue on page 188
Method Description Page
TemporaryQueue.Delete Delete a temporary queue. 73
TIBCO Enterprise Message Service .NET Reference
TemporaryQueue.Delete | 73
TemporaryQueue.DeleteMethod
Declaration void Delete();
Purpose Delete a temporary queue.
Remarks When a client deletes a temporary queue, the server deletes any unconsumed messages in the queue.
Throws If the client still has listeners or receivers for the queue, or is in the middle of a Receive call, then Delete throws an EMSException.
TIBCO Enterprise Message Service .NET Reference
74 | Chapter 3 Destination
TemporaryTopicClass
Declaration class TemporaryTopic : Topic
Purpose Programs can use temporary topics as reply destinations.
Remarks Programs create temporary topics using Session.CreateTemporaryTopic.
A temporary topic exists only for the duration of the session’s connection, and is available only within that connection.
Only consumers associated with the same connection as the temporary topic can consume messages from it.
Servers connected by routes do exchange messages sent to temporary topics.
See Also Session.CreateTemporaryTopic on page 189
Method Description Page
TemporaryTopic.Delete Delete a temporary topic. 75
TIBCO Enterprise Message Service .NET Reference
TemporaryTopic.Delete | 75
TemporaryTopic.DeleteMethod
Declaration void Delete();
Purpose Delete a temporary topic.
Remarks When a client deletes a temporary topic, the server deletes any unconsumed messages in the topic.
Throws If the client still has listeners or receivers for the topic, or is in the middle of a Receive call, then Delete throws an EMSException.
TIBCO Enterprise Message Service .NET Reference
76 | Chapter 3 Destination
TopicClass
Declaration class Topic : Destination
Purpose Topics deliver each message to multiple consumers.
Subclasses TemporaryTopic on page 74
Member Description
Properties
TopicName string {get;}
The lookup name of the topic object. Each topic has a name that is unique among all topics.
Method Description Page
Topic Constructor. 77
TIBCO Enterprise Message Service .NET Reference
Topic | 77
TopicConstructor
Declaration Topic(string name );
Purpose Create a topic object.
Remarks This constructor creates only local objects (within the program). It does not attempt to lookup the corresponding server object until the program creates a MessageConsumer or a MessageProducer that uses the topic. That automatic lookup can result in either of two outcomes:
• If lookup succeeds, it binds the local topic object to the server topic object.
• If lookup fails, the server creates a new dynamic topic.
See Also Session.CreateTopic on page 191LookupContext on page 215
Parameter Description
name Find or create a topic with this name.
TIBCO Enterprise Message Service .NET Reference
78 | Chapter 3 Destination
TIBCO Enterprise Message Service .NET Reference
| 79
Chapter 4 Consumer
Each message consumer receives messages from a destination.
Topics
• MessageConsumer, page 80
• QueueReceiver, page 85
• TopicSubscriber, page 86
• EMSMessageHandler, page 87
• EMSMessageEventArgs, page 88
• IMessageListener, page 90
TIBCO Enterprise Message Service .NET Reference
80 | Chapter 4 Consumer
MessageConsumerClass
Declaration class MessageConsumer
Purpose Root behavior of all consumers.
Subclasses QueueReceiver
TopicSubscriber
Remarks Consumers can receive messages synchronously (using the Receive methods), or asynchronously.
Consumers can receive messages asynchronously in either of two idioms. Programmers may select either idiom—but not both (which would cause duplicate message processing, with undefined behavior).
• MessageHandler events let programs receive messages in a .NET programming idiom.
• In contrast, the MessageListener property mimics the way in which JMS provides similar functionality in a Java programming idiom.
Member Description
Events
MessageHandler EMSMessageHandler
The client library raises an event when a message arrives at the destination. The program implements a handler delegate to processes it asynchronously, and registers the delegate here. See Remarks, above.
Properties
MessageListener IMessageListener {get; set;}
When a message arrives, the client library calls this listener’s onMessage method with the message as its argument. The program implements the message listener interface, and registers a message listener object by setting this property. See Remarks, above.
TIBCO Enterprise Message Service .NET Reference
MessageConsumer | 81
See Also IMessageListener on page 90EMSMessageHandler on page 87
MessageSelector string {get;}
A message selector restricts the set of messages that the consumer receives to those that match the selector; see Message Selectors on page 18.
Programs can set this property only when creating the consumer object; see Session.CreateConsumer on page 180.
Member Description
Method Description Page
MessageConsumer.Close Stop receiving messages; reclaim resources. 82
MessageConsumer.Receive Receive a message (synchronous). 83
MessageConsumer.ReceiveNoWait Receive a message (synchronous, non-blocking). 84
TIBCO Enterprise Message Service .NET Reference
82 | Chapter 4 Consumer
MessageConsumer.CloseMethod
Declaration void Close();
Purpose Stop receiving messages; reclaim resources.
Remarks If a receive call or a message listener is in progress, then Close waits until that call returns.
Message consumers rely on resources outside the client program. To reclaim these resources in a timely manner, we recommend that client programs explicitly close message consumer objects (rather than waiting for garbage collection).
See Also MessageConsumer.Receive on page 83IMessageListener on page 90Session.CreateConsumer on page 180
TIBCO Enterprise Message Service .NET Reference
MessageConsumer.Receive | 83
MessageConsumer.ReceiveMethod
Declaration Message Receive();
Message Receive(long timeout );
Purpose Receive a message (synchronous).
Remarks This method consumes the next message from the destination.
When the destination does not have any messages ready, this method blocks:
• If a message arrives at the destination, this call immediately returns that message.
• If the (non-zero) timeout elapses before a message arrives, this call returns null.
• If another thread closes the consumer, this call returns null.
When calling receive within a transaction, the consumer retains the message until transaction commits.
Parameter Description
timeout When present, wait no longer than this interval (in milliseconds) for a message to arrive. Zero is a special value, which specifies no timeout (block indefinitely).
When absent, the default value is zero.
TIBCO Enterprise Message Service .NET Reference
84 | Chapter 4 Consumer
MessageConsumer.ReceiveNoWaitMethod
Declaration Message ReceiveNoWait();
Purpose Receive a message (synchronous, non-blocking).
Remarks When the destination has at least one message ready, this method immediately returns the next message.
When the destination does not have any messages ready, this method immediately returns null.
When calling receive within a transaction, the consumer retains the message until transaction commits.
TIBCO Enterprise Message Service .NET Reference
QueueReceiver | 85
QueueReceiverClass
Declaration class QueueReceiver : MessageConsumer
Purpose Consume messages from a queue.
Remarks This class inherits almost all of its behavior from MessageConsumer. It adds only a property, specializing the generic destination to a queue.
Member Description
Properties
Queue Queue {get;}
The receiver consumes messages from this queue.
Programs set this queue when creating the receiver, and cannot subsequently change it.
TIBCO Enterprise Message Service .NET Reference
86 | Chapter 4 Consumer
TopicSubscriberClass
Declaration class TopicSubscriber : MessageConsumer
Purpose Consume messages from a topic.
Remarks This class inherits almost all of its behavior from MessageConsumer; it adds only two properties.
Member Description
Properties
NoLocal bool {get;}
When true, the subscriber does not receive messages sent through the same server connection (that is, the connection associated with the subscriber).
Programs set this property when creating the subscriber, and cannot subsequently change it.
Topic Topic {get;}
The subscriber consumes messages from this topic.
Programs set this topic property when creating the subscriber, and cannot subsequently change it.
TIBCO Enterprise Message Service .NET Reference
EMSMessageHandler | 87
EMSMessageHandlerDelegate
Declaration delegate void EMSMessageHandler(object sender,EMSMessageEventArgs args );
Purpose Asynchronously process an arriving message.
Remarks This delegate provides an asynchronous pathway for receiving messages. The program implements this delegate, and registers it with a MessageConsumer. When a message arrives, the client library raises an event. This delegate processes the event, which presents the message.
EMSMessageHandler receives messages in a .NET programming idiom. In contrast, IMessageListener mimics the way in which JMS provides similar functionality in a Java programming idiom. Programmers may select either idiom—but not both (which would cause duplicate message processing, with undefined behavior).
Example 1 Message Event Handler...consumer.MessageHandler += new EMSMessageHandler(handleMsg);...private void handleMsg(object sender, EMSMessageEventArgs arg){
Message m = arg.Message;Console.WriteLine("Received message: " + m);...
}...
Serialization In compliance with the JMS specification, sessions distribute messages to listeners and event handler delegates in serial (non-concurrent) fashion.
See Also MessageConsumer on page 80EMSMessageEventArgs on page 88
Parameter Description
sender The MessageConsumer object that raised a message event.
args The event, which contains the message object.
TIBCO Enterprise Message Service .NET Reference
88 | Chapter 4 Consumer
EMSMessageEventArgsClass
Declaration class EMSMessageEventArgs : EventArgs
Purpose Present an arriving message as a .NET event.
Remarks EMSMessageHandler delegates receive this object as an argument.
Member Description
Properties
Message Message {get;}
Programs can get the message that triggered the event.
Method Description Page
EMSMessageEventArgs Constructor. 89
TIBCO Enterprise Message Service .NET Reference
EMSMessageEventArgs | 89
EMSMessageEventArgsConstructor
Declaration EMSMessageEventArgs(Message msg );
Purpose Create a message event.
Parameter Description
msg The new event encapsulates this message, and signals its arrival.
TIBCO Enterprise Message Service .NET Reference
90 | Chapter 4 Consumer
IMessageListenerInterface
Declaration interface IMessageListener
Purpose Asynchronously process an arriving message.
Remarks This interface provides an asynchronous pathway for receiving messages. The program implements this interface, and registers a message listener with a MessageConsumer. When a message arrives, the client library calls the listener’s onMessage method with the message as its argument.
IMessageListener mimics the way in which JMS receives messages in a Java programming idiom. In contrast, EMSMessageHandler provides similar functionality in a .NET idiom. Programmers may select either idiom—but not both (which would cause duplicate message processing, with undefined behavior).
Serialization In compliance with the JMS specification, sessions distribute messages to listeners and event handler delegates in serial (non-concurrent) fashion.
Deprecated In earlier releases, clients could register listeners with sessions as well as consumers. This practice is now deprecated—we recommend migrating existing code to one of these two practices:
• Java Idiom Register listeners with consumers.
• .NET Idiom Register EMSMessageHandler delegates with consumers.
See Also MessageConsumer on page 80Session on page 170
Method Description Page
IMessageListener.OnMessage Process inbound messages (asynchronous). 91
TIBCO Enterprise Message Service .NET Reference
IMessageListener.OnMessage | 91
IMessageListener.OnMessageMethod
Declaration void OnMessage(Message message );
Purpose Process inbound messages (asynchronous).
Parameter Description
message Process this message.
TIBCO Enterprise Message Service .NET Reference
92 | Chapter 4 Consumer
TIBCO Enterprise Message Service .NET Reference
| 93
Chapter 5 Producer
Message producers send messages to destinations on the server.
Topics
• MessageProducer, page 94
• QueueSender, page 100
• TopicPublisher, page 103
TIBCO Enterprise Message Service .NET Reference
94 | Chapter 5 Producer
MessageProducerClass
Declaration class MessageProducer
Purpose Root behavior of all producers.
Subclasses QueueSender
TopicPublisher
Remarks Clients use message producers to send messages. A message producer object can store several parameters that affect the messages it sends.
This class lacks a constructor. Instead, clients create message producers using methods of a Session object; subclasses (such as QueueSession and TopicSession) each define methods to create corresponding producer subclasses.
Member Description
Properties
DeliveryMode int {get; set;}
Delivery mode instructs the server concerning persistent storage.
Programs can use this property to define a default delivery mode for messages that this producer sends. Individual sending calls can override this default value.
For values, see the class DeliveryMode on page 260.
MsgDeliveryMode MessageDeliveryMode {get; set;}
This parallel property accesses the same default value using enumerated values (instead of ordinary integers). We recommend it over the ordinary integer-valued accessor, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.
TIBCO Enterprise Message Service .NET Reference
MessageProducer | 95
Destination Destination {get;}
Each send call directs a message to a destination (queue or topic).
This property defines a default destination for messages that this producer sends. Individual sending calls can override this default value.
DisableMessageID bool {get; set;}
Applications that do not require message IDs can reduce overhead costs by disabling IDs (set this property to true).
DisableMessageTimestamp bool {get; set;}
Applications that do not require timestamps can reduce overhead costs by disabling timestamps (set this property to true).
Priority int {get; set;}
Priority affects the order in which the server delivers messages to consumers (higher values first).
The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
Programs can use this property to define a default priority for messages that this producer sends. Individual sending calls can override this default value.
Member Description
TIBCO Enterprise Message Service .NET Reference
96 | Chapter 5 Producer
TimeToLive long {get; set;}
Time-to-live (in milliseconds) determines the expiration time of a message.
• If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT). This rule applies even within sessions with transaction semantics—the timer begins with the send call, not the commit call.
• If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.
Programs can use this property to define a default time-to-live for messages that this producer sends. Individual sending calls can override this default value.
Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.
Member Description
Method Description Page
MessageProducer.Close Destroy the producer object; reclaim resources. 97
MessageProducer.Send Send a message. 98
TIBCO Enterprise Message Service .NET Reference
MessageProducer.Close | 97
MessageProducer.CloseMethod
Declaration void Close();
Purpose Destroy the producer object; reclaim resources.
Remarks Message producers rely on resources outside the client program. To reclaim these resources in a timely manner, we recommend that client programs explicitly close message producer objects (rather than waiting for garbage collection).
See Also Session.CreateProducer on page 185
TIBCO Enterprise Message Service .NET Reference
98 | Chapter 5 Producer
MessageProducer.SendMethod
Declaration virtual void Send(Destination dest,Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );
virtual void Send(Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );
virtual void Send(Destination dest,Message message,int deliveryMode,int priority,long timeToLive );
virtual void Send(Message message,int deliveryMode,int priority,long timeToLive );
virtual void Send(Destination dest,Message message );
virtual void Send(Message message );
Purpose Send a message.
Parameter Description
dest When present, the call sends the message to this destination (queue or topic).
When absent, the call sends the message to the producer’s default destination. When the producer does not specify a default, the send call must supply this parameter.
message Send this message object.
TIBCO Enterprise Message Service .NET Reference
MessageProducer.Send | 99
deliveryMode When present, the call sends the message with this delivery mode.
This argument may be either an enumerated value (see MessageDeliveryMode on page 264) or an integer (see DeliveryMode on page 260). We recommend enumerated values, because they enable .NET to do stronger type checking at compile time, which can enhance program reliability.
When absent, the call sends the message with the producer’s default delivery mode.
priority When present, the call sends the message with this priority.
Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
When absent, the call sends the message with the producer’s default priority.
timeToLive When present, the call uses this value (in milliseconds) to compute the message expiration.
• If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT). This rule applies even within sessions with transaction semantics—the timer begins with the send call, not the commit call.
• If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.
When absent, the call uses the producer’s default value to compute expiration.
Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.
Parameter Description
TIBCO Enterprise Message Service .NET Reference
100 | Chapter 5 Producer
QueueSenderClass
Declaration class QueueSender : MessageProducer
Purpose Send messages to a queue.
Remarks This class extends MessageProducer on page 94. It overloads more send methods, specializing the destination parameter to a queue.
Member Description
Properties
Queue Queue {get;}
Each send call directs a message to a queue.
Programs can use this property to define a default queue for messages that this producer sends. Individual sending calls can override this default value.
Programs set this queue when creating the sender, and cannot subsequently change it.
Method Description Page
QueueSender.Send Send a message. 101
TIBCO Enterprise Message Service .NET Reference
QueueSender.Send | 101
QueueSender.SendMethod
Declaration virtual void Send(Queue queue,Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );
virtual void Send(Queue queue,Message message,int deliveryMode,int priority,long timeToLive );
virtual void Send(Queue queue,Message message );
Purpose Send a message.
Remarks QueueSender inherits send methods from MessageProducer, and also defines these methods, which specialize the destination parameter to a queue; see MessageProducer.Send on page 98.
Parameter Description
queue When present, the call sends the message to this queue.
When absent, the call sends the message to the sender’s default queue. When the sender does not specify a default, the send call must supply this parameter (that is, it cannot use one of the inherited methods that omit this parameter).
message Send this message object.
deliveryMode When present, the call sends the message with this delivery mode.
This argument may be either an enumerated value (see MessageDeliveryMode on page 264) or an integer (see DeliveryMode on page 260). We recommend enumerated values, because they enable .NET to do stronger type checking at compile time, which can enhance program reliability.
When absent, the call sends the message with the sender’s default delivery mode.
TIBCO Enterprise Message Service .NET Reference
102 | Chapter 5 Producer
See Also MessageProducer.Send on page 98
priority When present, the call sends the message with this priority.
Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
When absent, the call sends the message with the sender’s default priority.
timeToLive When present, the call uses this value (in milliseconds) to compute the message expiration.
• If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT).
• If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.
When absent, the call uses the sender’s default value to compute expiration.
Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.
Parameter Description
TIBCO Enterprise Message Service .NET Reference
TopicPublisher | 103
TopicPublisherClass
Declaration class TopicPublisher : MessageProducer
Purpose Send a message to a topic.
Remarks This class extends MessageProducer on page 94. It overloads more send methods, specializing the destination parameter to a topic.
Member Description
Properties
Topic Topic {get;}
Each send call directs a message to a topic.
Programs can use this property to define a default topic for messages that this publisher sends. Individual sending calls can override this default value.
Programs set this topic when creating the publisher, and cannot subsequently change it.
Method Description Page
TopicPublisher.Publish Publish a message to a topic. 104
TIBCO Enterprise Message Service .NET Reference
104 | Chapter 5 Producer
TopicPublisher.PublishMethod
Declaration virtual void Publish(Topic topic,Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );
virtual void Publish(Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );
virtual void Publish(Topic topic,Message message,int deliveryMode,int priority,long timeToLive );
virtual void Publish(Message message,int deliveryMode,int priority,long timeToLive );
virtual void Publish(Topic topic,Message message );
virtual void Publish(Message message );
Purpose Publish a message to a topic.
Remarks These methods are parallel to the send methods that TopicPublisher inherits from MessageProducer, and they accomplish the same goal—sending messages.
Parameter Description
topic When present, the call sends the message to this topic.
When absent, the call sends the message to the publisher’s default topic. When the publisher does not specify a default, the publish call must supply this parameter.
message Publish this message.
TIBCO Enterprise Message Service .NET Reference
TopicPublisher.Publish | 105
See Also MessageProducer.Send on page 98
deliveryMode When present, the call sends the message with this delivery mode.
This argument may be either an enumerated value (see MessageDeliveryMode on page 264) or an integer (see DeliveryMode on page 260). We recommend enumerated values, because they enable .NET to do stronger type checking at compile time, which can enhance program reliability.
When absent, the call sends the message with the publisher’s default delivery mode.
priority When present, the call sends the message with this priority.
Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.
When absent, the call sends the message with the publisher’s default priority.
timeToLive When present, the call uses this value (in milliseconds) to compute the message expiration.
• If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT).
• If the time-to-live is zero, then expiration is also zero—indicating that the message never expires.
When absent, the call uses the publisher’s default value to compute expiration.
Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.
Parameter Description
TIBCO Enterprise Message Service .NET Reference
106 | Chapter 5 Producer
TIBCO Enterprise Message Service .NET Reference
| 107
Chapter 6 Requestor
Requestors implement convenience methods for request-reply semantics. They send messages (called requests) and wait for reply messages in response.
Topics
• QueueRequestor, page 108
• TopicRequestor, page 112
TIBCO Enterprise Message Service .NET Reference
108 | Chapter 6 Requestor
QueueRequestorClass
Declaration class QueueRequestor
Purpose Encapsulate request-reply semantics, sending requests to a queue.
Remarks We recommend that programs follow these steps:
1. Create a QueueSession, and use it to create a Queue for requests and replies.
2. Create a QueueRequestor, using the queue session and queue as arguments.
3. Send a request and receive a reply. You may repeat this step for several request and reply pairs.
4. Close the requestor object. The Close method also closes the requestor’s session as a side effect.
See Also Queue on page 70QueueSession on page 196
Method Description Page
QueueRequestor Create a queue requestor. 109
QueueRequestor.Close Close a queue requestor. 110
QueueRequestor.Request Send a request message; wait for a reply and return it.
111
TIBCO Enterprise Message Service .NET Reference
QueueRequestor | 109
QueueRequestorConstructor
Declaration QueueRequestor (QueueSession session,Queue queue );
Purpose Create a queue requestor.
Parameter Description
session The requestor operates within this queue session.
This session must not use transaction semantics. Its delivery mode must be either AutoAcknowledge or DupsOkAcknowledge.
The Close method also closes this session as a side effect.
queue The requestor sends request messages to this queue, and waits for replies on the same queue.
You must create this queue using the queue session you supply as the first argument.
TIBCO Enterprise Message Service .NET Reference
110 | Chapter 6 Requestor
QueueRequestor.CloseMethod
Declaration void Close ();
Purpose Close a queue requestor.
Remarks This method also closes the requestor’s session as a side effect.
TIBCO Enterprise Message Service .NET Reference
QueueRequestor.Request | 111
QueueRequestor.RequestMethod
Declaration Message Request(Message message );
Purpose Send a request message; wait for a reply and return it.
Remarks The requestor receives only the first reply. It discards other replies that arrive subsequently.
Parameter Description
message Send this request message.
TIBCO Enterprise Message Service .NET Reference
112 | Chapter 6 Requestor
TopicRequestorClass
Declaration class TopicRequestor
Purpose Encapsulate request-reply semantics, sending requests to a topic.
Remarks We recommend that programs follow these steps:
1. Create a TopicSession, and use it to create a Topic for requests and replies.
2. Create a TopicRequestor, using the topic session and topic as arguments.
3. Send a request and receive a reply. You may repeat this step for several request and reply pairs.
4. Close the requestor object. The Close method also closes the requestor’s session as a side effect.
See Also Topic on page 76TopicSession on page 197
Method Description Page
TopicRequestor Create a topic requestor. 113
TopicRequestor.Close Close a topic requestor. 114
TopicRequestor.Request Send a request message; wait for a reply and return it.
115
TIBCO Enterprise Message Service .NET Reference
TopicRequestor | 113
TopicRequestorConstructor
Declaration TopicRequestor (TopicSession session,Topic topic );
Purpose Create a topic requestor.
Parameter Description
session The requestor operates within this topic session.
This session must not use transaction semantics. Its delivery mode must be either AutoAcknowledge or DupsOkAcknowledge.
The Close method also closes this session as a side effect.
topic The requestor sends request messages to this topic, and waits for replies on the same topic.
You must create this topic using the topic session you supply as the first argument.
TIBCO Enterprise Message Service .NET Reference
114 | Chapter 6 Requestor
TopicRequestor.CloseMethod
Declaration void Close ();
Purpose Close a topic requestor.
Remarks This method also closes the requestor’s session as a side effect.
TIBCO Enterprise Message Service .NET Reference
TopicRequestor.Request | 115
TopicRequestor.RequestMethod
Declaration Message Request(Message message );
Purpose Send a request message; wait for a reply and return it.
Remarks The requestor receives only the first reply. It discards other replies that arrive subsequently.
Parameter Description
message Send this request message.
TIBCO Enterprise Message Service .NET Reference
116 | Chapter 6 Requestor
TIBCO Enterprise Message Service .NET Reference
| 117
Chapter 7 Connection
Connection objects represent a client program’s network connection to the server.
Topics
• Connection, page 118
• ConnectionMetaData, page 125
• QueueConnection, page 126
• TopicConnection, page 128
• EMSExceptionHandler, page 130
• EMSExceptionEventArgs, page 131
• IExceptionListener, page 133
TIBCO Enterprise Message Service .NET Reference
118 | Chapter 7 Connection
ConnectionClass
Declaration class Connection
Purpose Encapsulate a server connection.
Subclasses QueueConnection on page 126TopicConnection on page 128
Remarks When a program first opens a connection, the connection is stopped—that is, it does not deliver inbound messages. To begin the flow of inbound messages, the program must explicitly call the Start method. (Outbound messages flow even before calling Start.)
The EMS .NET API does not support the optional methods createConnectionConsumer and createDurableConnectionConsumer.
AsynchronousExceptions
When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program (synchronously) by throwing exceptions.
However, when a program uses a connection only to receive messages, the client cannot catch such exceptions. Instead, programs can handle such exceptions asynchronously in one of two idioms. Programmers may select either idiom—but not both (which would cause duplicate exception processing, with undefined behavior).
• ExceptionHandler events detect this type of problem in a .NET programming idiom.
• In contrast, the ExceptionListener property mimics the way in which JMS provides similar functionality in a Java programming idiom.
Member Description
Events
ExceptionHandler EMSExceptionHandler
The client library raises an event if it detects a problem with the connection. The program implements a handler delegate to processes it asynchronously, and registers the delegate here. See Asynchronous Exceptions, above. See EMSExceptionHandler on page 130.
TIBCO Enterprise Message Service .NET Reference
Connection | 119
Properties
ActiveURL string {get;}
This property holds the URL of the server at the other endpoint of the connection. When the connection interacts with several servers in a fault-tolerant arrangement, this property indicates the current active server.
ClientID string {get; set;}
This property holds the unique client ID of the connection.
Client IDs partition the namespace of durable subscribers; see Session.CreateDurableSubscriber on page 181.
Administrators can configure ConnectionFactory objects to assign client IDs to new connections. Alternatively, administrators can allow client programs to assign their own IDs. If the factory does not assign an ID, the program may set this property. However, it is illegal to overwrite an existing client ID value, and or to set this property after using the connection in any way (for example, after creating a session, or starting the connection); attempting to set this property in these situations results in IllegalStateException.
ExceptionListener IExceptionListener {get; set;}
This is an alternate pathway for alerting a client program of connection problems. The program implements the exception listener interface, and registers an exception listener object by setting this property. When the client library detects a connection problem, it calls the listener’s onException method with an exception argument that details the problem.
See Asynchronous Exceptions, above. See IExceptionListener on page 133.
IsClosed bool {get;}
This property is true if the connection has been closed; otherwise false.
IsSecure bool {get;}
This property is true if the connection communicates with a secure protocol; otherwise false.
Member Description
TIBCO Enterprise Message Service .NET Reference
120 | Chapter 7 Connection
MetaData ConnectionMetaData {get;}
Programs can get the connection’s metadata object.
Member Description
Method Description Page
Connection.Close Close the connection; reclaim resources. 121
Connection.CreateSession Create a session object. 122
Connection.Start Start delivering inbound messages. 123
Connection.Stop Stop delivering inbound messages. 124
TIBCO Enterprise Message Service .NET Reference
Connection.Close | 121
Connection.CloseMethod
Declaration virtual void Close();
Purpose Close the connection; reclaim resources.
Remarks Closing the connection is sufficient to reclaim all of its resources; you need not separately close the sessions, producers, and consumers associated with the connection.
Closing a connection deletes all temporary destinations associated with the connection.
Blocking If any message listener or receive call associated with the connection is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes—that is, until all message listeners and receive calls have returned.
Acknowledge Closing a connection does not force acknowledgment in client-acknowledged sessions. When the program still has a message that it received from a connection that has since closed, its Message.Acknowledge method throws IllegalStateException.
Transactions Closing a connection rolls back all open transactions in all sessions associated with the connection.
See Also Message.Acknowledge on page 25MessageConsumer on page 80MessageProducer on page 94Destination on page 69Session on page 170IMessageListener on page 90IllegalStateException on page 312
TIBCO Enterprise Message Service .NET Reference
122 | Chapter 7 Connection
Connection.CreateSessionMethod
Declaration virtual Session CreateSession(bool transacted,QueueSession acknowledgeMode );
virtual Session CreateSession(bool transacted,int acknowledgeMode );
Purpose Create a session object.
Remarks The new session uses the connection for all server communications.
See Also Message.Acknowledge on page 25Session on page 170Acknowledge Modes on page 174QueueSession on page 196
Parameter Description
transacted When true, the new session has transaction semantics.
When false, it has non-transaction semantics.
acknowledgeMode This parameter determines the acknowledge mode of the session.
Supply a value enumerated by the members of QueueSession.
For backward compatibility, you may also supply an integer value from the members of Session.
TIBCO Enterprise Message Service .NET Reference
Connection.Start | 123
Connection.StartMethod
Declaration virtual void Start();
Purpose Start delivering inbound messages.
Remarks When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this method to explicitly start it.
If the connection is not stopped, this call has no effect.
Outbound messages flow even before calling Start.
See Also Connection.Stop on page 124
TIBCO Enterprise Message Service .NET Reference
124 | Chapter 7 Connection
Connection.StopMethod
Declaration virtual void Stop();
Purpose Stop delivering inbound messages.
Remarks This call temporarily stops the connection from delivering inbound messages. A program can restart delivery by calling Connection.Start.
When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this method to explicitly start it.
If the connection is already stopped, this call has no effect.
Effect When this call returns, the connection has stopped delivery to all consumers associated with the connection:
• Messages do not arrive to trigger asynchronous message handler events, nor message listeners.
• Synchronous receive methods block. If their timeout intervals expire, they return null.
Blocking If any message listener or receive call associated with the connection is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes—that is, until all message listeners and receive calls have returned.
However, the stopped connection prevents the client program from processing any new messages.
Sending A stopped connection can still send outbound messages.
See Also Connection.Start on page 123
TIBCO Enterprise Message Service .NET Reference
ConnectionMetaData | 125
ConnectionMetaDataClass
Declaration class ConnectionMetaData
Purpose Information about the provider.
Remarks Programs can retrieve this object from a connection; see MetaData on page 120.
Member Description
Properties
JMSXPropertyNames System.Collections.IEnumerator {get;}
Enumerates the JMS message properties; see JMS Properties on page 17.
MajorVersion int {get;}
Major version number of the JMS specification that the provider supports.
MinorVersion int {get;}
Minor version number of the JMS specification that the provider supports.
Version string {get;}
Version number of the JMS specification that the provider supports.
ProviderMajorVersion int {get;}
Major version number of the provider (EMS).
ProviderMinorVersion int {get;}
Minor version number of the provider (EMS).
ProviderVersion string {get;}
Version number of the provider (EMS).
ProviderName string {get;}
Vendor name of the provider.
TIBCO Enterprise Message Service .NET Reference
126 | Chapter 7 Connection
QueueConnectionClass
Declaration class QueueConnection : Connection
Purpose Backward compatibility. Connection restricted to queue operations.
Remarks This class supports existing programs that use it.
For new programs, we recommend using the more general class, Connection on page 118, instead.
Method Description Page
QueueConnection.CreateQueueSession Backward compatibility. Create a queue session object.
127
TIBCO Enterprise Message Service .NET Reference
QueueConnection.CreateQueueSession | 127
QueueConnection.CreateQueueSessionMethod
Declaration virtual QueueSession CreateQueueSession(bool transacted,QueueSession acknowledgeMode );
virtual QueueSession CreateQueueSession(bool transacted,int acknowledgeMode );
Purpose Backward compatibility. Create a queue session object.
Remarks The new queue session uses the connection for all server communications.
See Also Message.Acknowledge on page 25QueueSession on page 196Acknowledge Modes on page 174QueueSession on page 196
Parameter Description
transacted When true, the new session has transaction semantics.
When false, it has non-transaction semantics.
acknowledgeMode This parameter determines the acknowledge mode of the session.
Supply a value enumerated by the members of QueueSession.
For backward compatibility, you may also supply an integer value from the members of Session.
TIBCO Enterprise Message Service .NET Reference
128 | Chapter 7 Connection
TopicConnectionClass
Declaration class TopicConnection : Connection
Purpose Backward compatibility. Connection restricted to topic operations.
Remarks This class supports existing programs that use it.
For new programs, we recommend using the more general class, Connection on page 118, instead.
Method Description Page
TopicConnection.CreateTopicSession Backward compatibility. Create a topic session object.
129
TIBCO Enterprise Message Service .NET Reference
TopicConnection.CreateTopicSession | 129
TopicConnection.CreateTopicSessionMethod
Declaration virtual TopicSession CreateTopicSession(bool transacted,QueueSession acknowledgeMode );
virtual TopicSession CreateTopicSession(bool transacted,int acknowledgeMode );
Purpose Backward compatibility. Create a topic session object.
Remarks The new topic session uses the connection for all server communications.
See Also Message.Acknowledge on page 25TopicSession on page 197Acknowledge Modes on page 174QueueSession on page 196
Parameter Description
transacted When true, the new session has transaction semantics.
When false, it has non-transaction semantics.
acknowledgeMode This parameter determines the acknowledge mode of the session.
Supply a value enumerated by the members of QueueSession.
For backward compatibility, you may also supply an integer value from the members of Session.
TIBCO Enterprise Message Service .NET Reference
130 | Chapter 7 Connection
EMSExceptionHandlerDelegate
Declaration delegate void EMSExceptionHandler(object sender,EMSExceptionEventArgs args );
Purpose Asynchronously detect problems with connections.
Remarks When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program by throwing exceptions. However, when a program uses a connection only to receive messages, the client cannot catch such exceptions.
This delegate provides an alternate pathway for alerting a client program of connection problems. The program implements this delegate, and registers it with the connection. When the client library detects a connection problem, it raises an event. This delegate processes the event, which contains an exception that details the problem.
EMSExceptionHandler detects this type of problem in a .NET programming idiom. In contrast, IExceptionListener mimics the way in which JMS provides similar functionality in a Java programming idiom. Programmers may select either idiom—but not both (which would cause duplicate exception processing, with undefined behavior).
Example 2 Exception Event Handler...connection.ExceptionHandler += new EMSExceptionHandler(handleEx);...private void handleEx(object sender, EMSExceptionEventArgs arg){
EMSException e = arg.Exception;Console.WriteLine("Exception: " + e.Message);
}...
See Also Connection on page 118EMSExceptionHandler on page 130EMSExceptionEventArgs on page 131
Parameter Description
sender The problematic connection object.
args The event, which contains the exception object.
TIBCO Enterprise Message Service .NET Reference
EMSExceptionEventArgs | 131
EMSExceptionEventArgsClass
Declaration class EMSMessageEventArgs : EventArgs
Purpose Present a connection problem as a .NET event.
Remarks EMSExceptionHandler delegates receive this object as an argument.
See Also EMSExceptionHandler on page 130
Member Description
Properties
Exception EMSException {get;}
Programs can get the exception that details the problem.
Method Description Page
EMSMessageEventArgs Constructor. 89
TIBCO Enterprise Message Service .NET Reference
132 | Chapter 7 Connection
EMSExceptionEventArgsConstructor
Declaration EMSExceptionEventArgs(EMSException emse );
Purpose Create an exception event.
Parameter Description
emse The new event encapsulates this exception, and signals its arrival.
TIBCO Enterprise Message Service .NET Reference
IExceptionListener | 133
IExceptionListenerInterface
Declaration interface IExceptionListener
Purpose Asynchronously detect problems with connections.
Remarks When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program by throwing exceptions. However, when a program uses a connection only to receive messages, the client cannot catch such exceptions.
This interface provides an alternate pathway for alerting a client program of connection problems. The program implements this interface, and registers an exception listener with the connection object. When the client library detects a connection problem, it calls the listener’s onException method with an exception argument that details the problem.
IExceptionListener mimics the way in which JMS detects this type of problem in a Java programming idiom. In contrast, EMSExceptionHandler provides similar functionality in a .NET idiom. Programmers may select either idiom—but not both (which would cause duplicate exception processing, with undefined behavior).
See Also Connection on page 118EMSExceptionHandler on page 130
Method Description Page
IExceptionListener.OnException Handle connection exceptions asynchronously. 134
TIBCO Enterprise Message Service .NET Reference
134 | Chapter 7 Connection
IExceptionListener.OnExceptionMethod
Declaration void OnException(EMSException exception );
Purpose Handle connection exceptions asynchronously.
Parameter Description
exception Handle this exception.
TIBCO Enterprise Message Service .NET Reference
| 135
TIBCO Enterprise Message Service .NET Reference
136 | Chapter 7 Connection
TIBCO Enterprise Message Service .NET Reference
| 137
Chapter 8 Connection Factory
Connection factories let administrators preconfigure client connections to the EMS server.
Topics
• ConnectionFactory, page 138
• QueueConnectionFactory, page 161
• TopicConnectionFactory, page 164
• QueueConnectionFactory, page 161
TIBCO Enterprise Message Service .NET Reference
138 | Chapter 8 Connection Factory
ConnectionFactoryClass
Declaration class ConnectionFactory
Purpose Administered object for creating server connections.
Subclasses QueueConnectionFactory on page 161TopicConnectionFactory on page 164
Remarks Connection factories are administered objects. They support concurrent use.
Administrators define connection factories in a repository. Each connection factory has administrative parameters that guide the creation of server connections. Usage follows either of two models:
EMS Server You can use the EMS server as a name service provider—one tibemsd process provides both the name repository and the message service. Administrators define factories in the name repository. Client programs create connection factory objects with the URL of the repository, and call the ConnectionFactory.CreateConnection method. This method automatically accesses the corresponding factory in the repository, and uses it to create a connection to the message service.
Separate JNDIRepository
Administrators define factories in a JNDI repository. Client programs call LookupContext.Lookup to retrieve factories, and use them to create connections to the server.
Member Description
Properties
Metric QueueConnectionFactory Metric {get; set;}
When the connection factory balances the client load among several servers, it uses this metric to determine the least loaded server, so the connection factory can create a connection to it. For values, see QueueConnectionFactory on page 161.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory | 139
Method Description Page
ConnectionFactory Constructor. 141
ConnectionFactory.Clone Overrides the cloning process 142
ConnectionFactory.CreateConnection Create a connection object. 142
ConnectionFactory.GetSSLProxyHost Get the SSL proxy host from this connection factory.
ConnectionFactory.GetSSLProxyPassword Get the SSL proxy password from a connection factory.
ConnectionFactory.GetSSLProxyPort Get the SSL proxy port from this connection factory.
ConnectionFactory.GetSSLProxyUser Get the SSL proxy username from a connection factory.
ConnectionFactory.SetCertificateStoreType Set the certificate store type and info.
ConnectionFactory.SetClientID Set the client id.
ConnectionFactory.SetClientTracer Set the client tracer to given output stream.
ConnectionFactory.SetConnAttemptCount Set the number of connection attempts.
ConnectionFactory.SetConnAttemptDelay Set the delay between connection attempts.
ConnectionFactory.SetConnAttemptTimeout Set the Connect Attempt timeout for a given connection.
ConnectionFactory.SetHostNameVerifier Set the custom host name verifier.
ConnectionFactory.SetMetric Set the load balance metric.
ConnectionFactory.SetReconnAttemptCount Set the number of reconnect attempts.
ConnectionFactory.SetReconnAttemptDelay Set the delay between reconnection attempts.
TIBCO Enterprise Message Service .NET Reference
140 | Chapter 8 Connection Factory
AdministeredObjects
Administered objects let administrators configure EMS behavior at the enterprise level. Administrators define these objects, and client programs use them. This arrangement relieves program developers and end users of the responsibility for correct configuration.
See Also LookupContext on page 215
ConnectionFactory.SetReconnAttemptTimeout Set the Reconnect Attempt timeout for a given connection.
ConnectionFactory.SetServerUrl Set the server URL.
ConnectionFactory.SetSSLAuthOnly Enable or disable auth only for the SSL connection.
ConnectionFactory.SetSSLProxy Set the connection factory's parameters for connecting through an SSL proxy.
ConnectionFactory.SetSSLProxyAuth Set a connection factory's username and password for connecting through an SSL proxy.
ConnectionFactory.SetSSLTrace Enable or disable tracing on the client side.
ConnectionFactory.SetTargetHostName Set the name of the target EMS server.
ConnectionFactory.SetUserName Set user name.
ConnectionFactory.SetUserPassword Set user password.
Method Description Page
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory | 141
ConnectionFactoryConstructor
Declaration ConnectionFactory(string serverUrl,string clientId,Hashtable properties );
ConnectionFactory(string serverUrl,string clientId );
ConnectionFactory(string serverUrl );
ConnectionFactory();
Purpose Create a connection factory.
Remarks When administrators define factories in the EMS server, these constructors automatically access the corresponding objects in the repository.
Reconnect andFault Tolerance
To enable reconnection behavior and fault tolerance, the serverURL parameter must be a comma-separated list of two or more URLs. In a situation with only one server, you may supply two copies of that server’s URL to enable client reconnection (for example, tcp://localhost:7222,tcp://localhost:7222).
See Also LookupContext on page 215
Parameter Description
serverUrl The constructor contacts the EMS server at this URL, to access a factory.
If connecting a fault-tolerant client, specify two or more comma-separated URLs, as described below inReconnect and Fault Tolerance.
clientId A client ID string lets the server associate a client-specific factory with each client program. When present, the server supplies that factory to the client. If a factory does not yet exist for the client, the server creates one, and stores it for future use by that specific client.
properties When present, these properties govern the behavior of the connection objects that a client-specific factory creates. For a list of properties, see Connection-Related Fields (Constants) on page 265.
TIBCO Enterprise Message Service .NET Reference
142 | Chapter 8 Connection Factory
ConnectionFactory.CloneMethod
Declaration override object Clone();
Purpose Overrides the cloning process
ConnectionFactory.CreateConnectionMethod
Declaration Connection CreateConnection(string userName,string password );
Connection CreateConnection();
Purpose Create a connection object.
When the identity parameters are absent, the connection object presents a default user identity. If the server configuration permits that user, then the call succeeds.
See Also Connection on page 118
Parameter Description
userName The connection object presents this user identity to the server. This parameter can be omitted if the server isn’t authenticating or authorizing users.
password The connection object authenticates the user identity with this password. This parameter can be omitted if the server isn’t authenticating or authorizing users.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.GetSSLProxyHost | 143
ConnectionFactory.GetSSLProxyHostMethod
Declaration string GetSSLProxyHost();
Purpose Get the SSL proxy host from this connection factory.
ConnectionFactory.GetSSLProxyPasswordMethod
Declaration string GetSSLProxyPassword();
Purpose Get the SSL proxy password from a connection factory.
ConnectionFactory.GetSSLProxyPortMethod
Declaration int GetSSLProxyPort();
Purpose Get the SSL proxy port from this connection factory.
ConnectionFactory.GetSSLProxyUserMethod
Declaration string GetSSLProxyUser();
Purpose Get the SSL proxy username from a connection factory.
TIBCO Enterprise Message Service .NET Reference
144 | Chapter 8 Connection Factory
ConnectionFactory.SetCertificateStoreTypeMethod
Declaration void SetCertificateStoreType(EMSSSLStoreType type,object storeInfo
);
Purpose Set the certificate store type and info.
Parameter Description
type The type of certificate store. Can be either EMSSSL_STORE_TYPE_SYSTEM or EMSSSL_STORE_TYPE_FILE. See EMSSSLStoreType on page 257 for details.
storeInfo If the store type is EMSSSL_STORE_TYPE_SYSTEM, then storeInfo must be an EMSSSLSystemStoreInfo object. If the store type is EMSSSL_STORE_TYPE_FILE, then storeInfo must be an EMSSSLFileStoreInfo object.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetClientID | 145
ConnectionFactory.SetClientIDMethod
Declaration void SetClientID(string clientID);
Purpose Set the client id.
Throws EMSException if the specified client id already exists.
Parameter Description
clientID Client ID.
TIBCO Enterprise Message Service .NET Reference
146 | Chapter 8 Connection Factory
ConnectionFactory.SetClientTracerMethod
Declaration void SetClientTracer(StreamWriter tracer);
Purpose Set the client tracer to given output stream.
Remarks Client tracing prints loaded certificates and information about the SSL handshake errors and results.
Parameter Description
tracer The output stream to send the tracing information. Specify null as parameter to disable client tracing.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetConnAttemptCount | 147
ConnectionFactory.SetConnAttemptCountMethod
Declaration void SetConnAttemptCount(int attempts);
Purpose Set the number of connection attempts.
Remarks See Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide for details.
Parameter Description
attempts Number of connection attempts.
TIBCO Enterprise Message Service .NET Reference
148 | Chapter 8 Connection Factory
ConnectionFactory.SetConnAttemptDelayMethod
Declaration void SetConnAttemptDelay(int delay);
Purpose Set the delay between connection attempts.
Remarks See Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide for details.
Parameter Description
delay Time (in milliseconds) of the delay between connection attempts.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetConnAttemptTimeout | 149
ConnectionFactory.SetConnAttemptTimeoutMethod
Declaration void SetConnAttemptTimeout(int timeout);
Purpose Set the Connect Attempt timeout for a given connection.
Remarks This timeout is per url and per connect_attempt. For example, to specify two connect attempts for a given url, then for each attempt the client will wait for the period specified by the connect attempt timeout for the connection to be established. If no connection is established within that the specified timeframe, the client connection attempt is terminated.
See Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide for details.
Parameter Description
timeout Timeout (in milliseconds) for the connection.
TIBCO Enterprise Message Service .NET Reference
150 | Chapter 8 Connection Factory
ConnectionFactory.SetHostNameVerifierMethod
Declaration void SetHostNameVerifier(EMSSSLHostNameVerifier verifier
);
Purpose Set the custom host name verifier.
Parameter Description
verifier Host name verifier. Set to null to remove custom host name verifier.
See EMSSSLHostNameVerifier on page 255 for details.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetMetric | 151
ConnectionFactory.SetMetricMethod
Declaration void SetMetric(int metric);
Purpose Set the load balance metric.
Throws EMSException if invalid metric is passed.
Parameter Description
metric Load balance metric.
TIBCO Enterprise Message Service .NET Reference
152 | Chapter 8 Connection Factory
ConnectionFactory.SetReconnAttemptCountMethod
Declaration void SetReconnAttemptCount(int attempts);
Purpose Set the number of reconnect attempts.
Remarks See Reconnect Timeout in the TIBCO Enterprise Message Service User’s Guide for details.
Parameter Description
attempts Number of reconnection attempts.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetReconnAttemptDelay | 153
ConnectionFactory.SetReconnAttemptDelayMethod
Declaration void SetConnAttemptDelay( int delay);
Purpose Set the delay between reconnection attempts.
Parameter Description
attempts Time (in milliseconds) of the delay between reconnection attempts.
TIBCO Enterprise Message Service .NET Reference
154 | Chapter 8 Connection Factory
ConnectionFactory.SetReconnAttemptTimeoutMethod
Declaration void SetReconnAttemptTimeout(int timeout);
Purpose Set the Reconnect Attempt timeout for a given connection.
Remarks This timeout is per url and per reconnect_attempt. For example, to specify two reconnect attempts for a given url, then for each attempt the client will wait for the period specified by the reconnect attempt timeout for the connection to be established. If no reconnection is established within that the specified timeframe, the reconnection attempt is terminated.
Parameter Description
timeout Timeout (in milliseconds) for the reconnection attempt.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetServerUrl | 155
ConnectionFactory.SetServerUrlMethod
Declaration void SetServerUrl(string serverUrl);
Purpose Set the server URL.
Remarks The server URL is of the form:
protocol://hostName:portNumber
For example:
tcp://localhost:7222
The server URL for a fault-tolerant configuration is a string with multiple URL's that are comma separated.
For example:
tcp://localhost:7222,tcp://localhost:7224.
Throws EMSException if the URL is already set or some other error.
Parameter Description
serverUrl The server URL.
TIBCO Enterprise Message Service .NET Reference
156 | Chapter 8 Connection Factory
ConnectionFactory.SetSSLAuthOnlyMethod
Declaration SetSSLAuthOnly (bool authOnly);
Purpose Enable or disable auth only for the SSL connection.
Remarks For the client and server to require an SSL connection only to perform authentication, the ssl_auth_only parameter needs to be set on the server and AUTH_ONLY needs to be set by the client. Setting these flags on both the server and client side indicates that the SSL connection is only used to only perform authentication. Once authentication is complete, the client switches to a regular TCP connection to communicate with the server.
See the SSL Authentication Only section in the TIBCO Enterprise Message Service User’s Guide for details.
See Also EMSSSL.SetAuthOnly on page 242EMSSSL.GetAuthOnly on page 241
Parameter Description
authOnly • When true, AUTH_ONLY is enabled.
• When false, (the default) AUTH_ONLY is disabled.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetSSLProxy | 157
ConnectionFactory.SetSSLProxyMethod
Declaration void SetSSLProxy(string host,int port
);
Purpose Set the connection factory's parameters for connecting through an SSL proxy.
Remarks An SSL proxy lets an EMS application create an SSL connection to an EMS server, even though a firewall separates the application from the server. The proxy usually runs within the firewall's DMZ. A connection factory contacts the SSL proxy, requesting an SSL connection to the server. The proxy authenticates the application program, and mediates the initial SSL negotiation between application and server. After the SSL connection is established, the application and server use it to communicate directly with one another.
Throws EMSException if the proxy host is null or empty, the port is zero or the protocol of the connection factory's URL is not SSL.
Parameter Description
host The connection factory establishes SSL communication through a web proxy at this host. Supply a simple hostname, a fully qualified hostname with domain name, or an IP address (dot notation).
port The connection factory establishes SSL communication through a web proxy on this port.
TIBCO Enterprise Message Service .NET Reference
158 | Chapter 8 Connection Factory
ConnectionFactory.SetSSLProxyAuthMethod
Declaration public void SetSSLProxyAuth(string username,string password
);
Purpose Set a connection factory's username and password for connecting through an SSL proxy.
Remarks When a connection factory establishes an EMS server connection through an SSL proxy host, the proxy might first require authentication before facilitating a connection. When required, use this call to set that authentication data on the connection factory.
Throws EMSException if the protocol of the connection factory's URL is not SSL.
This proxy authentication data is distinct from the server authentication data, and from the SSL private key encryption password.
Parameter Description
username The connection factory authenticates itself to the SSL proxy using this username.
password The connection factory authenticates itself to the SSL proxy using this password.
TIBCO Enterprise Message Service .NET Reference
ConnectionFactory.SetSSLTrace | 159
ConnectionFactory.SetSSLTraceMethod
Declaration SetSSLTrace (bool tracing);
Purpose Enable or disable tracing on the client side.
Remarks Tracing will show information during the SSL handshake and on messages received and sent by the SSL link.
ConnectionFactory.SetTargetHostNameMethod
Declaration void SetTargetHostName(string targetHostName);
Purpose Set the name of the target EMS server.
Remarks This is a required parameter for all .NET SSL connections. Because System.Net.Security.SslStream requires a target host, this value is required.
Parameter Description
tracing • When true, tracing is enabled.
• When false, (the default) tracing is disabled.
Parameter Description
targetHostName The name of the server as defined in the server's certificate. Usually the server's HostName is specified as the CN in the server's certificate.
TIBCO Enterprise Message Service .NET Reference
160 | Chapter 8 Connection Factory
ConnectionFactory.SetUserNameMethod
Declaration void SetUserName(string username);
Purpose Set user name.
ConnectionFactory.SetUserPasswordMethod
Declaration void SetUserPassword(string password);
Purpose Set user password.
Parameter Description
username User name.
Parameter Description
password Password.
TIBCO Enterprise Message Service .NET Reference
QueueConnectionFactory | 161
QueueConnectionFactoryClass
Declaration class QueueConnectionFactory : ConnectionFactory
Purpose Backward compatibility. Administered object for creating queue connections.
Remarks This class supports existing programs that use it.
For new programs, we recommend using the more general class, ConnectionFactory on page 138, instead.
Method Description Page
QueueConnectionFactory Constructor.
Same method signatures as the constructors for ConnectionFactory on page 141.
—
QueueConnectionFactory.CreateQueue
Connection
Create a queue connection object. 162
QueueConnectionFactory.Clone Implementation of ICloneable.Clone. 163
TIBCO Enterprise Message Service .NET Reference
162 | Chapter 8 Connection Factory
QueueConnectionFactory.CreateQueueConnectionMethod
Declaration QueueConnection CreateQueueConnection(string userName,string password );
QueueConnection CreateQueueConnection();
Purpose Create a queue connection object.
Remarks When the identity parameters are absent, the connection object presents a default user identity. If the server configuration permits that user, then the call succeeds.
See Also QueueConnection on page 126
Parameter Description
userName When present, the connection object presents this user identity to the server.
password When present, the connection object authenticates the user identity with this password.
TIBCO Enterprise Message Service .NET Reference
QueueConnectionFactory.Clone | 163
QueueConnectionFactory.CloneMethod
Declaration override object Clone();
Purpose Implementation of ICloneable.Clone.
Remarks Overrides the Clone process. Returns an object that is a clone of this QueueConnectionFactory instance.
TIBCO Enterprise Message Service .NET Reference
164 | Chapter 8 Connection Factory
TopicConnectionFactoryClass
Declaration class TopicConnectionFactory : ConnectionFactory
Purpose Backward compatibility. Administered object for creating topic connections.
Remarks This class supports existing programs that use it.
For new programs, we recommend using the more general class, ConnectionFactory on page 138, instead.
Method Description Page
TopicConnectionFactory Constructor.
Same method signatures as the constructors for ConnectionFactory on page 141.
—
TopicConnectionFactory.CreateTopic
Connection
Create a topic connection object. 165
TopicConnectionFactory.Clone Implementation of ICloneable.Clone. 166
TIBCO Enterprise Message Service .NET Reference
TopicConnectionFactory.CreateTopicConnection | 165
TopicConnectionFactory.CreateTopicConnectionMethod
Declaration TopicConnection CreateTopicConnection(string userName,string password );
TopicConnection CreateTopicConnection();
Purpose Create a topic connection object.
Remarks When the identity parameters are absent, the connection object presents a default user identity. If the server configuration permits that user, then the call succeeds.
See Also TopicConnection on page 128
Parameter Description
userName When present, the connection object presents this user identity to the server.
password When present, the connection object authenticates the user identity with this password.
TIBCO Enterprise Message Service .NET Reference
166 | Chapter 8 Connection Factory
TopicConnectionFactory.CloneMethod
Declaration override object Clone();
Purpose Implementation of ICloneable.Clone.
Remarks Overrides the Clone process. Returns an object that is a clone of this TopicConnectionFactory instance.
TIBCO Enterprise Message Service .NET Reference
FactoryLoadBalanceMetric | 167
FactoryLoadBalanceMetricClass
Declaration enum FactoryLoadBalanceMetric
Purpose Define enumerated load balancing constants.
Remarks When a connection factory balances the client load among several servers, it uses this metric to determine the least loaded server, so the connection factory can create a connection to it.
See Also ConnectionFactory on page 138
Member Description
Fields
None Indicates absence of any load balancing metric.
Connections The connection factory balances the connection load among several servers by creating a connection to the server with the fewest number of connections.
ByteRate The connection factory balances the connection load among several servers by creating a connection to the server with the lowest total byte rate (input and output).
TIBCO Enterprise Message Service .NET Reference
168 | Chapter 8 Connection Factory
TIBCO Enterprise Message Service .NET Reference
| 169
Chapter 9 Session
A session is a single-threaded context for producing and consuming messages.
Topics
• Session, page 170
• QueueSession, page 196
• TopicSession, page 197
• SessionMode, page 198
TIBCO Enterprise Message Service .NET Reference
170 | Chapter 9 Session
SessionClass
Declaration class Session
Purpose Main organizing context for message activity.
Subclasses QueueSession on page 196TopicSession on page 197
Remarks Sessions combine several roles:
• Factory for message producers and consumers
• Factory for message objects
• Factory for temporary destinations
• Factory for dynamic destinations
• Factory for queue browsers
• Serializer for inbound and outbound messages
• Serializer for asynchronous message events (or message listeners) of its consumer objects
• Cache for inbound messages (until the program acknowledges them).
• Transaction support (when enabled).
Single Thread The JMS specification restricts programs to use each session within a single thread.
AssociatedObjects
The same single-thread restriction applies to objects associated with a session—namely, messages, message consumers, durable subscribers, message producers, queue browsers, and temporary destinations (however, static and dynamic destinations are exempt from this restriction).
Corollary One consequence of this rule is that all the consumers of a session must deliver messages in the same mode—either synchronously or asynchronously.
Asynchronous In asynchronous delivery, the program registers message handler events or message listeners with the session’s consumer objects. An internal dispatcher thread delivers messages to those event handlers or listeners (in all the session’s consumer objects). No other thread may use the session (nor objects created by the session).
TIBCO Enterprise Message Service .NET Reference
Session | 171
Synchronous In synchronous delivery, the program explicitly begins a thread for the session. That thread processes inbound messages and produces outbound messages, serializing this activity among the session’s producers and consumers. Methods that request the next message (such as MessageConsumer.Receive) can organize the thread’s activity.
Close The only exception to the rule restricting session calls to a single thread is the method Session.Close; programs can call Close from any thread at any time.
Transactions A session has either transaction or non-transaction semantics. When a program specifies transaction semantics, the session object cooperates with the server, and all messages that flow through the session become part of a transaction.
• When the program calls Session.Commit, the session acknowledges all inbound messages in the current transaction, and the server delivers all outbound messages in the current transaction to their destinations.
• If the program calls Session.Rollback, the session recovers all inbound messages in the current transaction (so the program can consume them in a new transaction), and the server destroys all outbound messages in the current transaction.
After these actions, both Commit and Rollback immediately begin a new transaction.
Member Description
Properties
AcknowledgeMode int {get;}
This mode governs message acknowledgement and redelivery for consumers associated with the session. For values, see Acknowledge Modes on page 174.
This property is irrelevant when IsTransacted is true.
SessionAcknowledgeMode QueueSession {get;}
This parallel property accesses the same information using enumerated values (instead of ordinary integers). We recommend it over the ordinary integer-valued accessor, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability. For values, see QueueSession on page 196.
TIBCO Enterprise Message Service .NET Reference
172 | Chapter 9 Session
Connection Connection {get;}
The session is associated with this connection.
IsClosed bool {get;}
When true, the session has been closed.
When false, the session is valid.
MessageListener IMessageListener {get; set;}
This property is deprecated; use the property of MessageConsumer with same name—MessageListener on page 80, or MessageHandler on page 80.
SessID long {get;}
Session ID.
IsTransacted bool {get;}
When true, the session has transaction semantics, and AcknowledgeMode is irrelevant.
When false, it has non-transaction semantics.
Member Description
Method Description Page
Messages
Session.CreateBytesMessage Create a byte array message. 179
Session.CreateMapMessage Create a map message. 183
Session.CreateObjectMessage Create an object message. 184
Session.CreateStreamMessage Create a stream message. 187
Session.CreateTextMessage Create a text message. 190
TIBCO Enterprise Message Service .NET Reference
Session | 173
Destinations
Session.CreateBrowser Create a queue browser. 178
Session.CreateTemporaryQueue Create a temporary queue. 188
Session.CreateTemporaryTopic Create a temporary topic. 189
Session.CreateQueue Create a queue. 186
Session.CreateTopic Create a topic. 191
Consumers & Producers
Session.CreateConsumer Create a message consumer. 180
Session.CreateDurableSubscriber Create a durable topic subscriber. 181
Session.CreateProducer Create a message producer. 185
Session.Unsubscribe Unsubscribe a durable topic subscription. 195
Transactions
Session.Commit Commit the open transaction. 177
Session.Rollback Roll back messages in the current transaction. 193
Other
Session.Close Close a session; reclaim resources. 176
Session.Recover Recover from undetermined state during message processing.
192
Session.Run Obsolete. Do not call. 194
Method Description Page
TIBCO Enterprise Message Service .NET Reference
174 | Chapter 9 Session
Field Description
SESSION_TRANSACTED int
The IsTransacted property has this value (true) if the session uses transaction semantics.
Acknowledge Modes
AUTO_ACKNOWLEDGE int
In this mode, the session automatically acknowledges a message when message processing is finished—that is, in either of these methods returns successfully:
• synchronous Receive call
• asynchronous listener handler
CLIENT_ACKNOWLEDGE int
In this mode, the client program acknowledges receipt by calling Message.Acknowledge on page 25. Each call acknowledges all messages received so far.
DUPS_OK_ACKNOWLEDGE int
As with AUTO_ACKNOWLEDGE, the session automatically acknowledges messages. However, it may do so lazily. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. Lazy acknowledgement can reduce session overhead.
EXPLICIT_CLIENT_ACKNOWLEDGE int
As with CLIENT_ACKNOWLEDGE, the client program acknowledges receipt by calling Message.Acknowledge on page 25. However, each call acknowledges only the individual message. The client may acknowledge messages in any order.
This mode and behavior are proprietary extensions, specific to TIBCO EMS.
TIBCO Enterprise Message Service .NET Reference
Session | 175
EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE int
In EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE mode, the client program lazily acknowledges only the individual message, by calling Message.Acknowledge on page 25. The client may acknowledge messages in any order.
Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message.
This mode and behavior are proprietary extensions, specific to TIBCO EMS.
NO_ACKNOWLEDGE int
In NO_ACKNOWLEDGE mode, messages do not require acknowledgement (which reduces message overhead). The server never redelivers messages.
This mode is available for topic sessions only.
This mode and behavior are proprietary extensions, specific to TIBCO EMS.
Field Description
TIBCO Enterprise Message Service .NET Reference
176 | Chapter 9 Session
Session.CloseMethod
Declaration void Close();
Purpose Close a session; reclaim resources.
Remarks Closing a session automatically closes its consumers (except for durable subscribers), producers and browsers.
Blocking If any message listener or receive call associated with the session is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes—that is, until all message listeners and receive calls have returned.
Transactions Closing a session rolls back the open transaction in the session.
TIBCO Enterprise Message Service .NET Reference
Session.Commit | 177
Session.CommitMethod
Declaration virtual void Commit();
Purpose Commit the open transaction.
Remarks A session (with transaction semantics) always has exactly one open transaction. Message operations associated with the session become part of that transaction. This call commits all the messages within the transaction, and releases any locks. Then it opens a new transaction.
Throws EMSException on page 306TransactionRolledBackException on page 327IllegalStateException on page 312
TIBCO Enterprise Message Service .NET Reference
178 | Chapter 9 Session
Session.CreateBrowserMethod
Declaration QueueBrowser CreateBrowser(Queue queue,string messageSelector );
QueueBrowser CreateBrowser(Queue queue );
Purpose Create a queue browser.
Throws EMSException on page 306InvalidDestinationException on page 314InvalidSelectorException on page 316
See Also Queue on page 70QueueBrowser on page 202
Parameter Description
queue Browse this queue.
messageSelector When present, the browser presents only messages that match this selector; see Message Selectors on page 18.
When absent, null, or the empty string, the browser views all messages in the queue.
TIBCO Enterprise Message Service .NET Reference
Session.CreateBytesMessage | 179
Session.CreateBytesMessageMethod
Declaration BytesMessage CreateBytesMessage();
Purpose Create a byte array message.
See Also BytesMessage on page 32
TIBCO Enterprise Message Service .NET Reference
180 | Chapter 9 Session
Session.CreateConsumerMethod
Declaration MessageConsumer CreateConsumer(Destination dest,string messageSelector,bool noLocal );
MessageConsumer CreateConsumer(Destination dest,string messageSelector );
MessageConsumer CreateConsumer(Destination dest );
Purpose Create a message consumer.
Throws EMSException on page 306IllegalStateException on page 312InvalidDestinationException on page 314InvalidSelectorException on page 316
See Also Destination on page 69
Parameter Description
dest Create a consumer for this destination. The argument may be any destination (queue or topic).
messageSelector When present, the server filters messages using this selector, so the consumer receives only matching messages; see Message Selectors on page 18.
When absent, null, or the empty string, the consumer receives messages without filtering.
noLocal When true, the server filters messages so the consumer does not receive messages that originate locally—that is, messages sent through the same connection.
When absent or false, the consumer receives messages with local origin.
TIBCO Enterprise Message Service .NET Reference
Session.CreateDurableSubscriber | 181
Session.CreateDurableSubscriberMethod
Declaration TopicSubscriber CreateDurableSubscriber(Topic topic,string name,string messageSelector,bool noLocal );
TopicSubscriber CreateDurableSubscriber(Topic topic,string name );
Purpose Create a durable topic subscriber.
Remarks The server associates a durable subscription with at most one subscriber object at a time. When a subscriber object exists, the subscription is active, and the server delivers messages to it; when no subscriber object exists, the subscription is inactive.
Durable subscriptions guarantee message delivery across periods during which the subscriber is inactive. The server retains unacknowledged messages until the subscriber acknowledges them, or until the messages expire.
SubscriptionContinuity
Continuity across inactive periods uses two data items from the client:
• Subscription Name a parameter of this method
• Client ID an optional property of the Connection (used only when supplied)
Parameter Description
topic Create a durable subscriber for this topic (which cannot be a TemporaryTopic).
name This unique name lets the server associate the subscriber with a subscription.
messageSelector When present, the server filters messages using this selector, so the subscriber receives only matching messages; see Message Selectors on page 18.
When absent, null, or the empty string, the subscriber receives messages without filtering.
noLocal When true, the server filters messages so the subscriber does not receive messages that originate locally—that is, messages sent through the same connection.
When absent or false, the consumer receives messages with local origin.
TIBCO Enterprise Message Service .NET Reference
182 | Chapter 9 Session
The server uses one or both of these two items to match a subscriber object with its subscription. If a matching subscription exists, and it is inactive, then the server associates it with the subscriber (and the subscription becomes active). The server delivers unacknowledged messages to the subscriber.
If a matching subscription exists, but it is already active, this method throws EMSException.
If a matching subscription to the topic does not yet exist, the server creates one.
MatchingClient ID
• If the Connection’s client ID is non-null when a session creates a durable subscription, then only sessions of a connection with the same client ID can attach to that subscription.
• If the Connection’s client ID is null when a session creates a durable subscription, then any session can attach to that subscription (to receive its messages).
Changing Topicor Selector
Notice that the server does not use the topic and message selector arguments to match a subscriber to an existing subscription. As a result, client programs can change a subscription by altering either or both of these arguments. The effect is equivalent to deleting the existing subscription (from the server) and creating a new one (albeit with the same client ID and subscription name).
Throws EMSException on page 306IllegalStateException on page 312InvalidDestinationException on page 314InvalidSelectorException on page 316
See Also Topic on page 76Connection on page 118
TIBCO Enterprise Message Service .NET Reference
Session.CreateMapMessage | 183
Session.CreateMapMessageMethod
Declaration MapMessage CreateMapMessage();
Purpose Create a map message.
See Also MapMessage on page 41
TIBCO Enterprise Message Service .NET Reference
184 | Chapter 9 Session
Session.CreateObjectMessageMethod
Declaration ObjectMessage CreateObjectMessage(object obj );
ObjectMessage CreateObjectMessage();
Purpose Create an object message.
See Also ObjectMessage on page 48
Parameter Description
obj When present, use this object as data in the new message.
TIBCO Enterprise Message Service .NET Reference
Session.CreateProducer | 185
Session.CreateProducerMethod
Declaration MessageProducer CreateProducer(Destination dest );
Purpose Create a message producer.
Throws EMSException on page 306InvalidDestinationException on page 314
See Also MessageProducer on page 94
Parameter Description
dest When non-null, the producer sends messages to this destination.
When null, the client program must specify the destination for each message individually.
TIBCO Enterprise Message Service .NET Reference
186 | Chapter 9 Session
Session.CreateQueueMethod
Declaration Queue CreateQueue(string queueName );
Purpose Create a queue.
Remarks If the named queue already exists at the server, then this method returns that queue. (That queue can be either static or dynamic.)
If the named queue does not yet exist at the server, and the server allows dynamic queues, then this method creates a dynamic queue.
Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.
See Also Queue on page 70
Parameter Description
queueName Get or create the queue with this name.
TIBCO Enterprise Message Service .NET Reference
Session.CreateStreamMessage | 187
Session.CreateStreamMessageMethod
Declaration StreamMessage CreateStreamMessage();
Purpose Create a stream message.
See Also StreamMessage on page 50
TIBCO Enterprise Message Service .NET Reference
188 | Chapter 9 Session
Session.CreateTemporaryQueueMethod
Declaration TemporaryQueue CreateTemporaryQueue();
Purpose Create a temporary queue.
Remarks A temporary queue lasts no longer than the connection. That is, when the connection is closed or broken, the server deletes temporary queues associated with the connection.
See Also TemporaryQueue on page 72
TIBCO Enterprise Message Service .NET Reference
Session.CreateTemporaryTopic | 189
Session.CreateTemporaryTopicMethod
Declaration TemporaryTopic CreateTemporaryTopic();
Purpose Create a temporary topic.
Remarks A temporary topic lasts no longer than the connection. That is, when the connection is closed or broken, the server deletes temporary topic associated with the connection.
See Also TemporaryTopic on page 74
TIBCO Enterprise Message Service .NET Reference
190 | Chapter 9 Session
Session.CreateTextMessageMethod
Declaration TextMessage CreateTextMessage(string text);
TextMessage CreateTextMessage();
Purpose Create a text message.
See Also TextMessage on page 58
Parameter Description
text When present, use this string as data in the new message.
TIBCO Enterprise Message Service .NET Reference
Session.CreateTopic | 191
Session.CreateTopicMethod
Declaration Topic CreateTopic(string topicName );
Purpose Create a topic.
Remarks If the named topic already exists at the server, then this method returns that topic. (That topic can be either static or dynamic.)
If the named topic does not yet exist at the server, and the server allows dynamic topics, then this method creates a dynamic topic.
Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.
See Also Topic on page 76
Parameter Description
topicName Get or create the topic with this name.
TIBCO Enterprise Message Service .NET Reference
192 | Chapter 9 Session
Session.RecoverMethod
Declaration void Recover();
Purpose Recover from undetermined state during message processing.
Remarks Exceptions during message processing can sometimes leave a program in an ambiguous state. For example, some messages might be partially processed. This method lets a program return to an unambiguous state—the point within the message stream when the program last acknowledged the receipt of inbound messages. Programs can then review the messages delivered since that point (they are marked as redelivered), and resolve ambiguities about message processing.
Programs can also use this method to resolve similar ambiguities after a Connection stops delivering messages, and then starts again.
Operation This method requests that the server do this sequence of actions:
1. Stop message delivery within the session.
2. Mark as redelivered, any messages that the server has attempted to deliver to the session, but for which it has not received acknowledgement (that is, messages for which processing state is ambiguous).
According to the JMS specification, the server need not redeliver messages in the same order as it first delivered them.
3. Restart message delivery (including messages marked as redelivered in step 2).
When a session has transactional semantics, this method throws IllegalStateException (commit and rollback are more appropriate for transactions).
Throws EMSException on page 306IllegalStateException on page 312
TIBCO Enterprise Message Service .NET Reference
Session.Rollback | 193
Session.RollbackMethod
Declaration virtual void Rollback();
Purpose Roll back messages in the current transaction.
Remarks When a session does not have transactional semantics, this method throws IllegalStateException.
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.
Throws EMSException on page 306IllegalStateException on page 312
TIBCO Enterprise Message Service .NET Reference
194 | Chapter 9 Session
Session.RunMethod
Declaration void Run();
Purpose Obsolete. Do not call.
TIBCO Enterprise Message Service .NET Reference
Session.Unsubscribe | 195
Session.UnsubscribeMethod
Declaration void Unsubscribe(string name );
Purpose Unsubscribe a durable topic subscription.
Remarks This method deletes the subscription from the server.
It is illegal to delete an active subscription—that is, while a MessageConsumer or TopicSubscriber exists. Attempting to do so results in EMSException.
It is illegal to delete a subscription while one of its messages is either unacknowledged, or uncommitted (in the current transaction). Attempting to do so results in EMSException.
If the session is closed, this method throws IllegalStateException.
Throws EMSException on page 306IllegalStateException on page 312InvalidDestinationException on page 314
See Also MessageConsumer on page 80TopicSubscriber on page 86Topic on page 76Session.CreateDurableSubscriber on page 181
Parameter Description
name This name lets the server locate the subscription.
TIBCO Enterprise Message Service .NET Reference
196 | Chapter 9 Session
QueueSessionClass
Declaration class QueueSession : Session
Purpose Session restricted to queues.
Remarks Use this class with QueueRequestor objects.
Otherwise, when coding new programs, use the more general class, Session on page 170. Nonetheless, for backward compatibility, this class also supports existing programs that use it (rather than generic sessions).
See Also QueueRequestor on page 108
TIBCO Enterprise Message Service .NET Reference
TopicSession | 197
TopicSessionClass
Declaration class TopicSession : Session
Purpose Session restricted to topics.
Remarks Use this class with TopicRequestor objects.
Otherwise, when coding new programs, use the more general class, Session on page 170. Nonetheless, for backward compatibility, this class also supports existing programs that use it (rather than generic sessions).
See Also TopicRequestor on page 112
TIBCO Enterprise Message Service .NET Reference
198 | Chapter 9 Session
SessionModeEnumeration
Declaration enum SessionMode
Purpose Enumerate constants associated with sessions.
Members Description
SessionTransacted The IsTransacted property has this value if the session uses transaction semantics.
Acknowledge Modes
AutoAcknowledge In this mode, the session automatically acknowledges a message when message processing is finished—that is, in either of these methods returns successfully:
• synchronous Receive call
• asynchronous listener handler
ClientAcknowledge In this mode, the client program acknowledges receipt by calling Message.Acknowledge on page 25. Each call acknowledges all messages received so far.
DupsOkAcknowledge As with AutoAcknowledge, the session automatically acknowledges messages. However, it may do so lazily. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. Lazy acknowledgement can reduce session overhead.
ExplicitClientAcknowledge As with ClientAcknowledge, the client program acknowledges receipt by calling Message.Acknowledge on page 25. However, each call acknowledges only the individual message. The client may acknowledge messages in any order.
This mode and behavior are proprietary extensions, specific to TIBCO EMS.
TIBCO Enterprise Message Service .NET Reference
SessionMode | 199
ExplicitClientDupsOkAcknowledge In this mode, the client program lazily acknowledges only the individual message, by calling Message.Acknowledge on page 25. The client may acknowledge messages in any order.
Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message.
This mode and behavior are proprietary extensions, specific to TIBCO EMS.
NoAcknowledge In this mode, messages do not require acknowledgement (which reduces message overhead). The server never redelivers messages.
This mode is available for topic sessions only.
This mode and behavior are proprietary extensions, specific to TIBCO EMS.
Members Description
TIBCO Enterprise Message Service .NET Reference
200 | Chapter 9 Session
TIBCO Enterprise Message Service .NET Reference
| 201
Chapter 10 Queue Browser
Queue browsers let client programs examine the messages on a queue without removing them from the queue.
Topics
• QueueBrowser, page 202
TIBCO Enterprise Message Service .NET Reference
202 | Chapter 10 Queue Browser
QueueBrowserClass
Declaration class QueueBrowser : IEnumerator
Purpose Enumerate the messages in a queue without consuming them.
Remarks A browser is a dynamic enumerator of the queue (not a static snapshot). The queue is at the server, and its contents change as message arrive and consumers remove them. Meanwhile, while the browser is at the client. The method QueueBrowser.MoveNext asks the server for the next message after Current—that is, the next message that is still in the queue.
The browser can enumerate messages in a queue, or a subset filtered by a message selector.
Sessions serve as factories for queue browsers; see Session.CreateBrowser on page 178.
Member Description
Properties
Current object {get;}
This property presents the current message in the browser’s enumeration, but accessing the property does not consume that message.
The method QueueBrowser.MoveNext advances the current message.
MessageSelector string {get;}
The browser’s message selector expression filters the messages that the browser presents.
Queue Queue {get;}
The queue that this browser scans.
Method Description Page
QueueBrowser.Close Close the browser; reclaim resources. 204
TIBCO Enterprise Message Service .NET Reference
QueueBrowser | 203
See Also Session.CreateBrowser on page 178
QueueBrowser.GetEnumerator Get an enumerator of messages in the queue. 205
QueueBrowser.MoveNext Advance the browser’s enumeration to the next message.
206
QueueBrowser.Reset Reset the browser to the location before the first message.
207
Method Description Page
TIBCO Enterprise Message Service .NET Reference
204 | Chapter 10 Queue Browser
QueueBrowser.CloseMethod
Declaration void Close();
Purpose Close the browser; reclaim resources.
TIBCO Enterprise Message Service .NET Reference
QueueBrowser.GetEnumerator | 205
QueueBrowser.GetEnumeratorMethod
Declaration IEnumerator GetEnumerator();
Purpose Get an enumerator of messages in the queue.
Remarks This method returns the browser object—which is itself the enumerator.
TIBCO Enterprise Message Service .NET Reference
206 | Chapter 10 Queue Browser
QueueBrowser.MoveNextMethod
Declaration bool MoveNext();
Purpose Advance the browser’s enumeration to the next message.
Remarks A browser is a dynamic enumerator of the queue (not a static snapshot). The queue is at the server, and its contents change as message arrive and consumers remove them. Meanwhile, while the browser is at the client. This method asks the server for the next message after Current—that is, the next message that is still in the queue.
Returns true if another message exists; the Current property subsequently presents the next message.
Returns false otherwise.
After creating a browser, programs must first call this method to examine the first message.
TIBCO Enterprise Message Service .NET Reference
QueueBrowser.Reset | 207
QueueBrowser.ResetMethod
Declaration void Reset();
Purpose Reset the browser to the location before the first message.
TIBCO Enterprise Message Service .NET Reference
208 | Chapter 10 Queue Browser
TIBCO Enterprise Message Service .NET Reference
| 209
Chapter 11 Name Server Lookup
Lookup context objects find named objects (such as connection factories and destinations) in the name repository. (The EMS server, tibemsd, provides the name repository service).
Topics
• ILookupContext, page 210
• LookupContext, page 215
• LookupContextFactory, page 221
• LdapLookupConsts, page 224
• LdapLookupContext, page 226
• LdapLookupSSLParams, page 231
TIBCO Enterprise Message Service .NET Reference
210 | Chapter 11 Name Server Lookup
ILookupContextInterface
Declaration interface ILookupContext
Purpose The initial context used to look up administered objects in either an EMS server or a third-party LDAP server.
Remarks ILookupContext is implemented by the LookupContext and LdapLookupContext classes. LookupContext is mainly used to lookup up JMS administered objects in the TIBCO EMS server, whereas LdapLookupContext is used for looking up JMS administered objects in an LDAP server.
Users obtain an object of type ILookupContext (implemented by LookupContext and LdapLookupContext) by calling the LookupContextFactory.CreateContext method.
Requirements Namespace: TIBCO.EMSAssembly: TIBCO.EMS (in TIBCO.EMS.dll)
Member Description
Settings System.Collections.Hashtable Settings {get;}
Return the current settings of this lookup context.
Method Description Page
ILookupContext.AddSettings Add settings to the lookup context. 211
ILookupContext.Lookup Lookup up an object by name in an LDAP or TIBCO EMS Naming server.
212
ILookupContext.RemoveSettings Remove a lookup context setting by name. 214
TIBCO Enterprise Message Service .NET Reference
ILookupContext.AddSettings | 211
ILookupContext.AddSettingsMethod
Declaration object AddSettings(string propName, object propValue);
void AddSettings(Hashtable table);
Purpose Add settings to the lookup context.
Remarks You can add settings to the lookup context by either passing a hash table or a property/value pair.
Setting added to the lookup context are mainly LDAP or TIBCO EMS Naming Server related parameters used for looking up objects stored in an LDAP server or TIBCO EMS Server. Examples of setting names include LDAP_SERVER_URL or LDAP_BASE_DN.
Examples To add settings contained in a hash table:
Hashtable table = new Hashtable();LookupContextFactory contextFactory =
new LookupContextFactory();ILookupContext searcher = contextFactory.Create("ldap", table); searcher.AddSettings(table);
To add settings directly:
Hashtable table = new Hashtable();LookupContextFactory contextFactory =
new LookupContextFactory();ILookupContext searcher = contextFactory.Create("ldap", table); searcher.AddSettings(LdapLookupConsts.LDAP_SERVER_URL,
"adc1.na.tibco.com:10389");
Parameter Description
propName Set this single property.
For property names, see Fields on page 215.
propValue Set the single property to this value.
table Set all the name-value pairs contained in this hash table.
TIBCO Enterprise Message Service .NET Reference
212 | Chapter 11 Name Server Lookup
ILookupContext.LookupMethod
Declaration object Lookup(string name);
Purpose Lookup up an object by name in an LDAP or TIBCO EMS Naming server.
Remarks This method looks up an object in either an LDAP or TIBCO EMS Naming server, depending on which interface is asked for in the LookupContextFactory.
Ldap related information
If the context initialized is LDAP context, the Lookup method initializes the LDAP connection environment; searches for the object in the LDAP server; constructs the object, and the returns the object.
At a very high level, the lookup function performs a set of tasks for an LDAP context:
• Initializes the ldap connection environment, performs various checks to make sure the right parameters are passed in.
• Establishes a LDAP connection to the specified server
• Searches for the specified object in the LDAP server
• Once it receives the XML data for the specified administered object, it performs XML validation (i.e.) through the specified DTD.
• Retrieves the object properties stored as XML.
• Constructs the object and then returns the object.
Example This example demonstrates how to lookup a connection factory object in an LDAP server:
LookupContextFactory contextFactory = new LookupContextFactory();ILookupContext searcher = contextFactory.Create("ldap", table); ConnectionFactory cf =
(ConnectionFactory)searcher.Lookup("cn='testConnFact");
Parameter Description
name Name of the object to lookup.
TIBCO Enterprise Message Service .NET Reference
ILookupContext.Lookup | 213
Throws NamingException if we cannot connect to the ldap server or we cannot connect to the TIBCO EMS Naming server if the context is tibjmsnaming context or we cannot find the object or some other exception.
ConfigurationException if the url or basedn or principal or credential or any combinations of the required parameters are missing.
TIBCO Enterprise Message Service .NET Reference
214 | Chapter 11 Name Server Lookup
ILookupContext.RemoveSettingsMethod
Declaration object RemoveSettings(string propName);
Purpose Remove a lookup context setting by name.
Example Add and then remove the LDAP_SERVER_URL property from the lookup context:
Hashtable table = new Hashtable();table.Add(LdapLookupConsts.LDAP_SERVER_URL,
"adc1.na.tibco.com:10389");LookupContextFactory contextFactory = new LookupContextFactory();ILookupContext searcher = contextFactory.CreateContext(
"ldap", table); searcher.RemoveSettings(LdapLookupConsts.LDAP_SERVER_URL);
Parameter Description
propName Name of the property to be removed from the lookup context.
TIBCO Enterprise Message Service .NET Reference
LookupContext | 215
LookupContextClass
Declaration class LookupContext
Purpose Search for and perform queries on administered objects in the EMS server.
Remarks The context object establishes communication with the EMS server, authenticates the user, and submits name queries.
The following is a list of properties used to connect to an EMS server and specifying the search scope for looking up EMS administered objects. See LdapLookupConsts on page 224 for the properties related to establishing a lookup context for a third-party LDAP server.
Member Description
Properties
Settings System.Collections.Hashtable {get;}
Programs can get a copy of the context’s current settings.
Fields
Programs use these constants as names of context settings (in argument hashtables or individually).
PROVIDER_URL string
URL of the naming server (EMS server).
SECURITY_CREDENTIALS string
User password of the client program.
SECURITY_PRINCIPAL string
User name of the client program.
URL_LIST string
ArrayList of URLs of naming servers (EMS servers).
This property lets programs specify URLs as an ArrayList, rather than as a string (as with PROVIDER_URL).
TIBCO Enterprise Message Service .NET Reference
216 | Chapter 11 Name Server Lookup
URL_SEPARATOR string
Syntactic separator between URLs in the PROVIDER_URL.
Member Description
Method Description Page
LookupContext Constructor. 217
LookupContext.AddSettings Add or change the lookup context settings. 218
LookupContext.Lookup Lookup an object in the naming server. 219
LookupContext.RemoveSettings Remove a context setting. 220
TIBCO Enterprise Message Service .NET Reference
LookupContext | 217
LookupContextConstructor
Declaration LookupContext(Hashtable prop );
LookupContext();
Purpose Create a new lookup context object.
Remarks The first constructor sets properties of the new context object.
The second constructor creates a context without property settings.
Parameter Description
prop Set all the name-value pairs contained in this hash table.
TIBCO Enterprise Message Service .NET Reference
218 | Chapter 11 Name Server Lookup
LookupContext.AddSettingsMethod
Declaration virtual object AddSettings(string propName,object propValue );
virtual void AddSettings(Hashtable prop );
Purpose Add or change the lookup context settings.
Remarks The first method sets one property. If the property was previously set, the method modifies it and returns the old value.
The second method sets multiple properties defined in a hash table.
Parameter Description
propName Set this single property.
For property names, see Fields on page 215.
propValue Set the single property to this value.
prop Set all the name-value pairs contained in this hash table.
TIBCO Enterprise Message Service .NET Reference
LookupContext.Lookup | 219
LookupContext.LookupMethod
Declaration virtual object Lookup(string name );
Purpose Lookup an object in the naming server.
Remarks Returns the named object, if the server finds it.
If the server does not find the object, this method throws NamingException.
Example Hashtable env = new Hashtable();env.Add(LookupContext.PROVIDER_URL,
"tibjmsnaming://localhost:7222");env.Add(LookupContext.SECURITY_PRINCIPAL", "myUserName");env.Add(LookupContext.SECURITY_CREDENTIALS", "myPassword");try {
LookupContext searcher = new LookupContext(env);TIBCO.EMS.Queue queue =
(TIBCO.EMS.Queue)searcher.Lookup("theQueueName");...
} catch (NamingException) {...
}
Throws AuthenticationException on page 308NamingException on page 322ServiceUnavailableException on page 325
Parameter Description
name Lookup this name.
TIBCO Enterprise Message Service .NET Reference
220 | Chapter 11 Name Server Lookup
LookupContext.RemoveSettingsMethod
Declaration virtual object RemoveSettings(string propName );
Purpose Remove a context setting.
Parameter Description
propName Remove this property.
For property names, see Fields on page 215.
TIBCO Enterprise Message Service .NET Reference
LookupContextFactory | 221
LookupContextFactoryClass
Declaration class LookupContextFactory
Purpose Create ILookupContext objects.
Remarks To lookup administered objects in either a third-party LDAP naming server or the TIBCO EMS Naming server, clients create an instance of the LookupContextFactory and invoke the LookupContextFactory.CreateContext method to get an ILookupContext object.
Member Description
Fields
Programs use these constants as names of context settings (in argument hashtables or individually).
LDAP_CONTEXT string
Ldap context to lookup administered object in an ldap server.
TIBJMS_NAMING_CONTEXT string
tibjmsnaming context to lookup administered object inside the tibjmsnaming server.
Method Description Page
LookupContextFactory Create a lookup context factory. 222
LookupContextFactory.CreateContext Returns the initial context used to search for administered objects
222
TIBCO Enterprise Message Service .NET Reference
222 | Chapter 11 Name Server Lookup
LookupContextFactoryConstructor
Declaration LookupContextFactory();
Purpose Create a lookup context factory.
LookupContextFactory.CreateContextMethod
Declaration ILookupContext CreateContext(String name, Hashtable props);
Purpose Returns the initial context used to search for administered objects
Remarks This method returns an ILookupContext object that is the initial context used to look up administered object in the EMS server or an LDAP server. The currently supported contexts are tibjmsnaming and ldap.
Before calling CreateContext, first create a hash table of properties and their values.
Examples This example demonstrates how to create an initial context for looking up a queue object in the EMS naming 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(
Parameter Description
name Can be either:
• LookupContextFactory.TIBJMS_NAMING_CONTEXT to create an initial context in the EMS server.
• LookupContextFactory.LDAP_CONTEXT to create an initial context in an LDAP server.
props Hash table of properties.
TIBCO Enterprise Message Service .NET Reference
LookupContextFactory.CreateContext | 223
LookupContextFactory.TIBJMS_NAMING_CONTEXT,env);
TIBCO.EMS.Queue queue = (TIBCO.EMS.Queue)searcher.Lookup("theQueueName");
This example shows how to look up a connection factory, named testConnFact, in a third-party LDAP server located at the URL: 10.105.185.30:10389:
Hashtable env = new Hashtable();table.Add(LdapLookupConsts.LDAP_SERVER_URL,
"10.105.185.30:10389");table.Add(LdapLookupConsts.LDAP_BASE_DN,
"ou=People,dc=nmunjal1");table.Add(LdapLookupConsts.LDAP_PRINCIPAL, "cn=Manager");table.Add(LdapLookupConsts.LDAP_CREDENTIAL, "password");table.Add(LdapLookupConsts.LDAP_CONN_TYPE, "ldap");
LookupContextFactory contextFactory = new LookupContextFactory();ILookupContext searcher = contextFactory.CreateContext(
LookupContextFactory.LDAP_CONTEXT,env);
ConnectionFactory cf =(ConnectionFactory)searcher.Lookup("cn=testConnFact");
This example shows how to look up a connection factory object in the LDAP server via SSL.
Hashtable props = new Hashtable(); props.Add(LdapLookupConsts.LDAP_SERVER_URL",
"adc1.na.tibco.com:10636");props.Add(LdapLookupConsts.LDAP_BASE_DN",
"ou=People,dc=test-user");props.Add(LdapLookupConsts.LDAP_PRINCIPAL", "cn=Manager");props.Add(LdapLookupConsts.LDAP_CREDENTIAL", "password");props.Add(LdapLookupConsts.LDAP_SEARCH_SCOPE, "subtree");props.Add(LdapLookupConsts.LDAP_CONN_TYPE, "ldaps");props.Add(LdapLookupConsts.LDAP_CERT_NAME, "certName");props.Add(LdapLookupConsts.LDAP_CERT_STORE_NAME, "My");props.Add(LdapLookupConsts.LDAP_CERT_STORE_LOCATION,
"currentuser");
LdapLookupSSLParams sslparams = new LdapLookupSSLParams();sslparams.SetSSLQueryClientCertificateCallback(
QueryClientCertificateCallback);sslparams.SetSSLVerifyServerCertificateCallback(
VerifyServerCertificateCallback);props.Add(LdapLookupConsts.LDAP_SSL_PARAMS, sslparams);
LookupContextFactory contextFactory = new LookupContextFactory();ILookupContext searcher = contextFactory.CreateContext(
LookupContextFactory.LDAP_CONTEXT,props);
ConnectionFactory cf = searcher.Lookup("cn=testConnFact");Console.WriteLine("cf = " + cf.ToString());
TIBCO Enterprise Message Service .NET Reference
224 | Chapter 11 Name Server Lookup
LdapLookupConstsClass
Declaration abstract class LdapLookupConsts
Purpose Specifies the parameters used to connect to a third-party LDAP server and lookup EMS administered objects.
Remarks The LDAP Lookup Constants are mainly to specify parameters to connect to an LDAP server and specify search scope with the LDAP server for looking up EMS administered objects.
See LookupContext on page 215 for the parameters used looking up administered objects in the EMS server.
Member Description
LDAP_BASE_DN Specifies the base DN, which is where to start looking for the administered objects.
LDAP_CERT_NAME Specifies the certificate name. This is required property when the LDAP_CONN_TYPE of ldaps is used and LDAP_SSL_PARAMS is not specified with a LdapLookupSSLParams.SetSSLQueryClientCertificateCal
lback method.
LDAP_CERT_STORE_LOCATION Specifies the store location, acceptable values are "currentuser" (the default) and "localmachine."
LDAP_CERT_STORE_NAME Specifies the store name. The default is "My" (i.e personal) store at the "currentuser" location.
LDAP_CONN_TYPE Specifies the connection type. The acceptable values are "ldap" (the default) and "ldaps".
LDAP_CREDENTIAL Specifies the credential (i.e the password) to use while connecting to the LDAP server.
LDAP_PRINCIPAL Specifies the principal (for example, the user name) to use while connecting to the ldap server.
LDAP_SEARCH_SCOPE Specifies the search scope. The acceptable values are "subtree" (the default) and "onelevel."
LDAP_SERVER_URL Specifies the url for the connection to the LDAP server.
TIBCO Enterprise Message Service .NET Reference
LdapLookupConsts | 225
LDAP_SSL_PARAMS Specifies the other ssl parameters, namely QueryClientCertificateCallback and VerifyServerCertificateCallback.
Member Description
TIBCO Enterprise Message Service .NET Reference
226 | Chapter 11 Name Server Lookup
LdapLookupContextClass
Declaration class LdapLookupContext
Purpose Interface used to search for and perform queries on EMS administered objects in a third-party LDAP server.
Member Description
Settings System.Collections.Hashtable Settings {get;}
Return a copy of the current settings.
Method Description Page
LdapLookupContext.AddSettings Add or change the lookup context settings. 227
LdapLookupContext.Lookup Lookup up an EMS administered object by name in an LDAP server.
228
LdapLookupContext.RemoveSettings Remove a setting by name. 228
TIBCO Enterprise Message Service .NET Reference
LdapLookupContext.AddSettings | 227
LdapLookupContext.AddSettings
Declaration object AddSettings(string propName,object propValue );
void AddSettings(Hashtable prop );
Purpose Add or change the lookup context settings.
Remarks The first method sets one property. If the property was previously set, the method modifies it and returns the old value.
The second method sets multiple properties defined in a hash table.
Parameter Description
propName Set this single property.
For property names, see LdapLookupConsts on page 224.
propValue Set the single property to this value.
prop Set all the name-value pairs contained in this hash table.
TIBCO Enterprise Message Service .NET Reference
228 | Chapter 11 Name Server Lookup
LdapLookupContext.Lookup
Declaration object Lookup(string name)
Purpose Lookup up an EMS administered object by name in an LDAP server.
Remarks This is an implementation of ILookupContext.Lookup. The administered objects can be either EMS connection factories, topics, queues stored in a third-party LDAP server.
When looking up administered SSL connection factory objects, because of differences in the .NET ssl implementation and java/c ssl implementation, certain parameters are ignored.
The following values are supported.
• Expected hostname is converted to targethostName
• SSL client identity (only pkcs12 file)
• SSL password for the private key in the pkcs12 file
• SSL trace
• SSL trusted
The following (not complete) is the list of values ignored when constructing the ssl connection factory object:
• ssl verify host
• ssl vendor
• ssl verify host name
Lookup of XA connection factories is not supported.
Parameter Description
name Lookup this name.
TIBCO Enterprise Message Service .NET Reference
LdapLookupContext.Lookup | 229
Example Example that shows how to create and LDAP lookup context object and lookup an object in an LDAP server.
Hashtable props = new Hashtable();props.Add(LdapLookupConsts.LDAP_SERVER_URL",
"ldap://adc1.na.tibco.com:10389");props.Add(LdapLookupConsts.LDAP_BASE_DN",
"ou=People,dc=users");props.Add(LdapLookupConsts.LDAP_PRINCIPAL", "cn=Manager');props.Add(LdapLookupConsts.LDAP_CREDENTIAL", "password");props.Add(LdapLookupConsts.LDAP_SEARCH_SCOPE, "subtree");props.Add(LdapLookupConsts.LDAP_CONN_TYPE", "ldaps");
LookupContextFactory lookupCtxFactory = new LookupContextFactory();
ILookupContext searcher = lookupCtxFactory.Create(LookupContextFactory.LDAP_CONTEXT, props);
TIBCO.EMS.Queue queue =(TIBCO.EMS.Queue)searcher.Lookup("theQueueName");
Throws NullReferenceException if the name is null.
ConfigurationException if any of the configuration parameters are missing.
NamingException for any other error while establishing a connection to the ldap server or during lookup.
TIBCO Enterprise Message Service .NET Reference
230 | Chapter 11 Name Server Lookup
LdapLookupContext.RemoveSettings
Declaration object RemoveSettings string propName);
Purpose Remove a setting by name.
Remarks Implements ILookupContext.RemoveSettings
Throws ArgumentException if the property name is null.
Parameter Description
propName Remove this property.
For property names, see LdapLookupConsts on page 224.
TIBCO Enterprise Message Service .NET Reference
LdapLookupSSLParams | 231
LdapLookupSSLParamsClass
Declaration class LdapLookupSSLParams
Purpose Provides the query client certificate callback and the server verify callback used to establish an SSL connection to the LDAP server (ldaps).
Remarks The parameters set by this object are optional. The client may choose to either specify the store location along with the store name and certificate name, or optionally the query client certificate callback.
LdapLookupSSLParamsConstructor
Declaration LdapLookupSSLParams();
Purpose Create a LDAP lookup SSL Parameters object.
Method Description Page
LdapLookupSSLParams Create a LDAP lookup SSL Parameters object. 231
LdapLookupSSLParams.SetSSLQueryCl
ientCertificateCallback
Set the query client certificate callback to be invoked during the SSL handshake with the LDAP server.
232
LdapLookupSSLParams.SetSSLVerifyS
erverCertificateCallback
Set the server certificate verify callback to be invoked during the SSL handshake with the ldap server.
232
TIBCO Enterprise Message Service .NET Reference
232 | Chapter 11 Name Server Lookup
LdapLookupSSLParams.SetSSLQueryClientCertificateCallback
Declaration public void SetSSLQueryClientCertificateCallback(QueryClientCertificateCallback callback);
Purpose Set the query client certificate callback to be invoked during the SSL handshake with the LDAP server.
Remarks A query client certificate callback that gets invoked during the ssl handshake with the ldap server, allowing the user to specify a client certificate to be used for ssl handshake.
LdapLookupSSLParams.SetSSLVerifyServerCertificateCallback
Declaration public void SetSSLVerifyServerCertificateCallback(VerifyServerCertificateCallback callback);
Purpose Set the server certificate verify callback to be invoked during the SSL handshake with the ldap server.
Remarks A server certificate verify callback if set gets invoked during the ssl handshake with the ldap server. If this is not specified then the client will trust any server
Parameter Description
callback The query client certificate callback.
Parameter Description
callback The server certificate verify callback.
TIBCO Enterprise Message Service .NET Reference
| 233
TIBCO Enterprise Message Service .NET Reference
234 | Chapter 11 Name Server Lookup
TIBCO Enterprise Message Service .NET Reference
| 235
Chapter 12 SSL Support
This chapter presents classes and interfaces that support SSL.
Topics
• EMSSSL, page 236
• EMSSSLFileStoreInfo, page 246
• EMSSSLSystemStoreInfo, page 251
• EMSSSLHostNameVerifier, page 255
• EMSSSLHostNameVerifierArgs, page 256
• EMSSSLStoreType, page 257
TIBCO Enterprise Message Service .NET Reference
236 | Chapter 12 SSL Support
EMSSSLClass
Declaration class EMSSSL
Purpose Sets and gets the SSL parameters that apply across all connections.
Remarks Normally a client application obtains SSL setup as a part of the ConnectionFactory definition. A ConnectionFactory is usually obtained by the client applications via JNDI lookup calls. Alternatively, the client can use the EMSSSL class to define SSL parameters locally rather than from the ConnectionFactory. This may be necessary, for example, due to security considerations when JNDI lookup operation cannot be performed securely over SSL protocol. The EMSSSL class allows you to set SSL parameters globally so they apply to all the connections.
A EMS client communicates with the server via SSL protocol when the server URL provided to the ConnectionFactory is specified in the form ssl://host:port.
When the connection between the client and the server is an SSL connection, the server and the client application must set parameters in order for the SSL handshake to be successful. The server parameters are set by the administrator. Each client application is responsible for setting SSL parameters correctly in order to be able to establish an SSL connection to the server.
Setting up SSL parameters by the client can be done in one of three ways:
• All SSL parameters are specified in the ConnectionFactory, which either can be created dynamically by the client or obtained via a JNDI lookup call. Notice this does not address an issue of making JNDI lookup calls over SSL connection.
• SSL parameters are set globally via calls to this class. When a ConnectionFactory is using a URL specifying 'ssl' protocol but does not specify any other SSL parameters, the SSL parameters set via calls to the methods of this class will be used.
• A client application can create a Map of SSL parameters and pass it directly into constructor of TopicConnectionFactory or QueueConnectionFactory.
TIBCO Enterprise Message Service .NET Reference
EMSSSL | 237
SSL Parameters
A client has to choose the certificate store it is going to work with before setting the SSL parameters. EMS .NET client supports two different certificate stores and each store has a different API. See EMSSSLFileStoreInfo and EMSSSLSystemStoreInfo for more information on the certificate store specific APIs.
Cipher Suites
The .NET framework does not allow ciphers to be specified from the client side, so there is no provision of specifying the ciphers in the API.
General Setup
When an EMS .NET client establishes an SSL connection to the EMS server, it should at the very least specify the TARGET_HOST_NAME parameter, this is a required parameter for the SSLStream. A client then has to specify one of the certificate store types, EMSSSL_STORE_TYPE_FILE or EMSSSL_STORE_TYPE_SYSTEM, along with the Store info object containing all the required information:
• In case of the system store, the EMSSSLSystemStoreInfo object has information about the location of the store, the store name and the certificate name to look for in the store.
• In case of the file store, the EMSSSLFileStoreInfo object has information about the client identity, the password for the private key and any optional trusted certificates.
The client can set the host name verifier callback that will be called during the SSL handshake, the client can perform any specific validations in the host name verifier callback, returning false from this callback causes the SSL handshake to terminate, return true causes the SSL handshake to proceed.
If the client is interested in authentication only, then it can call EMSSSL.SetAuthOnly to enable. Normal behavior is to perform authentication before any data that is sent/received encrypted/decrypted. Setting auth only on both the client and server causes the client to use an SSL connection only to perform authentication and the switch over to a TCP connection for better performance at the expense of data security.
TIBCO Enterprise Message Service .NET Reference
238 | Chapter 12 SSL Support
For complete details, see the corresponding item in the book TIBCO Enterprise Message Service .NET Reference.
Member Description
AUTH_ONLY string AUTH_ONLY = "TIBCO.EMS.ssl.auth_only";
Name of SSL property specifying if SSL is used for authentication only. The value is a Boolean object. This name is defined as "TIBCO.EMS.ssl.auth_only".
CERT_NAME string CERT_NAME = "TIBCO.EMS.ssl.cert_name";
Name of the certificate
CLIENT_TRACER string CLIENT_TRACER = "TIBCO.EMS.ssl.client_tracer";
Name of SSL property specifying the client tracer object The is a valid tracer object This name is defined as "TIBCO.EMS.ssl.client_trace".
ENCODING_AUTO int ENCODING_AUTO = 0;
Integer defining AUTO format of the certificate or private key data.
ENCODING_DER int ENCODING_DER = 2;
Integer defining DER format of the certificate or private key data.
ENCODING_PEM int ENCODING_PEM = 1;
Integer defining PEM format of the certificate or private key data.
ENCODING_PFX int ENCODING_PFX = 256;
Integer defining Pfx format of the client identity data.
ENCODING_PKCS12 int ENCODING_PKCS12 = 64;
Integer defining PKCS12 format of the client identity data.
ENCODING_PKCS7 int ENCODING_PKCS7 = 16;
Integer defining PKCS7 format.
ENCODING_PKCS8 int ENCODING_PKCS8 = 32;
Integer defining PKCS8 format of the private key data.
TIBCO Enterprise Message Service .NET Reference
EMSSSL | 239
HOST_NAME_VERIFIER string HOST_NAME_VERIFIER = "TIBCO.EMS.ssl.hostname_verifier";
Name of SSL property specifying the custom host name verifier. Notice when this property is specified, the Map of parameters can not be stored in JNDI. The value is a EMSSSLHostNameVerifier object. This name is defined as "TIBCO.EMS.ssl.hostname_verifier".
IDENTITY string IDENTITY = "TIBCO.EMS.ssl.identity";
Name of SSL property specifying the client-side identity. An identity usually consists of the certificate, corresponding private key and optionally a set of issuer certificates. The value specified by this property can be a certificate, a PKCS12 file, a KeyStore object or an Entrust Store. Last three object types normally include all elements of the identity into a single storage. In this case only PASSWORD property should be specified as the password required to decrypt the content of the specified identity data. If this property specifies the certificate file then PRIVATE_KEY must be also set and optionally ISSUER_CERTIFICATES. This name is defined as "TIBCO.EMS.ssl.identity".
PASSWORD string PASSWORD = "TIBCO.EMS.ssl.password";
Name of SSL property specifying the password for the private key or the identity store. The value is a java.lang.String object or char[]. This name is defined as "TIBCO.EMS.ssl.password".
STORE_INFO string STORE_INFO = "TIBCO.EMS.ssl.store_info";
SSL Store Info
STORE_TYPE string STORE_TYPE = "TIBCO.EMS.ssl.store_type";
SSL Store type
TARGET_HOST_NAME string TARGET_HOST_NAME = "TIBCO.EMS.ssl.target_host_name";
TRACE
Member Description
TIBCO Enterprise Message Service .NET Reference
240 | Chapter 12 SSL Support
TRUSTED_CERTIFICATES string TRUSTED_CERTIFICATES = "TIBCO.EMS.ssl.trusted_certs";
Name of SSL property specifying the set of trusted certificates. The value is a Vector object, elements of the Vector can be: - certificate object, - an Integer object specifying the certificate type followed by the certificate object. An Integer object before the object presenting the certificate data may be required when certificate data does not allow automatic detection of the encoding format. This name is defined as "TIBCO.EMS.ssl.trusted_certs".
Member Description
Method Description Page
EMSSSL.GetAuthOnly Get the value of the AUTH_ONLY flag. 241
EMSSSL.GetClientTracer Returns the output target for the client tracer, or null if client tracing is disabled.
241
EMSSSL.GetHostNameVerifier Returns currently set custom host name verifier. 241
EMSSSL.GetTargetHostName Returns the name set target host name. 241
EMSSSL.Initialize Initializes SSL environment. 242
EMSSSL.SetAuthOnly Enable or disable AUTH_ONLY on the client side.
242
EMSSSL.SetCertificateStoreType Set the store type for all the connection factories. 243
EMSSSL.SetClientTracer Set client tracer to given output stream. 244
EMSSSL.SetHostNameVerifier Set the custom host name verifier. 244
EMSSSL.SetTargetHostName Set the target host name. 245
TIBCO Enterprise Message Service .NET Reference
EMSSSL.GetAuthOnly | 241
EMSSSL.GetAuthOnlyMethod
Declaration static bool GetAuthOnly();
Purpose Get the value of the AUTH_ONLY flag.
Remarks Returns true for enabled and false for disabled.
See Also EMSSSL.SetAuthOnly on page 242
EMSSSL.GetClientTracerMethod
Declaration static StreamWriter GetClientTracer();
Purpose Returns the output target for the client tracer, or null if client tracing is disabled.
EMSSSL.GetHostNameVerifierMethod
Declaration static EMSSSLHostNameVerifier GetHostNameVerifier();
Purpose Returns currently set custom host name verifier.
Remarks Returns null if custom host name verifier is not set.
EMSSSL.GetTargetHostNameMethod
Declaration static string GetTargetHostName();
Purpose Returns the name set target host name.
TIBCO Enterprise Message Service .NET Reference
242 | Chapter 12 SSL Support
EMSSSL.InitializeMethod
Declaration static void Initialize();
Purpose Initializes SSL environment.
Remarks Normally SSL environment is initialized automatically when creating the first SSL connection. If SSL environment has been already initialized this method does nothing.
EMSSSL.SetAuthOnlyMethod
Declaration static void SetAuthOnly(bool flag);
Purpose Enable or disable AUTH_ONLY on the client side.
Remarks For the client and server to require an SSL connection only to perform authentication, the ssl_auth_only parameter needs to be set on the server and AUTH_ONLY needs to be set by the client. Setting these flags on both the server and client side indicates that the SSL connection is only used to only perform authentication. Once authentication is complete, the client switches to a regular TCP connection to communicate with the server.
See the SSL Authentication Only section in the TIBCO Enterprise Message Service User’s Guide for details.
See Also EMSSSL.GetAuthOnly on page 241ConnectionFactory.SetSSLAuthOnly on page 156
Parameter Description
flag True = enabled.
False = disabled.
TIBCO Enterprise Message Service .NET Reference
EMSSSL.SetCertificateStoreType | 243
EMSSSL.SetCertificateStoreTypeMethod
Declaration static void SetCertificateStoreType(EMSSSLStoreType type,object storeInfo
);
Purpose Set the store type for all the connection factories.
Parameter Description
type The type of certificate store. Can be either EMSSSL_STORE_TYPE_SYSTEM or EMSSSL_STORE_TYPE_FILE. See EMSSSLStoreType on page 257 for details.
storeInfo If the store type is EMSSSL_STORE_TYPE_SYSTEM, then storeInfo must be an EMSSSLSystemStoreInfo object. If the store type is EMSSSL_STORE_TYPE_FILE, then storeInfo must be an EMSSSLFileStoreInfo object.
TIBCO Enterprise Message Service .NET Reference
244 | Chapter 12 SSL Support
EMSSSL.SetClientTracerMethod
Declaration static void SetClientTracer(StreamWriter tracer);
Purpose Set client tracer to given output stream.
.Remarks Client tracing prints loaded certificates and information about the SSL handshake errors and results.
EMSSSL.SetHostNameVerifierMethod
Declaration static void SetHostNameVerifier(EMSSSLHostNameVerifier verifier);
Purpose Set the custom host name verifier.
Parameter Description
tracer The output stream to send the tracing information. Specify null as parameter to disable client tracing.
Parameter Description
verifier Host name verifier. Set to null to remove custom host name verifier.
See EMSSSLHostNameVerifier on page 255 for details.
TIBCO Enterprise Message Service .NET Reference
EMSSSL.SetTargetHostName | 245
EMSSSL.SetTargetHostNameMethod
Declaration static void SetTargetHostName(string hostname);
Purpose Set the target host name.
Remarks This is a required parameter for all .NET SSL connections. Because System.Net.Security.SslStream requires a target host, this value is required.
Parameter Description
targetHostName The name of the server as defined in the server's certificate. Usually the server's HostName is specified as the CN in the server's certificate.
TIBCO Enterprise Message Service .NET Reference
246 | Chapter 12 SSL Support
EMSSSLFileStoreInfoClass
Declaration class EMSSSLFileStoreInfo;
Purpose Specifies the file store information
Remarks The File Store Info object sets the store for a connection factory via the ConnectionFactory.SetCertificateStoreType method or while using the global EMSSSL API to set the certificate store. The store info consists of the client's identity (the only type supported is the pkcs12 file aka .pfx file format), the SSL password for the private key stored in the pkcs12 file and any optional trusted certificates.
Requirements Namespace: TIBCO.EMSAssembly: TIBCO.EMS (in TIBCO.EMS.dll)
Method Description Page
EMSSSLFileStoreInfo Create a new File Store Info object.
247
EMSSSLFileStoreInfo.ClearTrustedCerts Remove all previously set trusted certificates.
247
EMSSSLFileStoreInfo.SetSSLClientIdentity Set the client identity. 248
EMSSSLFileStoreInfo.SetSSLPassword Set private key password. 249
EMSSSLFileStoreInfo.SetSSLTrustedCertificate Add a certificate to the list of trusted certificates.
250
TIBCO Enterprise Message Service .NET Reference
EMSSSLFileStoreInfo | 247
EMSSSLFileStoreInfoConstructor
Declaration EMSSSLFileStoreInfo();
Purpose Create a new File Store Info object
EMSSSLFileStoreInfo.ClearTrustedCertsMethod
Declaration void ClearTrustedCerts();
Purpose Remove all previously set trusted certificates.
TIBCO Enterprise Message Service .NET Reference
248 | Chapter 12 SSL Support
EMSSSLFileStoreInfo.SetSSLClientIdentityMethod
Declaration void SetSSLClientIdentity(X509Certificate certificate);
void SetSSLClientIdentity(string clientIdentity);
Purpose Set the client identity.
Remarks Overloaded. The only file type that is supported here is a pkcs12 or .pfx file. NOTE: If other file format are specified then a configuration exception will be thrown during the SSL handshake.
To set the Client Identity as a string:
public void SetSSLClientIdentity(clientId);
To set Client Identity as a X509 Certificate, use:
void SetSSLClientIdentity(X509Certificate);
Parameter Description
certificate A pkcs12 or .pfx file used to identify the client.
clientIdentity The X509 Certificate used to identify the client.
TIBCO Enterprise Message Service .NET Reference
EMSSSLFileStoreInfo.SetSSLPassword | 249
EMSSSLFileStoreInfo.SetSSLPasswordMethod
Declaration void SetSSLPassword(char[] password);
Purpose Set private key password.
Parameter Description
password The SSL Password.
TIBCO Enterprise Message Service .NET Reference
250 | Chapter 12 SSL Support
EMSSSLFileStoreInfo.SetSSLTrustedCertificateMethod
Declaration void SetSSLTrustedCertificate(X509Certificate certificate);
void SetSSLTrustedCertificate(string certificate);
Purpose Add a certificate to the list of trusted certificates.
Remarks Only ASN1.DER encoded files are supported.
Parameter Description
certificate The name of the certificate to add to the list of trusted certificates.
TIBCO Enterprise Message Service .NET Reference
EMSSSLSystemStoreInfo | 251
EMSSSLSystemStoreInfoClass
Declaration class EMSSSLSystemStoreInfo
Purpose Specifies the system store information.
Remarks The System Store Info object sets the store for a connection factory via the ConnectionFactory.SetCertificateStoreType method or while using the global EMSSSL API to set the certificate store. The store info consists of the store location, store name, the certificate name (to look for in the specified store name at the specified store location).
The default store location is StoreLocation.CurrentUser and the default store name is 'my' store as defined by the .NET framework. The search criteria to find the certificate in the store name at the store location is X509FindType.FindBySubjectDistinguishedName.
Method Description Page
EMSSSLSystemStoreInfo Creates an object of type system store info.
252
EMSSSLSystemStoreInfo.SetCertificateName Set the name of the certificate.
253
EMSSSLSystemStoreInfo.SetCertificateStoreLocation Set location of the certificate store.
254
EMSSSLSystemStoreInfo.SetCertificateStoreName Set the certificate store name. 254
TIBCO Enterprise Message Service .NET Reference
252 | Chapter 12 SSL Support
EMSSSLSystemStoreInfoConstructor
Declaration EMSSSLSystemStoreInfo();
Purpose Creates an object of type system store info.
Remarks This object is used mainly to specify system store information when the store type of SYSTEM is used by the ConnectionFactory.SetCertificateStoreType method.
See Also ConnectionFactory.SetCertificateStoreType on page 144
TIBCO Enterprise Message Service .NET Reference
EMSSSLSystemStoreInfo.SetCertificateName | 253
EMSSSLSystemStoreInfo.SetCertificateNameMethod
Declaration void SetCertificateName(string certName);
Purpose Set the name of the certificate.
Remarks This method sets the name of the certificate. The certificate name is the subject distinguished name of the certificate. During the SSL handshake, the server searches for the named certificate in the store specified by EMSSSLSystemStoreInfo.SetCertificateStoreName at the location specified by EMSSSLSystemStoreInfo.SetCertificateStoreLocation.
Throws ArgumentException if the certificate name is null.
See Also EMSSSLSystemStoreInfo.SetCertificateStoreName on page 254 EMSSSLSystemStoreInfo.SetCertificateStoreLocation on page 254
While searching for the certificate in the certificate store the tag 'CN' is automatically prepended to the certificate name.
Parameter Description
certName Certificate name.
TIBCO Enterprise Message Service .NET Reference
254 | Chapter 12 SSL Support
EMSSSLSystemStoreInfo.SetCertificateStoreLocationMethod
Declaration void SetCertificateStoreLocation(StoreLocation storeLocation);
Purpose Set location of the certificate store.
Remarks The certificate store location indicates where to lookup the certificate by name. If no store name is specified, then the default store name is "My" store name within this store location.
EMSSSLSystemStoreInfo.SetCertificateStoreNameMethod
Declaration void SetCertificateStoreName(string storeName);
Purpose Set the certificate store name.
Remarks This is the name of the store in which certificates are stored. During the SSL handshake, this is where the client library looks for the certificates.
Throws ArgumentException if the store name is null.
Parameter Description
storeLocation Location in which to lookup certificate by name. For example, "CurrentUser" or "LocalMachine."
Parameter Description
storeName Name of the certificate store.
TIBCO Enterprise Message Service .NET Reference
EMSSSLHostNameVerifier | 255
EMSSSLHostNameVerifierDelegate
Declaration delegate bool EMSSSLHostNameVerifier(object sender,EMSSSLHostNameVerifierArgs args
);
Purpose Delegate declaration for host name verifier.
Remarks The user can perform any necessary specific validations in the host name verifier delegate, returning false will cause the SSL handshake to terminate, returning true will cause the SSL handshake to continue.
Requirements Namespace: TIBCO.EMSAssembly: TIBCO.EMS (in TIBCO.EMS.dll)
Parameter Description
sender The source of the event.
args The event argument, EMSSSLHostNameVerifierArgs.
TIBCO Enterprise Message Service .NET Reference
256 | Chapter 12 SSL Support
EMSSSLHostNameVerifierArgsClass
Declaration class EMSSSLHostNameVerifierArgs : EventArgs
Purpose Specifies the host name verifier arguments.
Remarks The user is handed off an EMSSSLHostNameVerifierArgs object as part of the host name verifier event callback, LdapLookupSSLParams.SetSSLVerifyServerCertificateCallback.
Member Description
m_certificateCommonName string m_certificateCommonName;
The certificate CN name should be same as the target host name.
m_connectedHostName string m_connectedHostName;
The host name to which the client is connected.
m_targetHostName string m_targetHostName;
The target host name, which is the server certificate CN name.
m_serverCertificate X509Certificate m_serverCertificate;
The server's certificate.
m_x509Chain X509Chain m_x509Chain;
The server certificate's chain.
TIBCO Enterprise Message Service .NET Reference
EMSSSLStoreType | 257
EMSSSLStoreTypeEnumeration
Declaration enum EMSSSLStoreType;
Purpose Certificate Store Type to be used for reading SSL Certificates.
Requirements Namespace: TIBCO.EMSAssembly: TIBCO.EMS (in TIBCO.EMS.dll)
Member Description
EMSSSL_STORE_TYPE_FILE Public const to be used if the certificates are stored in a pkcs12 (aka .pfx) file.
EMSSSL_STORE_TYPE_SYSTEM Public const to be used if the certificates are stored in the Microsoft certificate store.
EMSSSL_STORE_TYPE_DEFAULT Public const to be used if the certificates are stored in the Microsoft certificate store. Specifying default will cause the Microsoft certificate store to be used.
TIBCO Enterprise Message Service .NET Reference
258 | Chapter 12 SSL Support
TIBCO Enterprise Message Service .NET Reference
| 259
Chapter 13 Utilities
This chapter presents classes and interfaces that define constants and utility methods.
Topics
• DeliveryMode, page 260
• IEMSSerialziable, page 261
• MessageDeliveryMode, page 264
• Tibems, page 265
TIBCO Enterprise Message Service .NET Reference
260 | Chapter 13 Utilities
DeliveryModeClass
Declaration class DeliveryMode
Purpose Backward compatibility. Define delivery mode constants as integers.
Remarks The class MessageDeliveryMode defines a parallel set of constants as .NET enumerated values (instead of ordinary integers). We recommend the enumeration over these ordinary integer values, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.
Member Description
Fields
NON_PERSISTENT int
Non-persistent delivery.
PERSISTENT int
Persistent delivery.
RELIABLE_DELIVERY int
Reliable delivery mode is a TIBCO proprietary extension that offers increased performance of the message producers. See also RELIABLE_DELIVERY in TIBCO Enterprise Message Service User’s Guide.
TIBCO Enterprise Message Service .NET Reference
IEMSSerialziable | 261
IEMSSerialziableInterface
Declaration interface IEMSSerialzable
Purpose Customize serialization and deserialization of objects.
.NET CompactFramework
This interface is available only in .NET Compact Framework. Programmers can use it to allow otherwise excluded objects within an ObjectMessage.
Remarks When an object class implements this interface, it can be serialized within an ObjectMessage.
To implement this interface for a class, define the methods listed below and a constructor that does not require any arguments.
See Also ObjectMessage on page 48
Method Description Page
IEMSSerialziable.Deserialize Deserialize a data stream to reconstruct an object. 262
IEMSSerialziable.Serialize Serialize an object. 263
TIBCO Enterprise Message Service .NET Reference
262 | Chapter 13 Utilities
IEMSSerialziable.DeserializeMethod
Declaration void Deserialize(System.IO.Stream stream );
Purpose Deserialize a data stream to reconstruct an object.
Remarks When this method is called, the stream already contains context information. That context information resides before the write position of the stream when this method is called (call it initWritePos). Your implementation of this method must not modify that context information, nor reset the stream’s write pointer to a position before initWritePos.
Similarly, your implementation must not close the stream.
Parameter Description
stream Deserialize the data from this stream to reconstruct an object.
TIBCO Enterprise Message Service .NET Reference
IEMSSerialziable.Serialize | 263
IEMSSerialziable.SerializeMethod
Declaration void Serialize(System.IO.Stream stream );
Purpose Serialize an object.
Remarks When this method is called, the stream already contains context information. That context information resides before the write position of the stream when this method is called (call it initWritePos). Your implementation of this method must not modify that context information, nor reset the stream’s write pointer to a position before initWritePos.
Similarly, your implementation must not close the stream.
Parameter Description
stream Serialize the object’s data to this stream.
TIBCO Enterprise Message Service .NET Reference
264 | Chapter 13 Utilities
MessageDeliveryModeEnumeration
Declaration enum MessageDeliveryMode
Purpose Define enumerated delivery mode constants.
Remarks The class DeliveryMode defines a parallel set of constants as ordinary integers. However, we recommend this enumeration, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.
Member Description
NonPersistent Non-persistent delivery.
Persistent Persistent delivery.
ReliableDelivery Reliable delivery mode is a TIBCO proprietary extension that offers increased performance of the message producers. See also RELIABLE_DELIVERY on page 26 in TIBCO Enterprise Message Service User’s Guide.
TIBCO Enterprise Message Service .NET Reference
Tibems | 265
TibemsClass
Declaration class Tibems
Purpose Define constants and utility methods specific to EMS.
Constant Description
Connection-Related Fields (Constants)
Programs can use these constants as names of settings in the hash table argument to ConnectionFactory.CreateConnection. They govern the behavior of the resulting connections that the factory creates.
DEFAULT_FACTORY_PASSWORD string
Defines the name of a ConnectionFactory property. That property specifies a default user password for the connections that the factory creates.
If the client does not supply a password, the connection factory object uses this password as a default when creating a connection. See also ConnectionFactory.CreateConnection on page 142.
DEFAULT_FACTORY_USERNAME string
Defines the name of a ConnectionFactory property. That property specifies a default username for the connections that the factory creates.
If the client does not supply a username, the connection factory object uses this username as a default when creating a connection. See also ConnectionFactory.CreateConnection on page 142.
FACTORY_LOAD_BALANCE_METRIC string
This field defines the name of a provider-specific ConnectionFactory property. That property governs the assignment of client connections among a set of load-balanced servers.
For property values, see QueueConnectionFactory on page 161.
TIBCO Enterprise Message Service .NET Reference
266 | Chapter 13 Utilities
Message-Related Fields (Constants)
Programs can use these constants as names of message properties.
JMS_TIBCO_CM_PUBLISHER string
Defines the name of a provider-specific message property. An imported message with that property is an RVCM message. The value of that property is the RVCM sender name. See also JMS_TIBCO_CM_PUBLISHER on page 15.
JMS_TIBCO_CM_SEQUENCE string
Defines the name of a provider-specific message property. An imported message with that property is an RVCM message. The value of that property is the RVCM sequence number. See also JMS_TIBCO_CM_SEQUENCE on page 15.
JMS_TIBCO_COMPRESS string
Defines the name of a provider-specific message property. EMS .NET does not support compression. See also JMS_TIBCO_COMPRESS on page 15.
JMS_TIBCO_DISABLE_SENDER string
Defines the name of a provider-specific message property. Programs may set that property before sending a message to request that the server omit the sender name from the message. See also JMS_TIBCO_DISABLE_SENDER on page 15.
JMS_TIBCO_IMPORTED string
Defines the name of a provider-specific message property. The server sets that property on messages it imports from external message services, such as TIBCO Rendezvous or TIBCO SmartSockets. See also JMS_TIBCO_IMPORTED on page 16.
JMS_TIBCO_MSG_EXT string
Defines the name of a provider-specific message property. When that property is set, the message can use TIBCO-specific extensions. See also JMS_TIBCO_MSG_EXT on page 16.
Constant Description
TIBCO Enterprise Message Service .NET Reference
Tibems | 267
JMS_TIBCO_MSG_TRACE string
Defines the name of a provider-specific message property. Programs may set that property before sending a message to request trace data at significant events during the lifetime of the message. See also JMS_TIBCO_MSG_TRACE on page 16.
JMS_TIBCO_PRESERVE_UNDELIVERED string
Defines the name of a provider-specific message property. Programs may set that property before sending a message to request that the server hold it in a special queue if the server cannot deliver it. See also JMS_TIBCO_PRESERVE_UNDELIVERED on page 16.
JMS_TIBCO_SENDER string
Defines the name of a provider-specific message property. When a destination requests it, the server stores the username of the message producer in that property. See also JMS_TIBCO_SENDER on page 16.
JMS_TIBCO_SS_SENDER string
Defines the name of a provider-specific message property. The server sets that property when importing a message from TIBCO SmartSockets; its value is the SmartSockets sender name. See also JMS_TIBCO_SS_SENDER on page 16.
Constant Description
Method Description Page
Tibems.CalculateMessageSize Returns the total size (in bytes) of a message in wire format.
270
Tibems.CreateFromBytes Create a message from a byte array. 271
Tibems.GetAllowCloseInCallback Determine whether client callbacks may call close methods.
272
Tibems.GetAsBytes Copy a message into a byte array. 273
TIBCO Enterprise Message Service .NET Reference
268 | Chapter 13 Utilities
Tibems.GetConnectAttempts Return the connection attempts setting. 274
Tibems.GetConnectAttemptTimeout Returns the connect attempt timeout value. 275
Tibems.GetConnectionActiveURL Return the URL of the EMS server for the specified connection.
276
Tibems.GetEncoding Return the global character encoding for messages.
277
Tibems.GetExceptionOnFTSwitch Return the fault tolerance exception setting. 278
Tibems.GetMessageEncoding Return the character encoding for an individual message.
279
Tibems.GetMessageSize
(and related methods)Return the size of a wire format message—or its body, header or properties portions.
280
Tibems.GetPingInterval Return the interval at which the client tests network connectivity.
281
Tibems.GetProperty Return a property value. 282
Tibems.GetReconnectAttempts Return the reconnection attempts setting. 284
Tibems.GetReconnectAttemptTimeout Returns the reconnect attempt timeout value. 285
Tibems.GetSessionDispatcherDaemon Return the dispatcher thread setting. 286
Tibems.GetSocketReceiveBufferSize Return the size of socket receive buffers. 287
Tibems.GetSocketSendBufferSize Return the size of socket send buffers. 288
Tibems.MakeWriteable Make a message writable. 289
Tibems.SetAllowCloseInCallback Override a JMS requirement so client callbacks may call close methods.
290
Tibems.SetConnectAttempts Modify the connection attempts setting. 291
Tibems.SetConnectAttemptTimeout Set the maximum amount of time a client will wait for the connection to be established.
292
Tibems.SetEncoding Set the global string encoding for messages. 293
Method Description Page
TIBCO Enterprise Message Service .NET Reference
Tibems | 269
Tibems.SetExceptionOnFTSwitch Modify the fault tolerance exception setting. 294
Tibems.SetMessageEncoding Set the character encoding for an individual message.
295
Tibems.SetPingInterval Set the interval at which the client tests network connectivity.
296
Tibems.SetProperty Modify a property value. 297
Tibems.SetReconnectAttempts Modify the reconnection attempts setting. 299
Tibems.SetReconnectAttemptTimeout Sets the maximum amount of time a client will wait for the reconnect to complete.
300
Tibems.SetSessionDispatcherDaemon Set the dispatcher thread setting. 301
Tibems.SetSocketReceiveBufferSize Set the size of socket receive buffers. 302
Tibems.SetSocketSendBufferSize Set the size of socket send buffers. 303
Method Description Page
TIBCO Enterprise Message Service .NET Reference
270 | Chapter 13 Utilities
Tibems.CalculateMessageSizeMethod
Declaration static int CalculateMessageSize(Message msg );
Purpose Returns the total size (in bytes) of a message in wire format.
Remarks The total size includes headers, properties and body.
This method re-measures the message, and caches the results; contrast Tibems.GetMessageSize.
This method might consume process storage, and might involve disk I/O—with associated performance penalties.
See Also Tibems.GetMessageSize on page 280
Parameter Description
msg Compute the size of this message.
TIBCO Enterprise Message Service .NET Reference
Tibems.CreateFromBytes | 271
Tibems.CreateFromBytesMethod
Declaration static Message CreateFromBytes(byte[] bytes );
Purpose Create a message from a byte array.
Remarks The newly created message is read-only; to enable modification without erasing the content, call Tibems.MakeWriteable.
See Also Tibems.GetAsBytes on page 273Tibems.MakeWriteable on page 289
Parameter Description
bytes Fill the new message with this byte array.
This byte array must be the result of previously calling Tibems.GetAsBytes.
TIBCO Enterprise Message Service .NET Reference
272 | Chapter 13 Utilities
Tibems.GetAllowCloseInCallbackMethod
Declaration static bool GetAllowCloseInCallback();
Purpose Determine whether client callbacks may call close methods.
Remarks According to the JMS specification, close methods (that is, MessageConsumer.Close, Session.Close, Connection.Close) cannot return while any message callbacks (that is, EMSMessageHandler, IMessageListener.OnMessage) are running. As a result, a message callback must not call a close method, lest it cause a deadlock.
Tibems.SetAllowCloseInCallback explicitly overrides this JMS requirement, permitting callbacks to call close without deadlock (that is, embedded close calls do not wait for callbacks to return).
See Also Tibems.SetAllowCloseInCallback on page 290
This method replaces the deprecated method GetAllowCallbackInClose.
TIBCO Enterprise Message Service .NET Reference
Tibems.GetAsBytes | 273
Tibems.GetAsBytesMethod
Declaration static byte[] GetAsBytes(Message message );
Purpose Copy a message into a byte array.
Remarks The byte array includes the message headers, properties and body.
See Also Tibems.CreateFromBytes on page 271
Parameter Description
message Fill the byte array with the content of this message.
TIBCO Enterprise Message Service .NET Reference
274 | Chapter 13 Utilities
Tibems.GetConnectAttemptsMethod
Declaration static string GetConnectAttempts();
Purpose Return the connection attempts setting.
Remarks This setting governs all client Connection objects as they attempt to connect to the server. Its value is a string of the form attempts or attempts,delay:
• attempts limits the number of times that the connection object attempts to establish a connection to the server. When this property is absent, the default value is 2. The minimum value is 1.
• delay is the time (in milliseconds) between connection attempts. When absent, the default value is 500. The minimum value is 250.
This method returns the string argument to Tibems.SetConnectAttempts—not the numeric value of the setting. If the client has not set a value, this method returns the null string.
See Also Tibems.SetConnectAttempts on page 291
TIBCO Enterprise Message Service .NET Reference
Tibems.GetConnectAttemptTimeout | 275
Tibems.GetConnectAttemptTimeoutMethod
Declaration static int GetConnectAttemptTimeout();
Purpose Returns the connect attempt timeout value.
See Also Tibems.SetConnectAttemptTimeout on page 292
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
TIBCO Enterprise Message Service .NET Reference
276 | Chapter 13 Utilities
Tibems.GetConnectionActiveURLMethod
Declaration static String GetConnectionActiveURL(Connection connection);
Purpose Return the URL of the EMS server for the specified connection.
Remarks The server URL is returned as a String.
Parameter Description
connection The connection to the EMS server.
TIBCO Enterprise Message Service .NET Reference
Tibems.GetEncoding | 277
Tibems.GetEncodingMethod
Declaration static string GetEncoding();
Purpose Return the global character encoding for messages.
Remarks If the global encoding has not been set, this method returns null.
Programs can override the global encoding for individual messages. When neither a global nor an individual message encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.
This encoding applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The methods BytesMessage.ReadUTF and BytesMessage.WriteUTF are exempt from global and individual encoding settings.
See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.SetEncoding on page 293Tibems.GetMessageEncoding on page 279Tibems.SetMessageEncoding on page 295
TIBCO Enterprise Message Service .NET Reference
278 | Chapter 13 Utilities
Tibems.GetExceptionOnFTSwitchMethod
Declaration static bool GetExceptionOnFTSwitch();
Purpose Return the fault tolerance exception setting.
Remarks This setting determines exception behavior when the client successfully switches to a different server (fault-tolerant failover).
• When true, the connection’s ExceptionListener catches an EMSException, which contains the name of the new server.
• When false, fault-tolerant failover does not trigger an exception in the client.
See Also IExceptionListener on page 133Tibems.SetExceptionOnFTSwitch on page 294
TIBCO Enterprise Message Service .NET Reference
Tibems.GetMessageEncoding | 279
Tibems.GetMessageEncodingMethod
Declaration static string GetMessageEncoding(Message message );
Purpose Return the character encoding for an individual message.
Remarks If the encoding has not been set for the individual message, this method returns null.
This encoding for an individual message overrides the global encoding. When neither a global nor an individual encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.
This encoding applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The methods BytesMessage.ReadUTF and BytesMessage.WriteUTF are exempt from global and individual encoding settings.
See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.GetEncoding on page 277Tibems.SetEncoding on page 293Tibems.SetMessageEncoding on page 295
Parameter Description
message Get the encoding for this message.
TIBCO Enterprise Message Service .NET Reference
280 | Chapter 13 Utilities
Tibems.GetMessageSizeMethod
Declaration static int GetMessageSize(Message msg );
static int GetMessageBodySize(Message msg );
static int GetMessageHeadersSize(Message msg );
static int GetMessagePropertiesSize(Message msg );
Purpose Return the size of a wire format message—or its body, header or properties portions.
Remarks These four methods return cached values for the size of a message or its parts.
The sizes are implicitly measured and cached when an inbound message arrives at the client, and when the client sends an outbound message. If the client modifies a message, or creates a message but never sends it, then these methods could yield incorrect cached values. To explicitly force a new measurement and cache its results, call Tibems.CalculateMessageSize; then these methods yield correct values.
GetMessageSize returns the total size of a message—that is, the number of bytes that traverse the network when the client sends the message. This total is slightly larger than the sum of its three constituent parts, because it includes additional control information. Furthermore, the server adds its own control information as well, so the size of message as measured by receivers is slightly larger than its size as measured by the sender.
See Also Tibems.CalculateMessageSize on page 270
Parameter Description
msg Return the cached size of this message, or one of its parts.
TIBCO Enterprise Message Service .NET Reference
Tibems.GetPingInterval | 281
Tibems.GetPingIntervalMethod
Declaration static int GetPingInterval();
Purpose Return the interval at which the client tests network connectivity.
Remarks Clients test network connectivity by sending ping requests to the server at regular intervals. This method returns that interval (in seconds). Zero is a special value that disables ping testing.
See Also Tibems.SetPingInterval on page 296
TIBCO Enterprise Message Service .NET Reference
282 | Chapter 13 Utilities
Tibems.GetPropertyMethod
Declaration static object GetProperty(string key );
Purpose Return a property value.
Remarks If the property is not set, this method returns null.
In .NET, methods exist to get and set the properties. GetProperty provides an alternate way to get property values, which is consistent with the EMS Java API (for easy porting to .NET).
Parameter Description
key Return the value associated with this property name.
You may supply any of the constants listed in the table below. The constants are defined as static fields of Tibems. The values of those constants are the actual property names.
Property Constant Corresponding Methods
PROP_SOCKET_RECEIVE_SIZE Tibems.GetSocketReceiveBufferSize on page 287
Tibems.SetSocketReceiveBufferSize on page 302
PROP_SOCKET_SEND_SIZE Tibems.GetSocketSendBufferSize on page 288
Tibems.SetSocketSendBufferSize on page 303
PROP_CONNECTION_ATTEMPTS Tibems.GetConnectAttempts on page 274
Tibems.SetConnectAttempts
PROP_RECONNECTION_ATTEMPTS Tibems.GetReconnectAttempts on page 284
Tibems.SetReconnectAttempts on page 299
PROP_CLOSE_IN_CALLBACK Tibems.GetAllowCloseInCallback on page 272
Tibems.SetAllowCloseInCallback on page 290
TIBCO Enterprise Message Service .NET Reference
Tibems.GetProperty | 283
See Also Tibems.SetProperty on page 297
PROP_PING_INTERVAL Tibems.GetPingInterval on page 281
Tibems.SetPingInterval on page 296
PROP_FT_SWITCH Tibems.GetExceptionOnFTSwitch on page 278
Tibems.SetExceptionOnFTSwitch on page 294
PROP_MESSAGE_ENCODING Tibems.GetMessageEncoding on page 279
Tibems.SetMessageEncoding on page 295
PROP_DAEMON_DISPATCHER Tibems.GetSessionDispatcherDaemon on page 286
Tibems.SetSessionDispatcherDaemon on page 301
Property Constant Corresponding Methods
TIBCO Enterprise Message Service .NET Reference
284 | Chapter 13 Utilities
Tibems.GetReconnectAttemptsMethod
Declaration static string GetReconnectAttempts();
Purpose Return the reconnection attempts setting.
Remarks This setting governs all client Connection objects as they attempt to reconnect to the server after a network disconnect. Its value is a string of the form attempts or attempts,delay:
• attempts limits the number of times that the connection object attempts to reestablish a connection to the server. When this property is absent, the default value is 4. The minimum value is 1.
• delay is the time (in milliseconds) between reconnection attempts. When absent, the default value is 500. The minimum value is 250.
This method returns the string argument to Tibems.SetReconnectAttempts—not the numeric value of the setting. If the client has not set a value, this method returns the null string.
See Also Tibems.SetReconnectAttempts on page 299
TIBCO Enterprise Message Service .NET Reference
Tibems.GetReconnectAttemptTimeout | 285
Tibems.GetReconnectAttemptTimeoutMethod
Declaration static int GetReconnectAttemptTimeout();
Purpose Returns the reconnect attempt timeout value.
See Also Tibems.SetReconnectAttemptTimeout on page 300
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
TIBCO Enterprise Message Service .NET Reference
286 | Chapter 13 Utilities
Tibems.GetSessionDispatcherDaemonMethod
Declaration static bool GetSessionDispatcherDaemon();
Purpose Return the dispatcher thread setting.
Remarks When a program uses asynchronous message consumers (either message listeners or .NET message event handler delegates), EMS creates internal dispatcher threads for each Session that has at least one asynchronous message consumer. When this setting is true, those dispatcher threads are daemon threads; when false (the default) they are not daemon threads.
.NET CompactFramework
The .NET Compact Framework does not support daemon threads. This call always returns false.
See Also Tibems.SetSessionDispatcherDaemon on page 301
TIBCO Enterprise Message Service .NET Reference
Tibems.GetSocketReceiveBufferSize | 287
Tibems.GetSocketReceiveBufferSizeMethod
Declaration static int GetSocketReceiveBufferSize();
Purpose Return the size of socket receive buffers.
Remarks When set, this value overrides the operating system’s default for the size of receive buffers associated with sockets that the client uses for connections to the server. (Some operating systems do not allow you to override the default size.)
See Also Tibems.SetSocketReceiveBufferSize on page 302
TIBCO Enterprise Message Service .NET Reference
288 | Chapter 13 Utilities
Tibems.GetSocketSendBufferSizeMethod
Declaration static int GetSocketSendBufferSize();
Purpose Return the size of socket send buffers.
Remarks When set, this value overrides the operating system’s default for the size of send buffers associated with sockets that the client uses for connections to the server. (Some operating systems do not allow you to override the default size.)
See Also Tibems.SetSocketSendBufferSize on page 303
TIBCO Enterprise Message Service .NET Reference
Tibems.MakeWriteable | 289
Tibems.MakeWriteableMethod
Declaration static void MakeWriteable(Message message);
Purpose Make a message writable.
See Also MessageNotWriteableException on page 320
Parameter Description
message Make this message writable.
TIBCO Enterprise Message Service .NET Reference
290 | Chapter 13 Utilities
Tibems.SetAllowCloseInCallbackMethod
Declaration static void SetAllowCloseInCallback(bool allow );
Purpose Override a JMS requirement so client callbacks may call close methods.
Remarks According to the JMS specification, close methods (that is, MessageConsumer.Close, Session.Close, Connection.Close) cannot return while any message callbacks (that is, EMSMessageHandler, IMessageListener.OnMessage) are running. As a result, a message callback must not call a close method, lest it cause a deadlock.
This method explicitly overrides this JMS requirement, permitting callbacks to call close without deadlock (that is, embedded close calls do not wait for callbacks to return).
See Also Tibems.GetAllowCloseInCallback on page 272
Parameter Description
allow When true, EMS overrides the JMS specification.
When false (the default), EMS obeys the JMS specification.
This method replaces the deprecated method SetAllowCallbackInClose.
TIBCO Enterprise Message Service .NET Reference
Tibems.SetConnectAttempts | 291
Tibems.SetConnectAttemptsMethod
Declaration static void SetConnectAttempts(string specs );
Purpose Modify the connection attempts setting.
Remarks This setting governs all client Connection objects as they attempt to connect to the server.
See Also Tibems.GetConnectAttempts on page 274
Parameter Description
specs Set the connect setting to these specifications. The value must be string of the form attempts or attempts,delay:
• attempts limits the number of times that the connection object attempts to establish a connection to the server. When this property is absent, the default value is 2. The minimum value is 1.
• delay is the time (in milliseconds) between connection attempts. When absent, the default value is 500. The minimum value is 250.
TIBCO Enterprise Message Service .NET Reference
292 | Chapter 13 Utilities
Tibems.SetConnectAttemptTimeoutMethod
Declaration static void SetConnectAttemptTimeout(int timeout
);
Purpose Set the maximum amount of time a client will wait for the connection to be established.
Remarks When too many clients connect to the same server, the server may not be able to accept all connections at the same time or may run out of system resources. This method specifies the amount of time a client is willing to wait for a connection to be established. Internally the client library will tear down any hung connections (either because of non-availability of system resources or some other EMS server problem) after the timeout period has elapsed.
See Also Tibems.SetReconnectAttemptTimeout on page 300Tibems.GetConnectAttemptTimeout on page 275
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide
Parameter Description
timeout Timeout value, in milliseconds. The minimum value is 100 milliseconds, if value less than 100 milliseconds is specified, then the minimum value of 100 milliseconds is used.
Default value is 0 (no timeout).
TIBCO Enterprise Message Service .NET Reference
Tibems.SetEncoding | 293
Tibems.SetEncodingMethod
Declaration static void SetEncoding(string encodingName );
Purpose Set the global string encoding for messages.
Remarks Programs can override the global encoding for individual messages. When neither a global nor an individual message encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.
This encoding applies to all strings in message body fields (names and values), and properties (names and values). It does not apply to message header fields. The methods BytesMessage.ReadUTF and BytesMessage.WriteUTF are exempt from global and individual encoding settings.
See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.GetEncoding on page 277Tibems.GetMessageEncoding on page 279Tibems.SetMessageEncoding on page 295
The only encoding names supported by the .NET client are the ones defined by the .NET framework. Please refer to the .NET framework documentation for a complete list of the supported encoding names.
Parameter Description
encodingName The name of the encoding (for example, "utf-8").
An EMSException is generated if the encoding is not supported.
For a list of standard encoding names, see www.iana.org.
TIBCO Enterprise Message Service .NET Reference
294 | Chapter 13 Utilities
Tibems.SetExceptionOnFTSwitchMethod
Declaration static void SetExceptionOnFTSwitch(bool callExceptionListener );
Purpose Modify the fault tolerance exception setting.
Remarks This setting determines exception behavior when the client successfully switches to a different server (fault-tolerant failover).
See Also IExceptionListener on page 133Tibems.GetExceptionOnFTSwitch on page 278
Parameter Description
callExceptionListener When true, the connection’s ExceptionListener catches an EMSException, which contains the name of the new server.
When false, fault-tolerant failover does not trigger an exception in the client.
TIBCO Enterprise Message Service .NET Reference
Tibems.SetMessageEncoding | 295
Tibems.SetMessageEncodingMethod
Declaration static void SetMessageEncoding(Message messagestring encodingName );
Purpose Set the character encoding for an individual message.
Remarks This encoding for an individual message overrides the global encoding. When neither a global nor an individual message encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.
This encoding applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The methods BytesMessage.ReadUTF and BytesMessage.WriteUTF are exempt from global and individual encoding settings.
See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.GetEncoding on page 277Tibems.SetEncoding on page 293Tibems.GetMessageEncoding on page 279
Parameter Description
message Set the encoding for this message.
encodingName Set this encoding.
For a list of standard encoding names, see www.iana.org.
TIBCO Enterprise Message Service .NET Reference
296 | Chapter 13 Utilities
Tibems.SetPingIntervalMethod
Declaration static void SetPingInterval(int seconds );
Purpose Set the interval at which the client tests network connectivity.
Remarks Clients test network connectivity by sending ping requests to the server at regular intervals. This method sets that interval (in seconds). If your program calls this method, it must do so before creating its first Connection object; after creating that object, this call has no effect.
See Also Tibems.GetPingInterval on page 281
Parameter Description
seconds Ping at this interval (in seconds).
Zero is a special value that disables ping testing.
TIBCO Enterprise Message Service .NET Reference
Tibems.SetProperty | 297
Tibems.SetPropertyMethod
Declaration static void SetProperty(string key,object val );
Purpose Modify a property value.
Remarks In .NET, methods exist to get and set the properties. SetProperty provides an alternate way to set property values, which is consistent with the EMS Java API (for easy porting to .NET).
Parameter Description
key Set the value associated with this property name.
You may supply any of the constants listed in the table below. The constants are defined as static fields of Tibems. The values of those constants are the actual property names.
value Set the property to this value.
Property Constant Corresponding Methods
PROP_SOCKET_RECEIVE_SIZE Tibems.GetSocketReceiveBufferSize on page 287
Tibems.SetSocketReceiveBufferSize on page 302
PROP_SOCKET_SEND_SIZE Tibems.GetSocketSendBufferSize on page 288
Tibems.SetSocketSendBufferSize on page 303
PROP_CONNECTION_ATTEMPTS Tibems.GetConnectAttempts on page 274
Tibems.SetConnectAttempts
PROP_RECONNECTION_ATTEMPTS Tibems.GetReconnectAttempts on page 284
Tibems.SetReconnectAttempts on page 299
PROP_CLOSE_IN_CALLBACK Tibems.GetAllowCloseInCallback on page 272
Tibems.SetAllowCloseInCallback on page 290
TIBCO Enterprise Message Service .NET Reference
298 | Chapter 13 Utilities
See Also Tibems.GetProperty on page 282
PROP_PING_INTERVAL Tibems.GetPingInterval on page 281
Tibems.SetPingInterval on page 296
PROP_FT_SWITCH Tibems.GetExceptionOnFTSwitch on page 278
Tibems.SetExceptionOnFTSwitch on page 294
PROP_MESSAGE_ENCODING Tibems.GetMessageEncoding on page 279
Tibems.SetMessageEncoding on page 295
PROP_DAEMON_DISPATCHER Tibems.GetSessionDispatcherDaemon on page 286
Tibems.SetSessionDispatcherDaemon on page 301
Property Constant Corresponding Methods
TIBCO Enterprise Message Service .NET Reference
Tibems.SetReconnectAttempts | 299
Tibems.SetReconnectAttemptsMethod
Declaration static void SetReconnectAttempts(string specs );
Purpose Modify the reconnection attempts setting.
Remarks This setting governs all client Connection objects as they attempt to reconnect to the server after a network disconnect.
See Also Tibems.GetReconnectAttempts on page 284
Parameter Description
specs Set the reconnect setting to these specifications. The value must be string of the form attempts or attempts,delay:
• attempts limits the number of times that the connection object attempts to reestablish a connection to the server. When this property is absent, the default value is 4. The minimum value is 1.
• delay is the time (in milliseconds) between reconnection attempts. When absent, the default value is 500. The minimum value is 250.
TIBCO Enterprise Message Service .NET Reference
300 | Chapter 13 Utilities
Tibems.SetReconnectAttemptTimeoutMethod
Declaration static void SetReconnectAttemptTimeout(int timeout
);
Purpose Sets the maximum amount of time a client will wait for the reconnect to complete.
Remarks This method is similar to Tibems.SetConnectAttemptTimeout. However, during the initial connect of the clients to the server, the time for each connect attempt is normally distributed and there are less chances of the server exceeding its maximum accept queue. During a fault-tolerant switch, all of the clients automatically try to reconnect to the backup server at approximately the same time. When the number of connections is large, it may require more reconnect time to reconnect than the initial connect.
See Also Tibems.SetConnectAttemptTimeout on page 292Tibems.GetReconnectAttemptTimeout on page 285
Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.
Parameter Description
timeout Timeout value, in milliseconds. The minimum value is 100 milliseconds, if value less than 100 milliseconds is specified, then the minimum value of 100 milliseconds is used.
Default value is 0 (no timeout).
TIBCO Enterprise Message Service .NET Reference
Tibems.SetSessionDispatcherDaemon | 301
Tibems.SetSessionDispatcherDaemonMethod
Declaration static void SetSessionDispatcherDaemon(bool makeDaemon );
Purpose Set the dispatcher thread setting.
Remarks When a program uses asynchronous message consumers (either message listeners or .NET message event handler delegates), EMS creates internal dispatcher threads for each Session that has at least one asynchronous message consumer. When this setting is true, those dispatcher threads are daemon threads; when false (the default) they are not daemon threads.
.NET CompactFramework
The .NET Compact Framework does not support daemon threads. This call has no effect, and returns without error.
See Also Tibems.GetSessionDispatcherDaemon on page 286
Parameter Description
makeDaemon • When true, dispatcher threads are daemon threads.
• When false, (the default) they are not daemon threads
TIBCO Enterprise Message Service .NET Reference
302 | Chapter 13 Utilities
Tibems.SetSocketReceiveBufferSizeMethod
Declaration static void SetSocketReceiveBufferSize(int size );
Purpose Set the size of socket receive buffers.
Remarks This value overrides the operating system’s default for the size of receive buffers associated with sockets that the client uses for connections to the server.
Use this call before creating server connections. This call sets an override buffer size for new socket buffers; it does not change the size of existing socket buffers.
.NET CompactFramework
The .NET Compact Framework does not permit changing the default socket buffer size. This call has no effect, and returns without error.
See Also Tibems.GetSocketReceiveBufferSize on page 287
Parameter Description
size Sockets use receive buffers of this size (in kilobytes).
TIBCO Enterprise Message Service .NET Reference
Tibems.SetSocketSendBufferSize | 303
Tibems.SetSocketSendBufferSizeMethod
Declaration static void SetSocketSendBufferSize(int size );
Purpose Set the size of socket send buffers.
Remarks This value overrides the operating system’s default for the size of send buffers associated with sockets that the client uses for connections to the server.
Use this call before creating server connections. This call sets an override buffer size for new socket buffers; it does not change the size of existing socket buffers.
.NET CompactFramework
The .NET Compact Framework does not permit changing the default socket buffer size. This call has no effect, and returns without error.
See Also Tibems.GetSocketSendBufferSize on page 288
Parameter Description
size Sockets use send buffers of this size (in kilobytes).
TIBCO Enterprise Message Service .NET Reference
304 | Chapter 13 Utilities
TIBCO Enterprise Message Service .NET Reference
| 305
Chapter 14 Exception
This chapter presents exceptions related to EMS.
Topics
• EMSException, page 306
• AuthenticationException, page 308
• CannotProceedException, page 309
• CommunicationException, page 310
• ConfigurationException, page 311
• IllegalStateException, page 312
• InvalidClientIDException, page 313
• InvalidDestinationException, page 314
• InvalidNameException, page 315
• InvalidSelectorException, page 316
• MessageEOFException, page 317
• MessageFormatException, page 318
• MessageNotReadableException, page 319
• MessageNotWriteableException, page 320
• NameNotFoundException, page 321
• NamingException, page 322
• ResourceAllocationException, page 323
• SecurityException, page 324
• ServiceUnavailableException, page 325
• TransactionInProgressException, page 326
• TransactionRolledBackException, page 327
TIBCO Enterprise Message Service .NET Reference
306 | Chapter 14 Exception
EMSExceptionClass
Declaration class EMSException : System.Exception
Purpose Root of exceptions specific to EMS.
Origin Corresponds to JMSException in JMS.
Remarks EMS methods throw instances of this class and its subclasses.
Subclasses EMSExceptionIllegalStateExceptionInvalidClientIDExceptionInvalidDestinationExceptionInvalidSelectorExceptionMessageEOFExceptionMessageFormatExceptionMessageNotReadableExceptionMessageNotWriteableExceptionNamingException
AuthenticationExceptionCannotProceedExceptionCommunicationExceptionConfigurationExceptionInvalidNameExceptionNameNotFoundExceptionServiceUnavailableException
ResourceAllocationExceptionSecurityExceptionTransactionInProgressExceptionTransactionRolledBackException
Member Description
Properties
ErrorCode string {get;}
When an exception results from a server error, this property holds the server’s error code.
LinkedException System.Exception {get; set;}
When an EMS exception results from a deeper problem, this linked exception details that problem.
TIBCO Enterprise Message Service .NET Reference
EMSException | 307
Constructors EMSException (string reason );
EMSException (string reason,string errorCode );
TIBCO Enterprise Message Service .NET Reference
308 | Chapter 14 Exception
AuthenticationExceptionClass
Declaration class AuthenticationException : NamingException
Purpose Invalid authentication or insufficient privileges for a lookup request.
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
CannotProceedException | 309
CannotProceedExceptionClass
Declaration class CannotProceedException : NamingException
Purpose Insufficient information to resolve a lookup request.
Remarks A destination lookup request found both a queue and a topic with the specified name. To resolve this situation, specify the destination name in one of these forms:
• $topic:<topic-name>
• $queue:<queue-name>
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
310 | Chapter 14 Exception
CommunicationExceptionClass
Declaration class CommunicationException : NamingException
Purpose A lookup request returned bad data.
Remarks This exception could indicate a version mismatch between the client and tibemsd.
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
ConfigurationException | 311
ConfigurationExceptionClass
Declaration class ConfigurationException : NamingException
Purpose Configuration error associated with a lookup context object.
Remarks When the client initialized the lookup context, some parameter values were missing or invalid.
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
312 | Chapter 14 Exception
IllegalStateExceptionClass
Declaration class IllegalStateException : EMSException
Purpose A method call or server request occurred in an inappropriate context.
Origin JMS.
Remarks For example, Session.Commit throws this exception when the session is non-transactional.
TIBCO Enterprise Message Service .NET Reference
InvalidClientIDException | 313
InvalidClientIDExceptionClass
Declaration class InvalidClientIDException : EMSException
Purpose The provider rejects the connection’s client ID.
Origin JMS.
Remarks Setting a connection’s client ID to an invalid or duplicate value results in this exception. (A duplicate value is one that is already in use by another connection.)
TIBCO Enterprise Message Service .NET Reference
314 | Chapter 14 Exception
InvalidDestinationExceptionClass
Declaration class InvalidDestinationException : EMSException
Purpose tibemsd cannot locate the destination.
Origin JMS.
TIBCO Enterprise Message Service .NET Reference
InvalidNameException | 315
InvalidNameExceptionClass
Declaration class InvalidNameException : NamingException
Purpose In a lookup request, the name has incorrect syntax.
Remarks The most common syntax error is a prefix other than tibjmsnaming:// (or a misspelling).
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
316 | Chapter 14 Exception
InvalidSelectorExceptionClass
Declaration class InvalidSelectorException : EMSException
Purpose The client passed a message selector with invalid syntax.
Origin JMS.
See Also Message Selectors on page 18
TIBCO Enterprise Message Service .NET Reference
MessageEOFException | 317
MessageEOFExceptionClass
Declaration class MessageEOFException : EMSException
Purpose The data stream within a message ended unexpectedly.
Origin JMS.
Remarks BytesMessage contains a stream of bytes. StreamMessage contains a stream of characters. If any of their read methods detects the end of the stream unexpectedly, it throws this exception.
TIBCO Enterprise Message Service .NET Reference
318 | Chapter 14 Exception
MessageFormatExceptionClass
Declaration class MessageFormatException : EMSException
Purpose Datatype mismatch.
Origin JMS.
Remarks For example:
• A read method cannot read the data with the specified type.
• A write method cannot store the data in the message or property because the data has the wrong type.
TIBCO Enterprise Message Service .NET Reference
MessageNotReadableException | 319
MessageNotReadableExceptionClass
Declaration class MessageNotReadableException : EMSException
Purpose Attempt to read from a message in write-only mode.
Origin JMS.
TIBCO Enterprise Message Service .NET Reference
320 | Chapter 14 Exception
MessageNotWriteableExceptionClass
Declaration class MessageNotWriteableException : EMSException
Purpose Attempt to write to a message in read-only mode.
Origin JMS.
See Also Tibems.MakeWriteable on page 289
TIBCO Enterprise Message Service .NET Reference
NameNotFoundException | 321
NameNotFoundExceptionClass
Declaration class NameNotFoundException : NamingException
Purpose The name lookup repository cannot find a name; the name is not bound.
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
322 | Chapter 14 Exception
NamingExceptionClass
Declaration class NamingException : EMSException
Purpose Root of exceptions related to name lookup requests.
Remarks Members of LookupContext throw instances of this class and its subclasses.
Subclasses NamingExceptionAuthenticationExceptionCannotProceedExceptionCommunicationExceptionConfigurationExceptionInvalidNameExceptionNameNotFoundExceptionServiceUnavailableException
See Also LookupContext on page 215
Member Description
Properties
RootCause System.Exception {get; set;}
When a naming exception results from a more general problem, this exception details that problem.
TIBCO Enterprise Message Service .NET Reference
ResourceAllocationException | 323
ResourceAllocationExceptionClass
Declaration class ResourceAllocationException : EMSException
Purpose Required resources are not available.
Origin JMS.
TIBCO Enterprise Message Service .NET Reference
324 | Chapter 14 Exception
SecurityExceptionClass
Declaration class SecurityException : EMSException
Purpose The method cannot complete because of a security restriction.
Origin JMS.
Remarks For example, the provider rejects a user or the user’s authentication.
TIBCO Enterprise Message Service .NET Reference
ServiceUnavailableException | 325
ServiceUnavailableExceptionClass
Declaration class ServiceUnavailableException : NamingException
Purpose A lookup request failed because the client could not connect to the server.
See Also LookupContext on page 215
TIBCO Enterprise Message Service .NET Reference
326 | Chapter 14 Exception
TransactionInProgressExceptionClass
Declaration class TransactionInProgressException : EMSException
Purpose Reserved for future use.
Origin JMS.
Remarks When a session uses an XA transaction manager, the XA resource is the correct locus for all commit and rollback requests. Local commit or rollback calls are not permitted, and throw this exception.
TIBCO Enterprise Message Service .NET Reference
TransactionRolledBackException | 327
TransactionRolledBackExceptionClass
Declaration class TransactionRolledBackException : EMSException
Purpose An attempt to commit a transaction resulted in rollback.
Origin JMS.
TIBCO Enterprise Message Service .NET Reference
328 | Chapter 14 Exception
TIBCO Enterprise Message Service .NET Reference
| 329
Index
A
Acknowledge 25AuthenticationException 308
B
body types, message 9BodyLength 32BytesMessage 32
Read methods 34ReadBytes 36Reset 40Write methods 37WriteBytes 39
C
CalculateMessageSize 270CannotProceedException 309character encoding 4, 277, 279, 293, 295ClearBody 26ClearProperties 26Clone 26Close
Connection 121MessageConsumer 82MessageProducer 97QueueBrowser 204QueueRequestor 110Session 176TopicRequestor 114
Commit 177CommunicationException 310Compact Framework 5
compression 3ConfigurationException 311Connection 118
Close 121CreateSession 122Start 123Stop 124
ConnectionConsumer (not supported) 3ConnectionFactory 138
constructor 141CreateConnection 142
ConnectionMetaData 125conversion, data type 21CreateBrowser 178CreateBytesMessage 179CreateConnection 142CreateConsumer 180CreateDurableSubscriber 181CreateFromBytes 271CreateMapMessage 183CreateObjectMessage 184CreateProducer 185CreateQueue 186CreateQueueConnection 162CreateQueueSession 127CreateSession 122CreateStreamMessage 187CreateTemporaryQueue 188CreateTemporaryTopic 189CreateTextMessage 190CreateTopic 191CreateTopicConnection 165CreateTopicSession 129customer support xvii
TIBCO Enterprise Message Service .NET Reference
330 | Index
D
daemon threads 3data type conversion 21Delete
TemporaryQueue 73TemporaryTopic 75
DeliveryMode 260Deserialize 262Destination 69
overview 66durable subscription
unsubscribe 195dynamic destination 66
E
EMSException 306EMSExceptionEventArgs 131
constructor 132EMSExceptionHandler 130EMSMessageEventArgs 88
constructor 89Message 88
EMSMessageHandler 87encoding, character 4, 277, 279, 293, 295exceptions 305
F
FactoryLoadBalanceMetric 167fault tolerance
ActiveURL 119failover exceptions 278, 294
FieldCountMapMessage 41StreamMessage 50
G
GetMapMessage 44message properties 28
GetAllowCloseInCallback 272GetAsBytes 273GetConnectAttempts 274GetConnectAttemptTimeout 275GetDeliveryModeName 27GetEncoding 277GetEnumerator 205GetExceptionOnFTSwitch 278GetMessageBodySize 280GetMessageEncoding 279GetMessageHeadersSize 280GetMessageSize 280GetPingInterval 281GetProperty, Tibems 282GetReconnectAttempts 284GetReconnectAttemptTimeout 285GetSessionDispatcherDaemon 286GetSocketReceiveBufferSize 287GetSocketSendBufferSize 288
H
headers, message 10
I
IEMSSerialziable 261Deserialize 262Serialize 263
IExceptionListener 133OnException 134
IllegalStateException 312IMessageListener 90
OnMessage 91InvalidClientIDException 313InvalidDestinationException 314
TIBCO Enterprise Message Service .NET Reference
Index | 331
InvalidNameException 315InvalidSelectorException 316ItemExists 45
L
Lookup 219LookupContext 210, 215
AddSettingsAddSettings 218
constructor 217Lookup 219RemoveSettings 220
M
MakeWriteable 289MapMessage 41
FieldCount 41Get methods 44ItemExists 45MapNames 41set methods 46SetBytes 47
MapNames 41Message 22
Acknowledge 25body types 9BodyLength 32ClearBody 26ClearProperties 26Clone 26EMSMessageEventArgs 88get property methods 28GetDeliveryModeName 27headers 10parts of 8properties 15PropertyExists 29set property methods 30ToString 31
messageselectors 18
MessageConsumer 80Close 82MessageHandler 80MessageListener 80MessageSelector 81Receive 83ReceiveNoWait 84
MessageDeliveryMode 264MessageEOFException 317MessageFormatException 318MessageHandler 80MessageListener 80MessageNotReadableException 319MessageNotWriteableException 320MessageProducer 94
Close 97Send 98
MessageProducer.Close 97MessageProducer.Send 98MessageSelector 81MoveNext 206
N
NameNotFoundException 321NamingException 322.NET Compact Framework 5NoLocal 86
O
object serialization 3ObjectMessage 48
constructor 49TheObject 48
OnException 134OnMessage 91
TIBCO Enterprise Message Service .NET Reference
332 | Index
P
property, message 15get 28set 30
PropertyExists 29Publish 104
Q
Queue 70constructor 71QueueName 70QueueReceiver 85
QueueBrowser 202Close 204GetEnumerator 205MoveNext 206Reset 207
QueueConnection 126CreateQueueSession 127
QueueConnectionFactory 161CreateQueueConnection 162
QueueName 70QueueReceiver 85
Queue 85QueueRequestor 108
Close 110constructor 109Request 111
QueueSender 100Send 101
QueueSender.Send 101QueueSession 196
R
ReadBytesMessage 34StreamMethod 53
ReadBytesBytesMessage 36StreamMessage 54
read-only 26, 40, 55, 271, 320Receive 83ReceiveNoWait 84Recover 192RemoveSettings 220Request
QueueRequestor 111TopicRequestor 115
request 10Reset
BytesMessage 40QueueBrowser 207StreamMessage 55
ResourceAllocationException 323Rollback 193Run (obsolete) 194
S
SecurityException 324selectors, message 18Send
MessageProducer 98QueueSender 101
serializable object interface 261serialization 3Serialize 263ServerSession (not supported) 3ServerSessionPool (not supported) 3ServiceUnavailableException 325
TIBCO Enterprise Message Service .NET Reference
Index | 333
Session 170Close 176Commit 177CreateBrowser 178CreateBytesMessage 179CreateConsumer 180CreateDurableSubscriber 181CreateMapMessage 183CreateObjectMessage 184CreateProducer 185CreateQueue 186CreateStreamMessage 187CreateTemporaryQueue 188CreateTemporaryTopic 189CreateTextMessage 190CreateTopic 191Recover 192Rollback 193Run (obsolete) 194Unsubscribe 195
SessionMode 198Set
MapMessage 46message property 30
SetAllowCloseInCallback 290SetBytes 47SetConnectAttempts 291SetConnectAttemptTimeout 292SetEncoding 293SetExceptionOnFTSwitch 294SetMessageEncoding 295SetPingInterval 296SetProperty, Tibems 297SetReconnectAttempts 299SetReconnectAttemptTimeout 300SetSessionDispatcherDaemon 301SetSocketReceiveBufferSize 302SetSocketSendBufferSize 303SSL 3Start 123static destination 66Stop 124
StreamMessage 50FieldCount 50Read methods 53ReadBytes 54Reset 55Write methods 56WriteBytes 57
string and character encoding 4support, contacting xvii
T
technical support xviitemporary destination 66TemporaryQueue 72
Delete 73TemporaryTopic 74
Delete 75Text 58TextMessage 58
constructor 59Text 58
TheObject 48
TIBCO Enterprise Message Service .NET Reference
334 | Index
Tibems 265CalculateMessageSize 270CreateFromBytes 271GetAllowCloseInCallback 272GetAsBytes 273GetConnectAttempts 274GetConnectAttemptTimeout 275GetEncoding 277GetExceptionOnFTSwitch 278GetMessageBodySize 280GetMessageEncoding 279GetMessageHeadersSize 280GetMessageSize 280GetPingInterval 281GetProperty 282GetReconnectAttempts 284GetReconnectAttemptTimeout 285GetSessionDispatcherDaemon 286GetSocketReceiveBufferSize 287GetSocketSendBufferSize 288MakeWriteable 289SetAllowCloseInCallback 290SetConnectAttempts 291SetConnectAttemptTimeout 292SetEncoding 293SetExceptionOnFTSwitch 294SetMessageEncoding 295SetPingInterval 296SetProperty 297SetReconnectAttempts 299SetReconnectAttemptTimeout 300SetSessionDispatcherDaemon 301SetSocketReceiveBufferSize 302SetSocketSendBufferSize 303
tibemsd 138, 209Topic 76
constructor 77TopicName 76TopicSubscriber 86
TopicConnection 128CreateTopicSession 129
TopicConnectionFactory 164CreateTopicConnection 165
TopicName 76
TopicPublisher 103Publish 104
TopicPublisher.Publish 104TopicRequestor 112
Close 114constructor 113Request 115
TopicSession 197TopicSubscriber 86
NoLocal 86Topic 86
ToString 31TransactionInProgressException 326TransactionRolledBackException 327translation, character encoding 4type conversion 21
U
Unicode 4Unsubscribe 195
W
WriteBytesMessage 37StreamMessage 56
WriteBytesBytesMessage 39StreamMessage 57
X
XA (not supported) 3
TIBCO Enterprise Message Service .NET Reference