TIBCO Enterprise Message

Service™
.NET Reference
Software Release 4.4
November 2006
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH
EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY
(OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE.
THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY
ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND
CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED
SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT,
THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING
DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE
TIBCO Enterprise Message Service User’s Guide). USE OF THIS DOCUMENT IS SUBJECT TO THOSE
TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE
OF AND AN AGREEMENT TO BE BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright
laws and treaties. No part of this document may be reproduced in any form without the written
authorization of TIBCO Software Inc.
TIB, TIBCO, Information Bus, The Power of Now, TIBCO 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
TIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Third Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Excluded Features and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Object 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Setting Message Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
EMS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
JMS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Message Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Data Type Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Message.Acknowledge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Message.ClearBody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message.ClearProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Message.GetDeliveryModeName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Message.Get Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

TIBCO Enterprise Message Service .NET Reference

iv
| Contents
Message.PropertyExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Message.Set Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Message.ToString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
BytesMessage.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
BytesMessage.ReadBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
BytesMessage.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
BytesMessage.WriteBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
BytesMessage.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
MapMessage.Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
MapMessage.ItemExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
MapMessage.Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
MapMessage.SetBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
StreamMessage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
StreamMessage.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
StreamMessage.ReadBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
StreamMessage.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
StreamMessage.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
StreamMessage.WriteBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
TextMessage.ClearBody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
TextMessage.Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Message.EmptyEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Message.EmptyEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Message.EmptyEnum.MoveNext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Message.EmptyEnum.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 3 Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Destination Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
TemporaryQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
TemporaryQueue.Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
TemporaryTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

TIBCO Enterprise Message Service .NET Reference

 Contents v
|
TemporaryTopic.Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 4 Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
MessageConsumer.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
MessageConsumer.Receive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
MessageConsumer.ReceiveNoWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
QueueReceiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
TopicSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
EMSMessageHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
EMSMessageEventArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
EMSMessageEventArgs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
IMessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
IMessageListener.OnMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Chapter 5 Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
MessageProducer.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
MessageProducer.Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
QueueSender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
QueueSender.Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
TopicPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
TopicPublisher.Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 6 Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

QueueRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
QueueRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
QueueRequestor.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
QueueRequestor.Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
TopicRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
TopicRequestor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
TopicRequestor.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
TopicRequestor.Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 7 Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Connection.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Connection.CreateSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

TIBCO Enterprise Message Service .NET Reference

vi
| Contents
Connection.Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Connection.Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
QueueConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
QueueConnection.CreateQueueSession. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
TopicConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
TopicConnection.CreateTopicSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
EMSExceptionHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
EMSExceptionEventArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
EMSExceptionEventArgs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
IExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
IExceptionListener.OnException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Chapter 8 Connection Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

ConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
ConnectionFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
ConnectionFactory.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
ConnectionFactory.CreateConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
ConnectionFactory.GetSSLProxyHost. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ConnectionFactory.GetSSLProxyPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ConnectionFactory.GetSSLProxyPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ConnectionFactory.GetSSLProxyUser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ConnectionFactory.SetCertificateStoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
ConnectionFactory.SetClientID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
ConnectionFactory.SetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
ConnectionFactory.SetConnAttemptCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ConnectionFactory.SetConnAttemptDelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
ConnectionFactory.SetConnAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ConnectionFactory.SetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
ConnectionFactory.SetMetric. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ConnectionFactory.SetReconnAttemptCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
ConnectionFactory.SetReconnAttemptDelay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
ConnectionFactory.SetReconnAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
ConnectionFactory.SetServerUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
ConnectionFactory.SetSSLAuthOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
ConnectionFactory.SetSSLProxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
ConnectionFactory.SetSSLProxyAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
ConnectionFactory.SetSSLTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
ConnectionFactory.SetTargetHostName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
ConnectionFactory.SetUserName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
ConnectionFactory.SetUserPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
QueueConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

TIBCO Enterprise Message Service .NET Reference

 Contents vii
|
QueueConnectionFactory.CreateQueueConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
QueueConnectionFactory.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
TopicConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
TopicConnectionFactory.CreateTopicConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
TopicConnectionFactory.Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
FactoryLoadBalanceMetric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Chapter 9 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Session.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Session.Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Session.CreateBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Session.CreateBytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Session.CreateConsumer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Session.CreateDurableSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Session.CreateMapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Session.CreateObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Session.CreateProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Session.CreateQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Session.CreateStreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Session.CreateTemporaryQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Session.CreateTemporaryTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Session.CreateTextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Session.CreateTopic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Session.Recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Session.Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Session.Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Session.Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
QueueSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
TopicSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
SessionMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Chapter 10 Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

QueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
QueueBrowser.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
QueueBrowser.GetEnumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
QueueBrowser.MoveNext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
QueueBrowser.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Chapter 11 Name Server Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

ILookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
ILookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

TIBCO Enterprise Message Service .NET Reference

viii
| Contents
ILookupContext.Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
ILookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
LookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
LookupContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
LookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
LookupContext.Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
LookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
LookupContextFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
LookupContextFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
LookupContextFactory.CreateContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
LdapLookupConsts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
LdapLookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
LdapLookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
LdapLookupContext.Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
LdapLookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
LdapLookupSSLParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
LdapLookupSSLParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
LdapLookupSSLParams.SetSSLQueryClientCertificateCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
LdapLookupSSLParams.SetSSLVerifyServerCertificateCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Chapter 12 SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

EMSSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
EMSSSL.GetAuthOnly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
EMSSSL.GetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
EMSSSL.GetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
EMSSSL.GetTargetHostName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
EMSSSL.Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
EMSSSL.SetAuthOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
EMSSSL.SetCertificateStoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
EMSSSL.SetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
EMSSSL.SetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
EMSSSL.SetTargetHostName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
EMSSSLFileStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
EMSSSLFileStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
EMSSSLFileStoreInfo.ClearTrustedCerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
EMSSSLFileStoreInfo.SetSSLClientIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
EMSSSLFileStoreInfo.SetSSLPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
EMSSSLFileStoreInfo.SetSSLTrustedCertificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
EMSSSLSystemStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
EMSSSLSystemStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
EMSSSLSystemStoreInfo.SetCertificateName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
EMSSSLSystemStoreInfo.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
IEMSSerialziable.Deserialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
IEMSSerialziable.Serialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
MessageDeliveryMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Tibems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Tibems.CalculateMessageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Tibems.CreateFromBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Tibems.GetAllowCloseInCallback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Tibems.GetAsBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Tibems.GetConnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Tibems.GetConnectAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Tibems.GetConnectionActiveURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Tibems.GetEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Tibems.GetExceptionOnFTSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Tibems.GetMessageEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Tibems.GetMessageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Tibems.GetPingInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Tibems.GetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Tibems.GetReconnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Tibems.GetReconnectAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Tibems.GetSessionDispatcherDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Tibems.GetSocketReceiveBufferSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Tibems.GetSocketSendBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Tibems.MakeWriteable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Tibems.SetAllowCloseInCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Tibems.SetConnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Tibems.SetConnectAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Tibems.SetEncoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Tibems.SetExceptionOnFTSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Tibems.SetMessageEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Tibems.SetPingInterval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Tibems.SetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Tibems.SetReconnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Tibems.SetReconnectAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Tibems.SetSessionDispatcherDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Tibems.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

 | 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.

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.

Topics

• Related Documentation, page xiv

• Typographical Conventions, page xv
• How to Contact TIBCO Customer Support, page xvii

TIBCO Enterprise Message Service .NET Reference

xiv
| Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Enterprise Message Service Documentation

The following documents form the TIBCO Enterprise Message Service
documentation set:
• TIBCO Enterprise Message Service User’s Guide Read this manual to gain an
overall understanding of the product, 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 Documentation

You may find it useful to read the documentation for the following TIBCO
products:
• TIBCO Rendezvous™ software
• TIBCO SmartSockets™ software

TIBCO Enterprise Message Service .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 Bold code font is used in the following ways:

font
• 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
Table 1 General Typographical Conventions

Convention Use
Key Key name separated by a plus sign indicate keys pressed simultaneously. For
combinations example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.

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 The default parameter.

font
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
|

TIBCO Enterprise Message Service .NET Reference

 |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.

Table 3 Feature Support

.NET
Feature .NET Compact
Framework
XA protocols for external transaction managers — —

ConnectionConsumer, ServerSession, ServerSessionPool — —

Compression Yes —

SSL Yes —

Modify socket buffer sizes (see Yes —

Tibems.SetSocketReceiveBufferSize on page 302 and
Tibems.SetSocketSendBufferSize on page 303).

Daemon threads (see Tibems.SetSessionDispatcherDaemon Yes —

on page 301).

Object Serialization
The .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.

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.

Outbound Programs can determine the encoding of strings in outbound messages in three
Messages 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.

Outbound An inbound message from another EMS client explicitly announces its encoding.
Messages 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.

Object See Object Serialization on page 3.

Serialization

Excluded See Excluded Features and Restrictions on page 3.

Features

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
|
Table 5 Message Header Names

Header Description
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.

TIBCO Enterprise Message Service .NET Reference

12
| Chapter 2 Messages

Table 5 Message Header Names

Header Description
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.

TIBCO Enterprise Message Service .NET Reference

 Headers 13
|
Table 5 Message Header Names

Header Description
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.

TIBCO Enterprise Message Service .NET Reference

14
| Chapter 2 Messages

Table 5 Message Header Names

Header Description
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.

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 Properties

Property 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 Properties
The 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

Table 6 Message Property Names

Property Description
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).

TIBCO Enterprise Message Service .NET Reference

 Properties 17
|

JMS Properties
The 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 Numeric An exact numeric literal is a numeric value without a decimal point, such as 57,
Literal -957, and +62; numbers in the range of long are supported.

Approximate An approximate numeric literal is a numeric value with a decimal point (such as
Numeric Literal 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 as Every selector is a conditional expression. A selector that evaluates to true

Expressions matches the message; a selector that evaluates to false or unknown does not
match.

Arithmetic Arithmetic expressions are composed of numeric literals, identifiers (that evaluate
Expression to numeric literals), arithmetic operations, and smaller arithmetic expressions.

Conditional Conditional expressions are composed of comparison operations, logical

Expression operations, and smaller conditional expressions.

Order of Order of evaluation is left-to-right, within precedence levels. Parentheses override

Evaluation this order.

Operators

Case Insensitivity Operator names are case-insensitive.

Logical Operators Logical operators in precedence order: NOT, AND, OR.

Comparison Comparison operators: =, >, >=, <, <=, <> (not equal).
Operators
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 <>.

Arithmetic Arithmetic operators in precedence order:

Operators
• +, - (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

Between arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 AND arithmetic-expr3

Operator
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

String identifier [NOT] IN (string-literal1, string-literal2, ...)

Set Membership
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 or identifier IS NULL

Property
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.

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

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.

TIBCO Enterprise Message Service .NET Reference

22
| Chapter 2 Messages

Message
Class

Declaration public class Message : ICloneable

Subclasses BytesMessage on page 32

MapMessageon page 41
ObjectMessage on page 48
StreamMessage on page 50
TextMessage 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 This table lists the JMS headers that are available as .NET properties of message
.NET Properties 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 29

on a message.

TIBCO Enterprise Message Service .NET Reference

24
| Chapter 2 Messages

Method Description Page

Message.Set Property Set the value of a message property. 30

Message.ToString Return a string representation of a message 31

object.

TIBCO Enterprise Message Service .NET Reference

 Message.Acknowledge 25
|

Message.Acknowledge
Method

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 83

Sessionon page 170
AcknowledgeMode on page 171
SessionAcknowledgeMode on page 171
QueueSession on page 196

TIBCO Enterprise Message Service .NET Reference

26
| Chapter 2 Messages

Message.ClearBody
Method

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.ClearProperties
Method

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.Clone
Method

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.GetDeliveryModeName
Method

Declaration static string GetDeliveryModeName(

MessageDeliveryMode deliveryMode );

static string GetDeliveryModeName

(int deliveryMode );

Purpose Convert a delivery mode constant to a string.

Parameters Parameter Description

deliveryMode Convert this delivery mode to a string.

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 260

MessageDeliveryMode on page 264

TIBCO Enterprise Message Service .NET Reference

28
| Chapter 2 Messages

Message.Get Property
Method

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 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.

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

TIBCO Enterprise Message Service .NET Reference

 Message.PropertyExists 29
|

Message.PropertyExists
Method

Declaration virtual bool PropertyExists(

string name );

Purpose Test whether a named property has been set on a message.

Parameters Parameter Description

name Test whether the message has a property with this name.

Remarks This call returns true if the property has a value on the message; otherwise it
returns false.

TIBCO Enterprise Message Service .NET Reference

30
| Chapter 2 Messages

Message.Set Property
Method

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 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.

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

TIBCO Enterprise Message Service .NET Reference

 Message.ToString 31
|

Message.ToString
Method

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

BytesMessage
Class

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.

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 34
message body.

BytesMessage.ReadBytes Read bytes to a byte array from the byte stream in the 36
message body.

BytesMessage.Write Write primitive data types to the byte stream in the 37

message body.

BytesMessage.WriteBytes Write bytes from a byte array to the byte stream in the 39
message body.

BytesMessage.Reset Set the read position to the beginning of the byte 40

stream, and mark the message body as read-only.

Member Description
Properties

BodyLength long {get;}

Programs can get the length of the message body (in bytes). Programs
cannot set this .NET property.

Superclasses Message on page 22

TIBCO Enterprise Message Service .NET Reference

 BytesMessage 33
|

BytesMessage
Constructor

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.Read
Method

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
|
Table 8 BytesMessage Read Methods

Method # Bytes Interpret As

ReadInt 4 int

ReadLong 8 long

ReadFloat 4 float

ReadDouble 8 double

ReadUTF varies String

Encoded as UTF-8

See Also BytesMessage.ReadBytes on page 36

TIBCO Enterprise Message Service .NET Reference

36
| Chapter 2 Messages

BytesMessage.ReadBytes
Method

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 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).

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.

TIBCO Enterprise Message Service .NET Reference

 BytesMessage.Write 37
|

BytesMessage.Write
Method

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.

Parameter Description
value Write this value to the message.

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.

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

Table 9 BytesMessage Write Methods

Method # Bytes Notes

WriteObject varies Converts an object to a primitive value (if
possible), and writes that value to the byte
stream.

See Also BytesMessage.WriteBytes on page 39

TIBCO Enterprise Message Service .NET Reference

 BytesMessage.WriteBytes 39
|

BytesMessage.WriteBytes
Method

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 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.

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).

TIBCO Enterprise Message Service .NET Reference

40
| Chapter 2 Messages

BytesMessage.Reset
Method

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
|

MapMessage
Class

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.

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.

Superclasses Message on page 22

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
|

MapMessage
Constructor

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.Get
Method

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 Parameter Description

name Get the value associated with this name.

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.

TIBCO Enterprise Message Service .NET Reference

 MapMessage.ItemExists 45
|

MapMessage.ItemExists
Method

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.Set
Method

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 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.

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

TIBCO Enterprise Message Service .NET Reference

 MapMessage.SetBytes 47
|

MapMessage.SetBytes
Method

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 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.

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

TIBCO Enterprise Message Service .NET Reference

48
| Chapter 2 Messages

ObjectMessage
Class

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.

Member Description
Properties

TheObject Object {get; set;}

Programs can get and set the object in an ObjectMessage.

Method Description Page

ObjectMessage Constructor. 49

.NET Object serialization differs among the various EMS language APIs in ways that
Compact are incompatible. An ObjectMessage contains a serialized object. Therefore EMS
Framework 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 22

IEMSSerialziable on page 261
MessageFormatException on page 318

TIBCO Enterprise Message Service .NET Reference

 ObjectMessage 49
|

ObjectMessage
Constructor

Declaration public ObjectMessage(

Session session,
object obj );

public ObjectMessage(
Session session );

Purpose Create an object message.

Parameters 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.

See Also .NET Compact Framework on page 48

Session.CreateObjectMessage on page 184

TIBCO Enterprise Message Service .NET Reference

50
| Chapter 2 Messages

StreamMessage
Class

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.

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, 55

and mark the message body as read-only.

StreamMessage.Write Write primitive data types to a stream message. 56

BytesMessage.WriteBytes Write bytes from a byte array to a stream message. 57

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.

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

StreamMessage
Constructor

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.Read
Method

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.ReadBytes
Method

Declaration int ReadBytes(byte[] value);

Purpose Read a byte array from a stream message.

Parameters Parameter Description

value The program supplies a byte array. The call fills it with bytes
from the stream message.

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.

TIBCO Enterprise Message Service .NET Reference

 StreamMessage.Reset 55
|

StreamMessage.Reset
Method

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.Write
Method

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
Parameter Description
value Write this datum.

See Also StreamMessage.WriteBytes on page 57

TIBCO Enterprise Message Service .NET Reference

 StreamMessage.WriteBytes 57
|

StreamMessage.WriteBytes
Method

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 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.

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).

TIBCO Enterprise Message Service .NET Reference

58
| Chapter 2 Messages

TextMessage
Class

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.

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

Superclasses Message on page 22

TIBCO Enterprise Message Service .NET Reference

 TextMessage 59
|

TextMessage
Constructor

Declaration public TextMessage(

Session session,
string text );

public ObjectMessage(
Session session );

Purpose Create a text message object.

Parameters Parameter Description

session Associate the new message with this session.

text Use this string as the value of the new message.

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

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.EmptyEnum
Class

Declaration class Message.EmptyEnum : IEnumerator

Purpose Specifies an empty enumerator

Remarks Messages with this body type contain a single value, which is a string.

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 62

collection.

Message.EmptyEnum.Reset Reset the enumerator. 62

Requirements Namespace: TIBCO.EMS

Assembly: TIBCO.EMS (in TIBCO.EMS.dll)

TIBCO Enterprise Message Service .NET Reference

62
| Chapter 2 Messages

Message.EmptyEnum
Constructor

Declaration Message.EmptyEnum();

Purpose Construct an empty enumerator.

Message.EmptyEnum.MoveNext
Method

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 Dynamic destinations give Temporary destinations
administrators configure client programs the are ideal for limited-scope
EMS behavior at the flexibility to define uses, such as reply
enterprise level. destinations as needed for subjects.
Administrators define short-term use.
these administered objects,
and client programs use
them—relieving program
developers and end users
of the responsibility for
correct configuration.

Scope of Static destinations support Dynamic destinations Temporary destinations

Delivery concurrent use. That is, support concurrent use. support only local use.
several client processes That is, several client That is, only the client
(and in several threads processes (and in several connection that created a
within a process) can threads within a process) temporary destination can
create local objects can create local objects consume messages from it.
denoting the destination, denoting the destination,
However, servers
and consume messages and consume messages
connected by routes do
from it. from it.
exchange messages sent to
temporary topics.

TIBCO Enterprise Message Service .NET Reference

 Destination Overview 67
|

Table 10 Destination Overview

Aspect Static Dynamic Temporary

Creation Administrators create If the server configuration Client programs create
static destinations using permits dynamic temporary destinations;
EMS server administration destinations, client see Session on page 170.
tools or API. 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.

Lookup Client programs lookup Client programs lookup Not applicable.

static destinations by dynamic destinations by
name. Successful lookup name. Successful lookup
returns a local object returns a local object
representation of the representation of the
destination; see destination; see
LookupContext.Lookup LookupContext.Lookup
on page 219. on page 219.

TIBCO Enterprise Message Service .NET Reference

68
| Chapter 3 Destination

Table 10 Destination Overview

Aspect Static Dynamic Temporary

Duration A static destination A dynamic destination A temporary destination
remains in the server until remains in the server as remains in the server either
an administrator explicitly long as at least one client until the client that created
deletes it. actively uses it. The server it explicitly deletes it, or
automatically deletes it (at until the client disconnects
a convenient time) when from the server.
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

TIBCO Enterprise Message Service .NET Reference

 Destination 69
|

Destination
Class

Declaration class Destination

Purpose Root behavior of all destinations.

Subclasses Queue on page 70

TemporaryQueue on page 72
Topic on page 76
TemporaryTopic 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

Queue
Class

Declaration class Queue : Destination

Purpose Queues deliver each message to exactly one consumer.

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

Subclasses TemporaryQueue on page 72

TIBCO Enterprise Message Service .NET Reference

 Queue 71
|

Queue
Constructor

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.

Parameter Description
name Find or create a queue with this name.

See Also Session.CreateQueue on page 186

LookupContext on page 215

TIBCO Enterprise Message Service .NET Reference

72
| Chapter 3 Destination

TemporaryQueue
Class

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.

Method Description Page

TemporaryQueue.Delete Delete a temporary queue. 73

See Also Session.CreateTemporaryQueue on page 188

TIBCO Enterprise Message Service .NET Reference

 TemporaryQueue.Delete 73
|

TemporaryQueue.Delete
Method

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

TemporaryTopic
Class

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.

Method Description Page

TemporaryTopic.Delete Delete a temporary topic. 75

See Also Session.CreateTemporaryTopic on page 189

TIBCO Enterprise Message Service .NET Reference

 TemporaryTopic.Delete 75
|

TemporaryTopic.Delete
Method

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

Topic
Class

Declaration class Topic : Destination

Purpose Topics deliver each message to multiple consumers.

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

Subclasses TemporaryTopic on page 74

TIBCO Enterprise Message Service .NET Reference

 Topic 77
|

Topic
Constructor

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.

Parameter Description
name Find or create a topic with this name.

See Also Session.CreateTopic on page 191

LookupContext on page 215

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

MessageConsumer
Class

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
|

Member Description
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.

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

See Also IMessageListener on page 90

EMSMessageHandler on page 87

TIBCO Enterprise Message Service .NET Reference

82
| Chapter 4 Consumer

MessageConsumer.Close
Method

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 83

IMessageListeneron page 90
Session.CreateConsumer on page 180

TIBCO Enterprise Message Service .NET Reference

 MessageConsumer.Receive 83
|

MessageConsumer.Receive
Method

Declaration Message Receive();

Message Receive(
long timeout );

Purpose Receive a message (synchronous).

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.

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.

TIBCO Enterprise Message Service .NET Reference

84
| Chapter 4 Consumer

MessageConsumer.ReceiveNoWait
Method

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
|

QueueReceiver
Class

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

TopicSubscriber
Class

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
|

EMSMessageHandler
Delegate

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).

Parameter Description
sender The MessageConsumer object that raised a message event.

args The event, which contains the message object.

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 80

EMSMessageEventArgs on page 88

TIBCO Enterprise Message Service .NET Reference

88
| Chapter 4 Consumer

EMSMessageEventArgs
Class

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
|

EMSMessageEventArgs
Constructor

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

IMessageListener
Interface

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).

Method Description Page

IMessageListener.OnMessage Process inbound messages (asynchronous). 91

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 80

Session on page 170

TIBCO Enterprise Message Service .NET Reference

 IMessageListener.OnMessage 91
|

IMessageListener.OnMessage
Method

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

MessageProducer
Class

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
|

Member Description
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.

TIBCO Enterprise Message Service .NET Reference

96
| Chapter 5 Producer

Member Description
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.

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.Close
Method

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.Send
Method

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
|

Parameter Description
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.

TIBCO Enterprise Message Service .NET Reference

100
| Chapter 5 Producer

QueueSender
Class

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.Send
Method

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

Parameter Description
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.

See Also MessageProducer.Send on page 98

TIBCO Enterprise Message Service .NET Reference

 TopicPublisher 103
|

TopicPublisher
Class

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.Publish
Method

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
|

Parameter Description
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.

See Also MessageProducer.Send on page 98

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

QueueRequestor
Class

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.

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 111

return it.

See Also Queue on page 70

QueueSession on page 196

TIBCO Enterprise Message Service .NET Reference

 QueueRequestor 109
|

QueueRequestor
Constructor

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.Close
Method

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.Request
Method

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

TopicRequestor
Class

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.

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 115

return it.

See Also Topic on page 76

TopicSession on page 197

TIBCO Enterprise Message Service .NET Reference

 TopicRequestor 113
|

TopicRequestor
Constructor

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.Close
Method

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.Request
Method

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

Connection
Class

Declaration class Connection

Purpose Encapsulate a server connection.

Subclasses QueueConnection on page 126

TopicConnection 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.

Asynchronous When a program uses a connection to send messages, the send calls can detect
Exceptions 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
|

Member Description
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.

TIBCO Enterprise Message Service .NET Reference

120
| Chapter 7 Connection

Member Description
MetaData ConnectionMetaData {get;}

Programs can get the connection’s metadata object.

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.Close
Method

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 25

MessageConsumer on page 80
MessageProducer on page 94
Destination on page 69
Session on page 170
IMessageListener on page 90
IllegalStateException on page 312

TIBCO Enterprise Message Service .NET Reference

122
| Chapter 7 Connection

Connection.CreateSession
Method

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.

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.

See Also Message.Acknowledge on page 25

Session on page 170
Acknowledge Modes on page 174
QueueSession on page 196

TIBCO Enterprise Message Service .NET Reference

 Connection.Start 123
|

Connection.Start
Method

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.Stop
Method

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
|

ConnectionMetaData
Class

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

QueueConnection
Class

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 127
session object.

TIBCO Enterprise Message Service .NET Reference

 QueueConnection.CreateQueueSession 127
|

QueueConnection.CreateQueueSession
Method

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.

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.

See Also Message.Acknowledge on page 25

QueueSession on page 196
Acknowledge Modes on page 174
QueueSession on page 196

TIBCO Enterprise Message Service .NET Reference

128
| Chapter 7 Connection

TopicConnection
Class

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 129
object.

TIBCO Enterprise Message Service .NET Reference

 TopicConnection.CreateTopicSession 129
|

TopicConnection.CreateTopicSession
Method

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.

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.

See Also Message.Acknowledge on page 25

TopicSession on page 197
Acknowledge Modes on page 174
QueueSession on page 196

TIBCO Enterprise Message Service .NET Reference

130
| Chapter 7 Connection

EMSExceptionHandler
Delegate

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).

Parameter Description
sender The problematic connection object.

args The event, which contains the exception object.

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 Connectionon page 118

EMSExceptionHandler on page 130
EMSExceptionEventArgs on page 131

TIBCO Enterprise Message Service .NET Reference

 EMSExceptionEventArgs 131
|

EMSExceptionEventArgs
Class

Declaration class EMSMessageEventArgs : EventArgs

Purpose Present a connection problem as a .NET event.

Remarks EMSExceptionHandler delegates receive this object as an argument.

Member Description
Properties

Exception EMSException {get;}

Programs can get the exception that details the problem.

Method Description Page

EMSMessageEventArgs Constructor. 89

See Also EMSExceptionHandler on page 130

TIBCO Enterprise Message Service .NET Reference

132
| Chapter 7 Connection

EMSExceptionEventArgs
Constructor

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
|

IExceptionListener
Interface

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).

Method Description Page

IExceptionListener.OnException Handle connection exceptions asynchronously. 134

See Also Connection on page 118

EMSExceptionHandler on page 130

TIBCO Enterprise Message Service .NET Reference

134
| Chapter 7 Connection

IExceptionListener.OnException
Method

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

ConnectionFactory
Class

Declaration class ConnectionFactory

Purpose Administered object for creating server connections.

Subclasses QueueConnectionFactory on page 161

TopicConnectionFactory 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 JNDI Administrators define factories in a JNDI repository. Client programs call
Repository 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

Method Description Page

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.

Administered Administered objects let administrators configure EMS behavior at the enterprise
Objects 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

TIBCO Enterprise Message Service .NET Reference

 ConnectionFactory 141
|

ConnectionFactory
Constructor

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.

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.

Reconnect and To enable reconnection behavior and fault tolerance, the serverURL parameter
Fault Tolerance 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

TIBCO Enterprise Message Service .NET Reference

142
| Chapter 8 Connection Factory

ConnectionFactory.Clone
Method

Declaration override object Clone();

Purpose Overrides the cloning process

ConnectionFactory.CreateConnection
Method

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.

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.

See Also Connection on page 118

TIBCO Enterprise Message Service .NET Reference

 ConnectionFactory.GetSSLProxyHost 143
|

ConnectionFactory.GetSSLProxyHost
Method

Declaration string GetSSLProxyHost();

Purpose Get the SSL proxy host from this connection factory.

ConnectionFactory.GetSSLProxyPassword
Method

Declaration string GetSSLProxyPassword();

Purpose Get the SSL proxy password from a connection factory.

ConnectionFactory.GetSSLProxyPort
Method

Declaration int GetSSLProxyPort();

Purpose Get the SSL proxy port from this connection factory.

ConnectionFactory.GetSSLProxyUser
Method

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.SetCertificateStoreType
Method

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.SetClientID
Method

Declaration void SetClientID(string clientID);

Purpose Set the client id.

Parameter Description
clientID Client ID.

Throws EMSException if the specified client id already exists.

TIBCO Enterprise Message Service .NET Reference

146
| Chapter 8 Connection Factory

ConnectionFactory.SetClientTracer
Method

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.SetConnAttemptCount
Method

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.SetConnAttemptDelay
Method

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.SetConnAttemptTimeout
Method

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.SetHostNameVerifier
Method

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.SetMetric
Method

Declaration void SetMetric(int metric);

Purpose Set the load balance metric.

Parameter Description
metric Load balance metric.

Throws EMSException if invalid metric is passed.

TIBCO Enterprise Message Service .NET Reference

152
| Chapter 8 Connection Factory

ConnectionFactory.SetReconnAttemptCount
Method

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.SetReconnAttemptDelay
Method

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.SetReconnAttemptTimeout
Method

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.SetServerUrl
Method

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.

Parameter Description
serverUrl The server URL.

Throws EMSException if the URL is already set or some other error.

TIBCO Enterprise Message Service .NET Reference

156
| Chapter 8 Connection Factory

ConnectionFactory.SetSSLAuthOnly
Method

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.

Parameter Description
authOnly • When true, AUTH_ONLY is enabled.
• When false, (the default) AUTH_ONLY is disabled.

See Also EMSSSL.SetAuthOnly on page 242

EMSSSL.GetAuthOnly on page 241

TIBCO Enterprise Message Service .NET Reference

 ConnectionFactory.SetSSLProxy 157
|

ConnectionFactory.SetSSLProxy
Method

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.

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.

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.

TIBCO Enterprise Message Service .NET Reference

158
| Chapter 8 Connection Factory

ConnectionFactory.SetSSLProxyAuth
Method

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.

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.

Throws EMSException if the protocol of the connection factory's URL is not SSL.

TIBCO Enterprise Message Service .NET Reference

 ConnectionFactory.SetSSLTrace 159
|

ConnectionFactory.SetSSLTrace
Method

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.

Parameter Description
tracing • When true, tracing is enabled.
• When false, (the default) tracing is disabled.

ConnectionFactory.SetTargetHostName
Method

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
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.SetUserName
Method

Declaration void SetUserName(string username);

Purpose Set user name.

Parameter Description
username User name.

ConnectionFactory.SetUserPassword
Method

Declaration void SetUserPassword(string password);

Purpose Set user password.

Parameter Description
password Password.

TIBCO Enterprise Message Service .NET Reference

 QueueConnectionFactory 161
|

QueueConnectionFactory
Class

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 Create a queue connection object. 162

Connection

QueueConnectionFactory.Clone Implementation of ICloneable.Clone. 163

TIBCO Enterprise Message Service .NET Reference

162
| Chapter 8 Connection Factory

QueueConnectionFactory.CreateQueueConnection
Method

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.

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.

See Also QueueConnection on page 126

TIBCO Enterprise Message Service .NET Reference

 QueueConnectionFactory.Clone 163
|

QueueConnectionFactory.Clone
Method

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

TopicConnectionFactory
Class

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 Create a topic connection object. 165

Connection

TopicConnectionFactory.Clone Implementation of ICloneable.Clone. 166

TIBCO Enterprise Message Service .NET Reference

 TopicConnectionFactory.CreateTopicConnection 165
|

TopicConnectionFactory.CreateTopicConnection
Method

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.

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.

See Also TopicConnection on page 128

TIBCO Enterprise Message Service .NET Reference

166
| Chapter 8 Connection Factory

TopicConnectionFactory.Clone
Method

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
|

FactoryLoadBalanceMetric
Class

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.

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).

See Also ConnectionFactory on page 138

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

Session
Class

Declaration class Session

Purpose Main organizing context for message activity.

Subclasses QueueSession on page 196

TopicSession 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.

Associated The same single-thread restriction applies to objects associated with a session—
Objects 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

Member Description
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.

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
|

Method Description Page

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 192

message processing.

Session.Run Obsolete. Do not call. 194

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
|

Field Description
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.

TIBCO Enterprise Message Service .NET Reference

176
| Chapter 9 Session

Session.Close
Method

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.Commit
Method

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 306

TransactionRolledBackException on page 327
IllegalStateException on page 312

TIBCO Enterprise Message Service .NET Reference

178
| Chapter 9 Session

Session.CreateBrowser
Method

Declaration QueueBrowser CreateBrowser(

Queue queue,
string messageSelector );

QueueBrowser CreateBrowser(
Queue queue );

Purpose Create a queue browser.

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.

Throws EMSException on page 306

InvalidDestinationException on page 314
InvalidSelectorException on page 316

See Also Queue on page 70

QueueBrowser on page 202

TIBCO Enterprise Message Service .NET Reference

 Session.CreateBytesMessage 179
|

Session.CreateBytesMessage
Method

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.CreateConsumer
Method

Declaration MessageConsumer CreateConsumer(

Destination dest,
string messageSelector,
bool noLocal );

MessageConsumer CreateConsumer(
Destination dest,
string messageSelector );

MessageConsumer CreateConsumer(
Destination dest );

Purpose Create a message consumer.

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.

Throws EMSExceptionon page 306

IllegalStateException on page 312
InvalidDestinationException on page 314
InvalidSelectorException on page 316

See Also Destination on page 69

TIBCO Enterprise Message Service .NET Reference

 Session.CreateDurableSubscriber 181
|

Session.CreateDurableSubscriber
Method

Declaration TopicSubscriber CreateDurableSubscriber(

Topic topic,
string name,
string messageSelector,
bool noLocal );

TopicSubscriber CreateDurableSubscriber(
Topic topic,
string name );

Purpose Create a durable topic subscriber.

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.

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.

Subscription Continuity across inactive periods uses two data items from the client:
Continuity
• Subscription Name a parameter of this method
• Client ID an optional property of the Connection (used only when supplied)

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.

Matching • If the Connection’s client ID is non-null when a session creates a durable

Client ID 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 Topic Notice that the server does not use the topic and message selector arguments to
or Selector 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 EMSExceptionon page 306

IllegalStateException on page 312
InvalidDestinationException on page 314
InvalidSelectorException on page 316

See Also Topic on page 76

Connection on page 118

TIBCO Enterprise Message Service .NET Reference

 Session.CreateMapMessage 183
|

Session.CreateMapMessage
Method

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.CreateObjectMessage
Method

Declaration ObjectMessage CreateObjectMessage(

object obj );

ObjectMessage CreateObjectMessage();

Purpose Create an object message.

Parameter Description
obj When present, use this object as data in the new message.

See Also ObjectMessage on page 48

TIBCO Enterprise Message Service .NET Reference

 Session.CreateProducer 185
|

Session.CreateProducer
Method

Declaration MessageProducer CreateProducer(

Destination dest );

Purpose Create a message producer.

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.

Throws EMSException on page 306

InvalidDestinationException on page 314

See Also MessageProducer on page 94

TIBCO Enterprise Message Service .NET Reference

186
| Chapter 9 Session

Session.CreateQueue
Method

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.

Parameter Description
queueName Get or create the queue with this name.

See Also Queue on page 70

TIBCO Enterprise Message Service .NET Reference

 Session.CreateStreamMessage 187
|

Session.CreateStreamMessage
Method

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.CreateTemporaryQueue
Method

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.CreateTemporaryTopic
Method

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.CreateTextMessage
Method

Declaration TextMessage CreateTextMessage(

string text);

TextMessage CreateTextMessage();

Purpose Create a text message.

Parameter Description
text When present, use this string as data in the new message.

See Also TextMessage on page 58

TIBCO Enterprise Message Service .NET Reference

 Session.CreateTopic 191
|

Session.CreateTopic
Method

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.

Parameter Description
topicName Get or create the topic with this name.

See Also Topic on page 76

TIBCO Enterprise Message Service .NET Reference

192
| Chapter 9 Session

Session.Recover
Method

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 306

IllegalStateException on page 312

TIBCO Enterprise Message Service .NET Reference

 Session.Rollback 193
|

Session.Rollback
Method

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 306

IllegalStateException on page 312

TIBCO Enterprise Message Service .NET Reference

194
| Chapter 9 Session

Session.Run
Method

Declaration void Run();

Purpose Obsolete. Do not call.

TIBCO Enterprise Message Service .NET Reference

 Session.Unsubscribe 195
|

Session.Unsubscribe
Method

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.

Parameter Description
name This name lets the server locate the subscription.

Throws EMSExceptionon page 306

IllegalStateException on page 312
InvalidDestinationException on page 314

See Also MessageConsumer on page 80

TopicSubscriber on page 86
Topic on page 76
Session.CreateDurableSubscriber on page 181

TIBCO Enterprise Message Service .NET Reference

196
| Chapter 9 Session

QueueSession
Class

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
|

TopicSession
Class

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

SessionMode
Enumeration

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
|

Members Description
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.

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

QueueBrowser
Class

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
|

Method Description Page

QueueBrowser.GetEnumerator Get an enumerator of messages in the queue. 205

QueueBrowser.MoveNext Advance the browser’s enumeration to the next 206

message.

QueueBrowser.Reset Reset the browser to the location before the first 207
message.

See Also Session.CreateBrowser on page 178

TIBCO Enterprise Message Service .NET Reference

204
| Chapter 10 Queue Browser

QueueBrowser.Close
Method

Declaration void Close();

Purpose Close the browser; reclaim resources.

TIBCO Enterprise Message Service .NET Reference

 QueueBrowser.GetEnumerator 205
|

QueueBrowser.GetEnumerator
Method

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.MoveNext
Method

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.Reset
Method

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

ILookupContext
Interface

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.

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 212

TIBCO EMS Naming server.

ILookupContext.RemoveSettings Remove a lookup context setting by name. 214

Requirements Namespace: TIBCO.EMS

Assembly: TIBCO.EMS (in TIBCO.EMS.dll)

TIBCO Enterprise Message Service .NET Reference

 ILookupContext.AddSettings 211
|

ILookupContext.AddSettings
Method

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.

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.

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");

TIBCO Enterprise Message Service .NET Reference

212
| Chapter 11 Name Server Lookup

ILookupContext.Lookup
Method

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.

Parameter Description
name Name of the object to lookup.

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");

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.RemoveSettings
Method

Declaration object RemoveSettings(string propName);

Purpose Remove a lookup context setting by name.

Parameter Description
propName Name of the property to be removed from the lookup context.

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);

TIBCO Enterprise Message Service .NET Reference

 LookupContext 215
|

LookupContext
Class

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

Member Description
URL_SEPARATOR string

Syntactic separator between URLs in the PROVIDER_URL.

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
|

LookupContext
Constructor

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.AddSettings
Method

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.Lookup
Method

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.

Parameter Description
name Lookup this name.

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 308

NamingExceptionon page 322
ServiceUnavailableException on page 325

TIBCO Enterprise Message Service .NET Reference

220
| Chapter 11 Name Server Lookup

LookupContext.RemoveSettings
Method

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
|

LookupContextFactory
Class

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 222

administered objects

TIBCO Enterprise Message Service .NET Reference

222
| Chapter 11 Name Server Lookup

LookupContextFactory
Constructor

Declaration LookupContextFactory();

Purpose Create a lookup context factory.

LookupContextFactory.CreateContext
Method

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.

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.

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(

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

LdapLookupConsts
Class

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
|

Member Description
LDAP_SSL_PARAMS Specifies the other ssl parameters, namely
QueryClientCertificateCallback and
VerifyServerCertificateCallback.

TIBCO Enterprise Message Service .NET Reference

226
| Chapter 11 Name Server Lookup

LdapLookupContext
Class

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 228

name in an LDAP server.

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.

Lookup of XA connection factories is not supported.

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

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

Parameter Description
propName Remove this property.
For property names, see LdapLookupConsts on page 224.

Throws ArgumentException if the property name is null.

TIBCO Enterprise Message Service .NET Reference

 LdapLookupSSLParams 231
|

LdapLookupSSLParams
Class

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.

Method Description Page

LdapLookupSSLParams Create a LDAP lookup SSL Parameters object. 231

LdapLookupSSLParams.SetSSLQueryCl Set the query client certificate callback to be 232

ientCertificateCallback invoked during the SSL handshake with the
LDAP server.

LdapLookupSSLParams.SetSSLVerifyS Set the server certificate verify callback to be 232

erverCertificateCallback invoked during the SSL handshake with the
ldap server.

LdapLookupSSLParams
Constructor

Declaration LdapLookupSSLParams();

Purpose Create a LDAP lookup SSL Parameters object.

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.

Parameter Description
callback The query client certificate callback.

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 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

EMSSSL
Class

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
|

Member Description
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

TIBCO Enterprise Message Service .NET Reference

240
| Chapter 12 SSL Support

Member Description
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".

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 241
null if client tracing is disabled.

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 242

side.

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.GetAuthOnly
Method

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.GetClientTracer
Method

Declaration static StreamWriter GetClientTracer();

Purpose Returns the output target for the client tracer, or null if client tracing is disabled.

EMSSSL.GetHostNameVerifier
Method

Declaration static EMSSSLHostNameVerifier GetHostNameVerifier();

Purpose Returns currently set custom host name verifier.

Remarks Returns null if custom host name verifier is not set.

EMSSSL.GetTargetHostName
Method

Declaration static string GetTargetHostName();

Purpose Returns the name set target host name.

TIBCO Enterprise Message Service .NET Reference

242
| Chapter 12 SSL Support

EMSSSL.Initialize
Method

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.SetAuthOnly
Method

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.

Parameter Description
flag True = enabled.
False = disabled.

See Also EMSSSL.GetAuthOnly on page 241

ConnectionFactory.SetSSLAuthOnly on page 156

TIBCO Enterprise Message Service .NET Reference

 EMSSSL.SetCertificateStoreType 243
|

EMSSSL.SetCertificateStoreType
Method

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.SetClientTracer
Method

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.

Parameter Description
tracer The output stream to send the tracing information. Specify null as parameter
to disable client tracing.

EMSSSL.SetHostNameVerifier
Method

Declaration static 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

 EMSSSL.SetTargetHostName 245
|

EMSSSL.SetTargetHostName
Method

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

EMSSSLFileStoreInfo
Class

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.

Method Description Page

EMSSSLFileStoreInfo Create a new File Store Info 247
object.

EMSSSLFileStoreInfo.ClearTrustedCerts Remove all previously set 247

trusted certificates.

EMSSSLFileStoreInfo.SetSSLClientIdentity Set the client identity. 248

EMSSSLFileStoreInfo.SetSSLPassword Set private key password. 249

EMSSSLFileStoreInfo.SetSSLTrustedCertificate Add a certificate to the list of 250

trusted certificates.

Requirements Namespace: TIBCO.EMS

Assembly: TIBCO.EMS (in TIBCO.EMS.dll)

TIBCO Enterprise Message Service .NET Reference

 EMSSSLFileStoreInfo 247
|

EMSSSLFileStoreInfo
Constructor

Declaration EMSSSLFileStoreInfo();

Purpose Create a new File Store Info object

EMSSSLFileStoreInfo.ClearTrustedCerts
Method

Declaration void ClearTrustedCerts();

Purpose Remove all previously set trusted certificates.

TIBCO Enterprise Message Service .NET Reference

248
| Chapter 12 SSL Support

EMSSSLFileStoreInfo.SetSSLClientIdentity
Method

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.SetSSLPassword
Method

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.SetSSLTrustedCertificate
Method

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
|

EMSSSLSystemStoreInfo
Class

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 252
system store info.

EMSSSLSystemStoreInfo.SetCertificateName Set the name of the 253

certificate.

EMSSSLSystemStoreInfo.SetCertificateStoreLocation Set location of the certificate 254

store.

EMSSSLSystemStoreInfo.SetCertificateStoreName Set the certificate store name. 254

TIBCO Enterprise Message Service .NET Reference

252
| Chapter 12 SSL Support

EMSSSLSystemStoreInfo
Constructor

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.SetCertificateName
Method

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.

While searching for the certificate in the certificate store the tag 'CN' is
automatically prepended to the certificate name.

Parameter Description
certName Certificate name.

Throws ArgumentException if the certificate name is null.

See Also EMSSSLSystemStoreInfo.SetCertificateStoreName on page 254

EMSSSLSystemStoreInfo.SetCertificateStoreLocation on page 254

TIBCO Enterprise Message Service .NET Reference

254
| Chapter 12 SSL Support

EMSSSLSystemStoreInfo.SetCertificateStoreLocation
Method

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.

Parameter Description
storeLocation Location in which to lookup certificate by name. For example, "CurrentUser"
or "LocalMachine."

EMSSSLSystemStoreInfo.SetCertificateStoreName
Method

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.

Parameter Description
storeName Name of the certificate store.

Throws ArgumentException if the store name is null.

TIBCO Enterprise Message Service .NET Reference

 EMSSSLHostNameVerifier 255
|

EMSSSLHostNameVerifier
Delegate

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.

Parameter Description
sender The source of the event.

args The event argument, EMSSSLHostNameVerifierArgs.

Requirements Namespace: TIBCO.EMS

Assembly: TIBCO.EMS (in TIBCO.EMS.dll)

TIBCO Enterprise Message Service .NET Reference

256
| Chapter 12 SSL Support

EMSSSLHostNameVerifierArgs
Class

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
|

EMSSSLStoreType
Enumeration

Declaration enum EMSSSLStoreType;

Purpose Certificate Store Type to be used for reading SSL Certificates.

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.

Requirements Namespace: TIBCO.EMS

Assembly: TIBCO.EMS (in TIBCO.EMS.dll)

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

DeliveryMode
Class

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
|

IEMSSerialziable
Interface

Declaration interface IEMSSerialzable

Purpose Customize serialization and deserialization of objects.

.NET Compact This interface is available only in .NET Compact Framework. Programmers can
Framework 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.

Method Description Page

IEMSSerialziable.Deserialize Deserialize a data stream to reconstruct an object. 262

IEMSSerialziable.Serialize Serialize an object. 263

See Also ObjectMessage on page 48

TIBCO Enterprise Message Service .NET Reference

262
| Chapter 13 Utilities

IEMSSerialziable.Deserialize
Method

Declaration void Deserialize(

System.IO.Stream stream );

Purpose Deserialize a data stream to reconstruct an object.

Parameter Description
stream Deserialize the data from this 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.

TIBCO Enterprise Message Service .NET Reference

 IEMSSerialziable.Serialize 263
|

IEMSSerialziable.Serialize
Method

Declaration void Serialize(

System.IO.Stream stream );

Purpose Serialize an object.

Parameter Description
stream Serialize the object’s data to this stream.

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.

TIBCO Enterprise Message Service .NET Reference

264
| Chapter 13 Utilities

MessageDeliveryMode
Enumeration

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
|

Tibems
Class

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

Constant Description
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.

TIBCO Enterprise Message Service .NET Reference

 Tibems 267
|

Constant Description
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.

Method Description Page

Tibems.CalculateMessageSize Returns the total size (in bytes) of a message in 270
wire format.

Tibems.CreateFromBytes Create a message from a byte array. 271

Tibems.GetAllowCloseInCallback Determine whether client callbacks may call 272

close methods.

Tibems.GetAsBytes Copy a message into a byte array. 273

TIBCO Enterprise Message Service .NET Reference

268
| Chapter 13 Utilities

Method Description Page

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 276
specified connection.

Tibems.GetEncoding Return the global character encoding for 277

messages.

Tibems.GetExceptionOnFTSwitch Return the fault tolerance exception setting. 278

Tibems.GetMessageEncoding Return the character encoding for an 279

individual message.

Tibems.GetMessageSize Return the size of a wire format message—or 280

(and related methods) its body, header or properties portions.

Tibems.GetPingInterval Return the interval at which the client tests 281

network connectivity.

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 290

may call close methods.

Tibems.SetConnectAttempts Modify the connection attempts setting. 291

Tibems.SetConnectAttemptTimeout Set the maximum amount of time a client will 292

wait for the connection to be established.

Tibems.SetEncoding Set the global string encoding for messages. 293

TIBCO Enterprise Message Service .NET Reference

 Tibems 269
|

Method Description Page

Tibems.SetExceptionOnFTSwitch Modify the fault tolerance exception setting. 294

Tibems.SetMessageEncoding Set the character encoding for an individual 295

message.

Tibems.SetPingInterval Set the interval at which the client tests 296

network connectivity.

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 300

wait for the reconnect to complete.

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

TIBCO Enterprise Message Service .NET Reference

270
| Chapter 13 Utilities

Tibems.CalculateMessageSize
Method

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.

Parameter Description
msg Compute the size of this message.

See Also Tibems.GetMessageSize on page 280

TIBCO Enterprise Message Service .NET Reference

 Tibems.CreateFromBytes 271
|

Tibems.CreateFromBytes
Method

Declaration static Message CreateFromBytes(

byte[] bytes );

Purpose Create a message from a byte array.

Parameter Description
bytes Fill the new message with this byte array.
This byte array must be the result of previously calling
Tibems.GetAsBytes.

Remarks The newly created message is read-only; to enable modification without erasing
the content, call Tibems.MakeWriteable.

See Also Tibems.GetAsBytes on page 273

Tibems.MakeWriteable on page 289

TIBCO Enterprise Message Service .NET Reference

272
| Chapter 13 Utilities

Tibems.GetAllowCloseInCallback
Method

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).

This method replaces the deprecated method GetAllowCallbackInClose.

See Also Tibems.SetAllowCloseInCallback on page 290

TIBCO Enterprise Message Service .NET Reference

 Tibems.GetAsBytes 273
|

Tibems.GetAsBytes
Method

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.

Parameter Description
message Fill the byte array with the content of this message.

See Also Tibems.CreateFromBytes on page 271

TIBCO Enterprise Message Service .NET Reference

274
| Chapter 13 Utilities

Tibems.GetConnectAttempts
Method

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.GetConnectAttemptTimeout
Method

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.GetConnectionActiveURL
Method

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.GetEncoding
Method

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 34

BytesMessage.Write on page 37
Tibems.SetEncoding on page 293
Tibems.GetMessageEncoding on page 279
Tibems.SetMessageEncoding on page 295

TIBCO Enterprise Message Service .NET Reference

278
| Chapter 13 Utilities

Tibems.GetExceptionOnFTSwitch
Method

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 133

Tibems.SetExceptionOnFTSwitch on page 294

TIBCO Enterprise Message Service .NET Reference

 Tibems.GetMessageEncoding 279
|

Tibems.GetMessageEncoding
Method

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.

Parameter Description
message Get the encoding for this message.

See Also BytesMessage.Read on page 34

BytesMessage.Write on page 37
Tibems.GetEncoding on page 277
Tibems.SetEncoding on page 293
Tibems.SetMessageEncoding on page 295

TIBCO Enterprise Message Service .NET Reference

280
| Chapter 13 Utilities

Tibems.GetMessageSize
Method

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.

Parameter Description
msg Return the cached size of this message, or one of its parts.

See Also Tibems.CalculateMessageSize on page 270

TIBCO Enterprise Message Service .NET Reference

 Tibems.GetPingInterval 281
|

Tibems.GetPingInterval
Method

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.GetProperty
Method

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
|

Property Constant Corresponding Methods

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

See Also Tibems.SetProperty on page 297

TIBCO Enterprise Message Service .NET Reference

284
| Chapter 13 Utilities

Tibems.GetReconnectAttempts
Method

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.GetReconnectAttemptTimeout
Method

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.GetSessionDispatcherDaemon
Method

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 Compact The .NET Compact Framework does not support daemon threads. This call
Framework always returns false.

See Also Tibems.SetSessionDispatcherDaemon on page 301

TIBCO Enterprise Message Service .NET Reference

 Tibems.GetSocketReceiveBufferSize 287
|

Tibems.GetSocketReceiveBufferSize
Method

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.GetSocketSendBufferSize
Method

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.MakeWriteable
Method

Declaration static void MakeWriteable(

Message message);

Purpose Make a message writable.

Parameter Description
message Make this message writable.

See Also MessageNotWriteableException on page 320

TIBCO Enterprise Message Service .NET Reference

290
| Chapter 13 Utilities

Tibems.SetAllowCloseInCallback
Method

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).

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.

See Also Tibems.GetAllowCloseInCallback on page 272

TIBCO Enterprise Message Service .NET Reference

 Tibems.SetConnectAttempts 291
|

Tibems.SetConnectAttempts
Method

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.

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.

See Also Tibems.GetConnectAttempts on page 274

TIBCO Enterprise Message Service .NET Reference

292
| Chapter 13 Utilities

Tibems.SetConnectAttemptTimeout
Method

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.

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).

See Also Tibems.SetReconnectAttemptTimeout on page 300

Tibems.GetConnectAttemptTimeout on page 275
Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO
Enterprise Message Service User’s Guide

TIBCO Enterprise Message Service .NET Reference

 Tibems.SetEncoding 293
|

Tibems.SetEncoding
Method

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.

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.

See Also BytesMessage.Read on page 34

BytesMessage.Write on page 37
Tibems.GetEncoding on page 277
Tibems.GetMessageEncoding on page 279
Tibems.SetMessageEncoding on page 295

TIBCO Enterprise Message Service .NET Reference

294
| Chapter 13 Utilities

Tibems.SetExceptionOnFTSwitch
Method

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).

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.

See Also IExceptionListener on page 133

Tibems.GetExceptionOnFTSwitch on page 278

TIBCO Enterprise Message Service .NET Reference

 Tibems.SetMessageEncoding 295
|

Tibems.SetMessageEncoding
Method

Declaration static void SetMessageEncoding(

Message message
string 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.

Parameter Description
message Set the encoding for this message.

encodingName Set this encoding.

For a list of standard encoding names, see www.iana.org.

See Also BytesMessage.Read on page 34

BytesMessage.Write on page 37
Tibems.GetEncoding on page 277
Tibems.SetEncoding on page 293
Tibems.GetMessageEncoding on page 279

TIBCO Enterprise Message Service .NET Reference

296
| Chapter 13 Utilities

Tibems.SetPingInterval
Method

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.

Parameter Description
seconds Ping at this interval (in seconds).
Zero is a special value that disables ping testing.

See Also Tibems.GetPingInterval on page 281

TIBCO Enterprise Message Service .NET Reference

 Tibems.SetProperty 297
|

Tibems.SetProperty
Method

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

Property Constant Corresponding Methods

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

See Also Tibems.GetProperty on page 282

TIBCO Enterprise Message Service .NET Reference

 Tibems.SetReconnectAttempts 299
|

Tibems.SetReconnectAttempts
Method

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.

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.

See Also Tibems.GetReconnectAttempts on page 284

TIBCO Enterprise Message Service .NET Reference

300
| Chapter 13 Utilities

Tibems.SetReconnectAttemptTimeout
Method

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.

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).

See Also Tibems.SetConnectAttemptTimeout on page 292

Tibems.GetReconnectAttemptTimeout on page 285

Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service

User’s Guide.

TIBCO Enterprise Message Service .NET Reference

 Tibems.SetSessionDispatcherDaemon 301
|

Tibems.SetSessionDispatcherDaemon
Method

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.

Parameter Description
makeDaemon • When true, dispatcher threads are daemon threads.
• When false, (the default) they are not daemon threads

.NET Compact The .NET Compact Framework does not support daemon threads. This call has
Framework no effect, and returns without error.

See Also Tibems.GetSessionDispatcherDaemon on page 286

TIBCO Enterprise Message Service .NET Reference

302
| Chapter 13 Utilities

Tibems.SetSocketReceiveBufferSize
Method

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.

Parameter Description
size Sockets use receive buffers of this size (in kilobytes).

.NET Compact The .NET Compact Framework does not permit changing the default socket
Framework buffer size. This call has no effect, and returns without error.

See Also Tibems.GetSocketReceiveBufferSize on page 287

TIBCO Enterprise Message Service .NET Reference

 Tibems.SetSocketSendBufferSize 303
|

Tibems.SetSocketSendBufferSize
Method

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.

Parameter Description
size Sockets use send buffers of this size (in kilobytes).

.NET Compact The .NET Compact Framework does not permit changing the default socket
Framework buffer size. This call has no effect, and returns without error.

See Also Tibems.GetSocketSendBufferSize on page 288

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

EMSException
Class

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.

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.

Subclasses EMSException
IllegalStateException
InvalidClientIDException
InvalidDestinationException
InvalidSelectorException
MessageEOFException
MessageFormatException
MessageNotReadableException
MessageNotWriteableException
NamingException
AuthenticationException
CannotProceedException
CommunicationException
ConfigurationException
InvalidNameException
NameNotFoundException
ServiceUnavailableException
ResourceAllocationException
SecurityException
TransactionInProgressException
TransactionRolledBackException

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

AuthenticationException
Class

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
|

CannotProceedException
Class

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

CommunicationException
Class

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
|

ConfigurationException
Class

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

IllegalStateException
Class

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
|

InvalidClientIDException
Class

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

InvalidDestinationException
Class

Declaration class InvalidDestinationException : EMSException

Purpose tibemsd cannot locate the destination.

Origin JMS.

TIBCO Enterprise Message Service .NET Reference

 InvalidNameException 315
|

InvalidNameException
Class

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

InvalidSelectorException
Class

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
|

MessageEOFException
Class

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

MessageFormatException
Class

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
|

MessageNotReadableException
Class

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

MessageNotWriteableException
Class

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
|

NameNotFoundException
Class

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

NamingException
Class

Declaration class NamingException : EMSException

Purpose Root of exceptions related to name lookup requests.

Member Description
Properties

RootCause System.Exception {get; set;}

When a naming exception results from a more general problem, this

exception details that problem.

Remarks Members of LookupContext throw instances of this class and its subclasses.

Subclasses NamingException
AuthenticationException
CannotProceedException
CommunicationException
ConfigurationException
InvalidNameException
NameNotFoundException
ServiceUnavailableException

See Also LookupContext on page 215

TIBCO Enterprise Message Service .NET Reference

 ResourceAllocationException 323
|

ResourceAllocationException
Class

Declaration class ResourceAllocationException : EMSException

Purpose Required resources are not available.

Origin JMS.

TIBCO Enterprise Message Service .NET Reference

324
| Chapter 14 Exception

SecurityException
Class

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
|

ServiceUnavailableException
Class

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

TransactionInProgressException
Class

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
|

TransactionRolledBackException
Class

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 compression 3
ConfigurationException 311
Acknowledge 25 Connection 118
AuthenticationException 308 Close 121
CreateSession 122
Start 123
Stop 124
B ConnectionConsumer (not supported) 3
ConnectionFactory 138
body types, message 9 constructor 141
BodyLength 32 CreateConnection 142
BytesMessage 32 ConnectionMetaData 125
Read methods 34 conversion, data type 21
ReadBytes 36 CreateBrowser 178
Reset 40 CreateBytesMessage 179
Write methods 37 CreateConnection 142
WriteBytes 39 CreateConsumer 180
CreateDurableSubscriber 181
CreateFromBytes 271
CreateMapMessage 183
C CreateObjectMessage 184
CreateProducer 185
CalculateMessageSize 270 CreateQueue 186
CannotProceedException 309 CreateQueueConnection 162
character encoding 4, 277, 279, 293, 295 CreateQueueSession 127
ClearBody 26 CreateSession 122
ClearProperties 26 CreateStreamMessage 187
Clone 26 CreateTemporaryQueue 188
Close CreateTemporaryTopic 189
Connection 121 CreateTextMessage 190
MessageConsumer 82 CreateTopic 191
MessageProducer 97 CreateTopicConnection 165
QueueBrowser 204 CreateTopicSession 129
QueueRequestor 110 customer support xvii
Session 176
TopicRequestor 114
Commit 177
CommunicationException 310
Compact Framework 5

TIBCO Enterprise Message Service .NET Reference

330
| Index

D G
daemon threads 3 Get
data type conversion 21 MapMessage 44
Delete message properties 28
TemporaryQueue 73 GetAllowCloseInCallback 272
TemporaryTopic 75 GetAsBytes 273
DeliveryMode 260 GetConnectAttempts 274
Deserialize 262 GetConnectAttemptTimeout 275
Destination 69 GetDeliveryModeName 27
overview 66 GetEncoding 277
durable subscription GetEnumerator 205
unsubscribe 195 GetExceptionOnFTSwitch 278
dynamic destination 66 GetMessageBodySize 280
GetMessageEncoding 279
GetMessageHeadersSize 280
GetMessageSize 280
E GetPingInterval 281
GetProperty, Tibems 282
EMSException 306 GetReconnectAttempts 284
EMSExceptionEventArgs 131 GetReconnectAttemptTimeout 285
constructor 132 GetSessionDispatcherDaemon 286
EMSExceptionHandler 130 GetSocketReceiveBufferSize 287
EMSMessageEventArgs 88 GetSocketSendBufferSize 288
constructor 89
Message 88
EMSMessageHandler 87
encoding, character 4, 277, 279, 293, 295 H
exceptions 305
headers, message 10

F
I
FactoryLoadBalanceMetric 167
fault tolerance IEMSSerialziable 261
ActiveURL 119 Deserialize 262
failover exceptions 278, 294 Serialize 263
FieldCount IExceptionListener 133
MapMessage 41 OnException 134
StreamMessage 50 IllegalStateException 312
IMessageListener 90
OnMessage 91
InvalidClientIDException 313
InvalidDestinationException 314

TIBCO Enterprise Message Service .NET Reference

 Index 331
|
InvalidNameException 315 message
InvalidSelectorException 316 selectors 18
ItemExists 45 MessageConsumer 80
Close 82
MessageHandler 80
MessageListener 80
L MessageSelector 81
Receive 83
Lookup 219 ReceiveNoWait 84
LookupContext 210, 215 MessageDeliveryMode 264
AddSettings MessageEOFException 317
AddSettings 218 MessageFormatException 318
constructor 217 MessageHandler 80
Lookup 219 MessageListener 80
RemoveSettings 220 MessageNotReadableException 319
MessageNotWriteableException 320
MessageProducer 94
Close 97
M Send 98
MessageProducer.Close 97
MakeWriteable 289 MessageProducer.Send 98
MapMessage 41 MessageSelector 81
FieldCount 41 MoveNext 206
Get methods 44
ItemExists 45
MapNames 41
set methods 46 N
SetBytes 47
MapNames 41 NameNotFoundException 321
Message 22 NamingException 322
Acknowledge 25 .NET Compact Framework 5
body types 9 NoLocal 86
BodyLength 32
ClearBody 26
ClearProperties 26
Clone 26 O
EMSMessageEventArgs 88
get property methods 28 object serialization 3
GetDeliveryModeName 27 ObjectMessage 48
headers 10 constructor 49
parts of 8 TheObject 48
properties 15 OnException 134
PropertyExists 29 OnMessage 91
set property methods 30
ToString 31

TIBCO Enterprise Message Service .NET Reference

332
| Index

P ReadBytes
BytesMessage 36
property, message 15 StreamMessage 54
get 28 read-only 26, 40, 55, 271, 320
set 30 Receive 83
PropertyExists 29 ReceiveNoWait 84
Publish 104 Recover 192
RemoveSettings 220
Request
QueueRequestor 111
Q TopicRequestor 115
request 10
Queue 70 Reset
constructor 71 BytesMessage 40
QueueName 70 QueueBrowser 207
QueueReceiver 85 StreamMessage 55
QueueBrowser 202 ResourceAllocationException 323
Close 204 Rollback 193
GetEnumerator 205 Run (obsolete) 194
MoveNext 206
Reset 207
QueueConnection 126
CreateQueueSession 127 S
QueueConnectionFactory 161
CreateQueueConnection 162 SecurityException 324
QueueName 70 selectors, message 18
QueueReceiver 85 Send
Queue 85 MessageProducer 98
QueueRequestor 108 QueueSender 101
Close 110 serializable object interface 261
constructor 109 serialization 3
Request 111 Serialize 263
QueueSender 100 ServerSession (not supported) 3
Send 101 ServerSessionPool (not supported) 3
QueueSender.Send 101 ServiceUnavailableException 325
QueueSession 196

R
Read
BytesMessage 34
StreamMethod 53

TIBCO Enterprise Message Service .NET Reference

 Index 333
|
Session 170 StreamMessage 50
Close 176 FieldCount 50
Commit 177 Read methods 53
CreateBrowser 178 ReadBytes 54
CreateBytesMessage 179 Reset 55
CreateConsumer 180 Write methods 56
CreateDurableSubscriber 181 WriteBytes 57
CreateMapMessage 183 string and character encoding 4
CreateObjectMessage 184 support, contacting xvii
CreateProducer 185
CreateQueue 186
CreateStreamMessage 187
CreateTemporaryQueue 188 T
CreateTemporaryTopic 189
CreateTextMessage 190 technical support xvii
CreateTopic 191 temporary destination 66
Recover 192 TemporaryQueue 72
Rollback 193 Delete 73
Run (obsolete) 194 TemporaryTopic 74
Unsubscribe 195 Delete 75
SessionMode 198 Text 58
Set TextMessage 58
MapMessage 46 constructor 59
message property 30 Text 58
SetAllowCloseInCallback 290 TheObject 48
SetBytes 47
SetConnectAttempts 291
SetConnectAttemptTimeout 292
SetEncoding 293
SetExceptionOnFTSwitch 294
SetMessageEncoding 295
SetPingInterval 296
SetProperty, Tibems 297
SetReconnectAttempts 299
SetReconnectAttemptTimeout 300
SetSessionDispatcherDaemon 301
SetSocketReceiveBufferSize 302
SetSocketSendBufferSize 303
SSL 3
Start 123
static destination 66
Stop 124

TIBCO Enterprise Message Service .NET Reference

334
| Index
Tibems 265 TopicPublisher 103
CalculateMessageSize 270 Publish 104
CreateFromBytes 271 TopicPublisher.Publish 104
GetAllowCloseInCallback 272 TopicRequestor 112
GetAsBytes 273 Close 114
GetConnectAttempts 274 constructor 113
GetConnectAttemptTimeout 275 Request 115
GetEncoding 277 TopicSession 197
GetExceptionOnFTSwitch 278 TopicSubscriber 86
GetMessageBodySize 280 NoLocal 86
GetMessageEncoding 279 Topic 86
GetMessageHeadersSize 280 ToString 31
GetMessageSize 280 TransactionInProgressException 326
GetPingInterval 281 TransactionRolledBackException 327
GetProperty 282 translation, character encoding 4
GetReconnectAttempts 284 type conversion 21
GetReconnectAttemptTimeout 285
GetSessionDispatcherDaemon 286
GetSocketReceiveBufferSize 287
GetSocketSendBufferSize 288 U
MakeWriteable 289
SetAllowCloseInCallback 290 Unicode 4
SetConnectAttempts 291 Unsubscribe 195
SetConnectAttemptTimeout 292
SetEncoding 293
SetExceptionOnFTSwitch 294
SetMessageEncoding 295 W
SetPingInterval 296
SetProperty 297 Write
SetReconnectAttempts 299 BytesMessage 37
SetReconnectAttemptTimeout 300 StreamMessage 56
SetSessionDispatcherDaemon 301 WriteBytes
SetSocketReceiveBufferSize 302 BytesMessage 39
SetSocketSendBufferSize 303 StreamMessage 57
tibemsd 138, 209
Topic 76
constructor 77
TopicName 76 X
TopicSubscriber 86
TopicConnection 128 XA (not supported) 3
CreateTopicSession 129
TopicConnectionFactory 164
CreateTopicConnection 165
TopicName 76

TIBCO Enterprise Message Service .NET Reference