Tib Ems Dotnet Ref

TIBCO Enterprise Message Service™

.NET ReferenceSoftware Release 4.4November 2006

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE TIBCO Enterprise Message Service User’s Guide). USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIB, TIBCO, Information Bus, The Power of Now, TIBCO Adapter, Rendezvous are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

EJB, J2EE, JMS and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. PLEASE SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2001–2006 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

| iii

Contents

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivTIBCO Enterprise Message Service Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivThird Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Excluded Features and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Object Serialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Strings and Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

.NET Compact Framework (CF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Parts of a Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Body Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Setting Message Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15EMS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15JMS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Message Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Data Type Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Message.Acknowledge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Message.ClearBody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Message.ClearProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Message.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Message.GetDeliveryModeName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Message.Get Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

TIBCO Enterprise Message Service .NET Reference

iv | Contents

Message.PropertyExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Message.Set Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Message.ToString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33BytesMessage.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34BytesMessage.ReadBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36BytesMessage.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37BytesMessage.WriteBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39BytesMessage.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43MapMessage.Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44MapMessage.ItemExists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45MapMessage.Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46MapMessage.SetBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50StreamMessage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52StreamMessage.Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53StreamMessage.ReadBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54StreamMessage.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55StreamMessage.Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56StreamMessage.WriteBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59TextMessage.ClearBody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59TextMessage.Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Message.EmptyEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Message.EmptyEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Message.EmptyEnum.MoveNext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Message.EmptyEnum.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 3 Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Destination Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

TemporaryQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72TemporaryQueue.Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

TemporaryTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74


Contents | v

TemporaryTopic.Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 4 Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80MessageConsumer.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82MessageConsumer.Receive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83MessageConsumer.ReceiveNoWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

QueueReceiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

TopicSubscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

EMSMessageHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

EMSMessageEventArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88EMSMessageEventArgs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

IMessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90IMessageListener.OnMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Chapter 5 Producer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94MessageProducer.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97MessageProducer.Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

QueueSender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100QueueSender.Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

TopicPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103TopicPublisher.Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

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

QueueRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108QueueRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109QueueRequestor.Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110QueueRequestor.Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

TopicRequestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112TopicRequestor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113TopicRequestor.Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114TopicRequestor.Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

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

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


vi | Contents

Connection.Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Connection.Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

QueueConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126QueueConnection.CreateQueueSession. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

TopicConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128TopicConnection.CreateTopicSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

EMSExceptionHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

EMSExceptionEventArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131EMSExceptionEventArgs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

IExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133IExceptionListener.OnException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

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

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

QueueConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161


Contents | vii

QueueConnectionFactory.CreateQueueConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162QueueConnectionFactory.Clone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

TopicConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164TopicConnectionFactory.CreateTopicConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165TopicConnectionFactory.Clone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

FactoryLoadBalanceMetric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

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

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

QueueSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

TopicSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

SessionMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

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

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

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

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


viii | Contents

ILookupContext.Lookup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212ILookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

LookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215LookupContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217LookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218LookupContext.Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219LookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

LookupContextFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221LookupContextFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222LookupContextFactory.CreateContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

LdapLookupConsts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

LdapLookupContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226LdapLookupContext.AddSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227LdapLookupContext.Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228LdapLookupContext.RemoveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

LdapLookupSSLParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231LdapLookupSSLParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231LdapLookupSSLParams.SetSSLQueryClientCertificateCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232LdapLookupSSLParams.SetSSLVerifyServerCertificateCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

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

EMSSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236EMSSSL.GetAuthOnly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.GetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.GetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.GetTargetHostName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241EMSSSL.Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242EMSSSL.SetAuthOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242EMSSSL.SetCertificateStoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243EMSSSL.SetClientTracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244EMSSSL.SetHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244EMSSSL.SetTargetHostName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

EMSSSLFileStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246EMSSSLFileStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247EMSSSLFileStoreInfo.ClearTrustedCerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247EMSSSLFileStoreInfo.SetSSLClientIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248EMSSSLFileStoreInfo.SetSSLPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249EMSSSLFileStoreInfo.SetSSLTrustedCertificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

EMSSSLSystemStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251EMSSSLSystemStoreInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252EMSSSLSystemStoreInfo.SetCertificateName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253EMSSSLSystemStoreInfo.SetCertificateStoreLocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254


Contents | ix

EMSSSLSystemStoreInfo.SetCertificateStoreName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

EMSSSLHostNameVerifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

EMSSSLHostNameVerifierArgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

EMSSSLStoreType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Chapter 13 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

DeliveryMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

IEMSSerialziable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261IEMSSerialziable.Deserialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262IEMSSerialziable.Serialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

MessageDeliveryMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Tibems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Tibems.CalculateMessageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Tibems.CreateFromBytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Tibems.GetAllowCloseInCallback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Tibems.GetAsBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Tibems.GetConnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Tibems.GetConnectAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Tibems.GetConnectionActiveURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Tibems.GetEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Tibems.GetExceptionOnFTSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Tibems.GetMessageEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279Tibems.GetMessageSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Tibems.GetPingInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Tibems.GetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Tibems.GetReconnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Tibems.GetReconnectAttemptTimeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Tibems.GetSessionDispatcherDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Tibems.GetSocketReceiveBufferSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Tibems.GetSocketSendBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Tibems.MakeWriteable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Tibems.SetAllowCloseInCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Tibems.SetConnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Tibems.SetConnectAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Tibems.SetEncoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Tibems.SetExceptionOnFTSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Tibems.SetMessageEncoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Tibems.SetPingInterval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Tibems.SetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Tibems.SetReconnectAttempts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Tibems.SetReconnectAttemptTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Tibems.SetSessionDispatcherDaemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Tibems.SetSocketReceiveBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302


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


| 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


xii | Tables



| xiii

Preface

TIBCO Enterprise Message Service™ software lets application programs send and receive messages according to the Java Message Service (JMS) protocol. It also integrates with TIBCO Rendezvous and TIBCO SmartSockets message products.

Topics

• Related Documentation, page xiv

• Typographical Conventions, page xv

• How to Contact TIBCO Customer Support, page xvii

This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform.


xiv | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO Enterprise Message Service DocumentationThe following documents form the TIBCO Enterprise Message Service documentation set:

• TIBCO Enterprise Message Service User’s Guide Read this manual to gain an overall understanding of the product, its features, and configuration.

• TIBCO Enterprise Message Service Installation Read the relevant sections of this manual before installing this product.

• TIBCO Enterprise Message Service Application Integration Guide This manual presents detailed instructions for integrating TIBCO Enterprise Message Service with third-party products.

• TIBCO Enterprise Message Service C & COBOL API Reference This reference is available in HTML and PDF formats.

• TIBCO Enterprise Message Service Java API Reference This reference is available as JavaDoc, and you can access the reference only through the HTML documentation interface.

• TIBCO Enterprise Message Service .NET API Reference This reference is available in PDF and HTML format.

• TIBCO Enterprise Message Service Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products:

• TIBCO Rendezvous™ software

• TIBCO SmartSockets™ software


Preface | xv

Third Party Documentation• Java™ Message Service specification, available through

java.sun.com/products/jms/index.html

• Java™ Message Service by Richard Monson-Haefel and David A. Chappell, O’Reilly and Associates, Sebastopol, California, 2001.

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

Use MyCommand to start the TIBCO foo process.

bold code

font Bold code font is used in the following ways:

• In procedures, to indicate what a user types. For example: Type the username admin.

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default value.

italic font Italic font is used in the following ways:

• To indicate a document title. For example: See TIBCO BusinessWorks Concepts for more details.

• To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal.

• To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname


xvi | Typographical Conventions

Key combinations

Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

Table 1 General Typographical Conventions

Convention Use

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical ’OR’ that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3

bold code

font The default parameter.

For example, if no parameter is specified, MyCommand is enabled:

MyCommand [enable | disable]

{ } A logical group of items. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either param1 and param2 or param3 and param4:

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include param2 as the second parameter. And the last parameter is either param3 or param4.

MyCommand param1 [param2] {param3 | param4}


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.


xviii | How to Contact TIBCO Customer Support

| 1

Chapter 1 Introduction

This chapter presents concepts specific to the TIBCO Enterprise Message Service™ .NET API and .NET Compact Framework API. For more general information and concepts pertaining to TIBCO Enterprise Message Service (EMS) software, see the TIBCO Enterprise Message Service User’s Guide.

Topics

• Overview, page 2

• Excluded Features and Restrictions, page 3

• Strings and Character Encodings, page 4

• .NET Compact Framework (CF), page 5


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.


Excluded Features and Restrictions | 3

Excluded Features and Restrictions

This section summarizes features that are not available in either the .NET library, or the .NET Compact Framework library.

Object SerializationThe .NET library supports serialization for all objects. In contrast, the .NET Compact Framework library supports serialization for a restricted set of objects. For details, see ObjectMessage on page 48.

Object serialization differs among the various EMS language APIs in ways that are incompatible. An ObjectMessage contains a serialized object. Therefore EMS programs can only send an ObjectMessage to another program written in the same language; for example, Java to Java, C to C, .NET to .NET, and .NET Compact Framework to .NET Compact Framework. In particular, notice that a .NET Compact Framework client and a full .NET client cannot exchange an ObjectMessage.

Table 3 Feature Support

Feature .NET.NETCompact Framework

XA protocols for external transaction managers — —

ConnectionConsumer, ServerSession, ServerSessionPool — —

Compression Yes —

SSL Yes —

Modify socket buffer sizes (see Tibems.SetSocketReceiveBufferSize on page 302 and Tibems.SetSocketSendBufferSize on page 303).

Yes —

Daemon threads (see Tibems.SetSessionDispatcherDaemon on page 301).

Yes —



Strings and Character Encodings

.NET programs represent strings within messages as byte arrays. Before sending an outbound message, EMS programs translate strings to their byte representation using an encoding, which the program specifies. Conversely, when EMS programs receive inbound messages, they reconstruct strings from byte arrays using the same encoding.

When a program specifies an encoding, it applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The method BytesMessage.WriteUTF always uses UTF-8 as its encoding.

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

OutboundMessages

Programs can determine the encoding of strings in outbound messages in three ways:

• Use the default global encoding—namely, UTF-8.

• Set a non-default global encoding (for all outbound messages) using Tibems.SetEncoding on page 293.

• Set the encoding for an individual message using Tibems.SetMessageEncoding on page 295.

OutboundMessages

An inbound message from another EMS client explicitly announces its encoding. A receiving client decodes the message using the proper encoding.


.NET Compact Framework (CF) | 5

.NET Compact Framework (CF)

This section presents recommendations for using the EMS .NET Compact Framework API to develop applications for handheld devices.

Threads .NET Compact Framework does not support background threads. To avoid problems with threads, we recommend that programs release all EMS resources before terminating. For example, close EMS connections when they are no longer needed (see Connection.Close on page 121).

Clock Resolution Clock resolution affects the granularity of all time-related calls and parameters—for example MessageConsumer.Receive(timeout), connect delays. On some handheld devices, clock resolution is coarser than one might expect. Check the resolution on your target device before selecting time values.

ObjectSerialization

See Object Serialization on page 3.

ExcludedFeatures

See Excluded Features and Restrictions on page 3.

DLL Import the correct EMS assembly (see Table 4).

Table 4 EMS Assembly DLL

Version DLL

Full .NET API TIBCO.EMS.dll

.NET Compact Framework API TIBCO.EMS-CF.dll




| 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


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.


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.



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.


Headers | 11

CorrelationIDAsBytes byte[] {get; set;}

The JMS specification describes this optional utility, but EMS does not support it. Attempting to access this header results in System.InvalidOperationException.

DeliveryMode int {get; set;}

This header instructs the server concerning persistent storage for the message.

Sending calls record the delivery mode for each message, based on either a property of the producer (DeliveryMode on page 94), or on a parameter to the sending call.

For values, see the class DeliveryMode on page 260.

MsgDeliveryMode MessageDeliveryMode {get; set;}

This parallel .NET property accesses the same header using enumerated values (instead of ordinary integers). We recommend it over the ordinary integer-valued accessor, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.

For values, see the class MessageDeliveryMode on page 264.

Destination Destination {get; set;}

Sending calls record the destination (queue or topic) of the message in this header (ignoring and overwriting any existing value). The value is based on either a property of the producer (Destination on page 95), or on a parameter to the send call.

Listeners that consume messages from several destinations can use this property to determine the actual destination of a message.


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.


Header Description


Headers | 13

Priority int {get; set;}

Sending calls record the priority of a message in this header, based on either a property of the producer (Priority on page 95), or on a parameter to the send call.

The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.

Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification does not require all providers to implement priority ordering of messages. (EMS supports priorities, but other JMS providers might not.)

Redelivered bool {get; set;}

The server sets this header to indicate whether a message might duplicate a previously delivered message:

• false—The server has not previously attempted to deliver this message to the consumer.

• true—It is likely (but not guaranteed) that the server has previously attempted to deliver this message to the consumer, but the consumer did not return timely acknowledgement.

See also, QueueSession on page 196.

ReplyTo Destination {get; set;}

Sending clients can set this header to request that recipients reply to the message:

• When the value is a destination object, recipients can send replies to that destination. Such a message is called a request.

• When the value is null, the sender does not expect a reply.

When sending a reply, clients can refer to the corresponding request by setting the CorrelationID field.


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.


Header Description


Properties | 15

Properties

Properties associate an extensible set of property field names with values. The EMS server uses properties to attach ancillary information to messages.

Client applications can also use properties—for example, to customize message filtering; see Message Selectors on page 18.

Setting Message PropertiesProperty names must conform to the syntax for message selector identifiers; see Identifiers on page 18.

Property values must not be null, nor the empty string.

Sending programs can set property values before sending a message.

Receiving programs cannot ordinarily set property values on inbound messages. However, the clearProperties method removes all existing the properties from a message, and lets the program set property values.

EMS PropertiesThe JMS specification reserves the property name prefix JMS_vendor_name_ for provider-specific properties (for EMS, this prefix is JMS_TIBCO_). Properties that begin with this prefix refer to features of EMS; client programs may use these properties to access those features, but not for communicating application-specific information among client programs.

Table 6 Message Property Names

Property Description

JMS_TIBCO_CM_PUBLISHER Correspondent name of an RVCM sender for messages imported from TIBCO Rendezvous.

JMS_TIBCO_CM_SEQUENCE Sequence number of an RVCM message imported from TIBCO Rendezvous.

JMS_TIBCO_COMPRESS Senders may set this property to request that EMS compress the message before sending it to the server.

JMS_TIBCO_DISABLE_SENDER Senders may set this property to prevent the EMS server from including the sender name in the message when the server sends it to consumers; see JMS_TIBCO_SENDER.



JMS_TIBCO_IMPORTED When the EMS server imports a message from an external message service (such as TIBCO Rendezvous or TIBCO SmartSockets), it sets this property to true.

JMS_TIBCO_MSG_EXT Producers can set this property to true to indicate that a message uses EMS extensions to the JMS specification for messages.

The server sets this property to true when importing a message from an external message service, since the message might use those extensions.

JMS_TIBCO_MSG_TRACE When a producer sets this property, the EMS server generates trace output when the message arrives from the producer, and whenever a consumer receives it.

• When the property value is null, the trace output contains the message ID and sequence number.

• When the property value is body, the trace output includes the message body as well.

JMS_TIBCO_PRESERVE_UNDELIVERED When this property is true, the server preserves a record of undeliverable messages by delivering them to the undelivered message queue, $sys.undelivered.

JMS_TIBCO_SENDER The EMS server fills this property with the user name (string) of the client that sent the message. This feature applies only when the sender_name property of the message’s destination is non-null. The sender can disable this feature (overriding the destination property sender_name) by setting a non-null value for the message property JMS_TIBCO_DISABLE_SENDER.

JMS_TIBCO_SS_SENDER When the EMS server imports a message from TIBCO SmartSockets, it sets this property to the SmartSockets sender header field (in SmartSockets syntax).

Table 6 Message Property Names

Property Description


Properties | 17

JMS PropertiesThe JMS specification reserves the property name prefix JMSX for properties defined by JMS. Client programs may use these properties to access those features, but not for communicating application-specific information among client programs.

To determine the set of JMS properties that a connection supports, call the method JMSXPropertyNames on page 125. For information about these properties, see the JMS specification.



Message Selectors

A message selector is string that lets a client program specify a set of messages, based on the values of message headers and properties. A selector matches a message if, after substituting header and property values from the message into the selector string, the string evaluates to true. Consumers can request that the server deliver only those messages that match a selector.

The syntax of selectors is based on a subset of SQL92 conditional expression syntax.

Identifiers

Identifiers can refer to the values of message headers and properties, but not to the message body. Identifiers are case-sensitive.

Basic Syntax An identifier is a sequence of letters and digits, of any length, that begins with a letter. As in Java, the set of letters includes _ (underscore) and $ (dollar).

Illegal Certain names are exceptions, which cannot be used as identifiers. In particular, NULL, TRUE, FALSE, NOT, AND, OR, BETWEEN, LIKE, IN, IS, and ESCAPE are defined to have special meaning in message selector syntax.

Value Identifiers refer either to message header names or property names. The type of an identifier in a message selector corresponds to the type of the header or property value. If an identifier refers to a header or property that does not exist in a message, its value is NULL.

Literals

String Literal A string literal is enclosed in single quotes. To represent a single quote within a literal, use two single quotes; for example, 'literal''s'. String literals use the Unicode character encoding. String literals are case sensitive.

Exact NumericLiteral

An exact numeric literal is a numeric value without a decimal point, such as 57, -957, and +62; numbers in the range of long are supported.

ApproximateNumeric Literal

An approximate numeric literal is a numeric value with a decimal point (such as 7., -95.7, and +6.2), or a numeric value in scientific notation (such as 7E3 and -57.9E2); numbers in the range of double are supported. Approximate literals use the floating-point literal syntax of the Java programming language.

Boolean Literal The boolean literals are TRUE and FALSE (case insensitive).


Message Selectors | 19

Internal computations of expression values use a 3-value boolean logic similar to SQL. However, the final value of an expression is always either TRUE or FALSE—never UNKNOWN.

Expressions

Selectors asExpressions

Every selector is a conditional expression. A selector that evaluates to true matches the message; a selector that evaluates to false or unknown does not match.

ArithmeticExpression

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

ConditionalExpression

Conditional expressions are composed of comparison operations, logical operations, and smaller conditional expressions.

Order ofEvaluation

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

Operators

Case Insensitivity Operator names are case-insensitive.

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

ComparisonOperators

Comparison operators: =, >, >=, <, <=, <> (not equal).

These operators can compare only values of comparable types. (Exact numeric values and approximate numerical values are comparable types.) Attempting to compare incomparable types yields false. If either value in a comparison evaluates to NULL, then the result is unknown (in SQL 3-valued logic).

Comparison of string values is restricted to = and <>. Two strings are equal if and only if they contain the same sequence of characters.

Comparison of boolean values is restricted to = and <>.

ArithmeticOperators

Arithmetic operators in precedence order:

• +, - (unary)

• *, / (multiplication and division)

• +, - (addition and subtraction)

Arithmetic operations obey numeric promotion rules of the Java programming language.



BetweenOperator

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

The BETWEEN comparison operator includes its endpoints. For example:

• age BETWEEN 5 AND 9 is equivalent to age >= 5 AND age <= 9

• age NOT BETWEEN 5 AND 9 is equivalent to age < 5 OR age > 9

StringSet Membership

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

The identifier must evaluate to either a string or NULL. If it is NULL, then the value of this expression is unknown.

Pattern Matching identifier [NOT] LIKE pattern-value [ESCAPE escape-character]

The identifier must evaluate to a string.

The pattern-value is a string literal, in which some characters bear special meaning:

• _ (underscore) can match any single character.

• % (percent) can match any sequence of zero or more characters.

• escape-character preceding either of the special characters changes them into ordinary characters (which match only themselves).

Null Header orProperty

identifier IS NULL

This comparison operator tests whether a message header is null, or a message property is absent.

identifier IS NOT NULL

This comparison operator tests whether a message header or message property is non-null.

White Space

White space is any of the characters space, horizontal tab, form feed, or line terminator—or any contiguous run of characters in this set.


Data Type Conversion | 21

Data Type Conversion

Table 7 summarizes legal datatype conversions. The symbol X in Table 7 indicates that a value written into a message as the row type can be extracted as the column type. This table applies to all message values—including map pairs, headers and properties—except as noted below.

Notes • Message properties cannot have byte array values.

• Values written as strings can be extracted as a numeric or boolean type only when it is possible to parse the string as a number of that type.

Table 7 Data Type Conversion

bool byte short char int long float double string byte[]

bool X X

byte X X X X X

short X X X X

char X X

int X X X

long X X

float X X X

double X X

string X X X X X X X X

byte[] X



MessageClass

Declaration public class Message : ICloneable

Subclasses BytesMessage on page 32MapMessage on page 41ObjectMessage on page 48StreamMessage on page 50TextMessage on page 58

Purpose Messages carry information among EMS client programs.

Remarks All other message types extend this root class.

Field Description

Constants defined as .NET fields.

DEFAULT_DELIVERY_MODE int DeliveryMode.PERSISTENT

When neither the sending call nor the producer supplies a delivery mode, this default applies.

DEFAULT_MSG_DELIVERY_MODE MessageDeliveryMode MessageDeliveryMode.Persistent

Enumerated version of the same value.

DEFAULT_PRIORITY int 4

When neither the sending call nor the producer supplies a priority, this default applies.

See also Priority on page 13.

DEFAULT_TIME_TO_LIVE long 0

When neither the sending call nor the producer supplies a priority, this default applies. The default value, zero, indicates that messages do not expire.

See also Expiration on page 12.


Message | 23

JMS Headers as.NET Properties

This table lists the JMS headers that are available as .NET properties of message objects. For details, see Headers on page 10.

Header

CorrelationID

CorrelationIDAsBytes

DeliveryMode

MsgDeliveryMode

Destination

Expiration

MessageID

MsgType

Priority

Redelivered

ReplyTo

Timestamp

Method Description Page

Message.Acknowledge Acknowledge messages. 25

Message.ClearBody Clear the body of a message. 26

Message.ClearProperties Clear the properties of a message. 26

Message.Clone Create a copy of the message object. 26

Message.GetDeliveryModeName Convert a delivery mode constant to a string. 27

Message.Get Property Get the value of a message property. 28

Message.PropertyExists Test whether a named property has been set on a message.

29



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

Message.ToString Return a string representation of a message object.

31



Message.Acknowledge | 25

Message.AcknowledgeMethod

Declaration virtual void Acknowledge();

Purpose Acknowledge messages.

Remarks The behavior of this call depends on the acknowledgement mode of the Session.

• In ClientAcknowledge mode, this call acknowledges all messages that the program has consumed within the session. (This behavior complies with the JMS specification.)

• In ExplicitClientAcknowledge mode, this call acknowledges only the individual message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)

• In ExplicitClientDupsOkAcknowledge mode, this call lazily acknowledges only the individual message. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. (This mode and behavior are proprietary extensions, specific to TIBCO EMS.)

• In all other modes, this call has no effect. In particular, modes that specify transactions or implicit acknowledgement do not require the consuming program to call this method. However, calling it does not produce an exception. (This behavior complies with the JMS specification.)

Consumed Three events mark a message as consumed—that is, eligible for acknowledgment using this method:

• Just before the provider raises an EMSMessageHandler event, it marks the message argument as consumed.

• Just before the provider calls an IMessageListener.OnMessage callback, it marks the message argument as consumed.

• Just before a receive call returns a message, it marks that message as consumed.

Redelivery The server might redeliver unacknowledged messages.

See Also MessageConsumer.Receive on page 83Session on page 170AcknowledgeMode on page 171SessionAcknowledgeMode on page 171QueueSession on page 196



Message.ClearBodyMethod

Declaration virtual void ClearBody();

Purpose Clear the body of a message.

Remarks Clearing the body of a message leaves its header and property values unchanged.

If the message body was read-only, this method makes it writable. The message body appears and behaves identically to an empty body in a newly created message.

Message.ClearPropertiesMethod

Declaration virtual void ClearProperties();

Purpose Clear the properties of a message.

Remarks Clearing the property values of a message leaves its header values and body unchanged.

Message.CloneMethod

Declaration virtual Object Clone();

Implements ICloneable.Clone

Purpose Create a copy of the message object.


Message.GetDeliveryModeName | 27

Message.GetDeliveryModeNameMethod

Declaration static string GetDeliveryModeName(MessageDeliveryMode deliveryMode );

static string GetDeliveryModeName(int deliveryMode );

Purpose Convert a delivery mode constant to a string.

Parameters

Remarks Programs can obtain the delivery mode of a message by accessing the DeliveryMode header property of the message object.

This method is an extension to the JMS specification.

See Also DeliveryMode on page 260MessageDeliveryMode on page 264

Parameter Description

deliveryMode Convert this delivery mode to a string.



Message.Get PropertyMethod

Declaration bool GetBooleanProperty(string name);byte GetByteProperty(string name);short GetShortProperty(string name);int GetIntProperty(string name);long GetLongProperty(string name);float GetFloatProperty(string name);double GetDoubleProperty(string name);string GetStringProperty(string name);Object GetObjectProperty(string name);

Purpose Get the value of a message property.

Parameters

Remarks The JMS specification defines eight methods to get properties with different value types—converting between compatible types. It also defines a ninth method to get values of the eight primitive types as if they were objects. All nine of these methods convert property values to the corresponding type (if possible).

When the message does not have a property set for the name, these rules apply:

• GetStringProperty and GetObjectProperty return null.

• GetBooleanProperty returns false.

• Numeric methods throw EMSException.

See Also Message.Set Property on page 30


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.


Message.PropertyExists | 29

Message.PropertyExistsMethod

Declaration virtual bool PropertyExists(string name );

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

Parameters

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


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



Message.Set PropertyMethod

Declaration void SetBooleanProperty(string name, bool val);void SetByteProperty(string name, byte val);void SetShortProperty(string name, short val);void SetIntProperty(string name, int val);void SetLongProperty(string name, long val);void SetFloatProperty(string name, float val);void SetDoubleProperty(string name, double val);void SetStringProperty(string name, string val);void SetObjectProperty(string name, Object val);

Purpose Set the value of a message property.

Parameters

Remarks The JMS specification defines eight methods to set properties with different primitive value types. It also defines a ninth method to set a property to an object representation of any of the eight primitive types.

See Also Message.Get Property on page 28


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.


Message.ToString | 31

Message.ToStringMethod

Declaration override string ToString();

Purpose Return a string representation of a message object.

Remarks The string includes the body type, headers (name-value pairs), properties (name-value pairs), and body content.



BytesMessageClass

Declaration class BytesMessage : Message

Purpose A message containing a stream of uninterpreted bytes.

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

Superclasses Message on page 22


BytesMessage Construct an empty bytes message for a session. 33

BytesMessage.Read Read primitive data types from the byte stream in the message body.

34

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

36

BytesMessage.Write Write primitive data types to the byte stream in the message body.

37

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

39

BytesMessage.Reset Set the read position to the beginning of the byte stream, and mark the message body as read-only.

40

Member Description

Properties

BodyLength long {get;}

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


BytesMessage | 33

BytesMessageConstructor

Declaration BytesMessage(Session session);

Purpose Construct an empty bytes message for a session.

Parameters Parameter Description

session The Session of the message.



BytesMessage.ReadMethod

Declaration bool ReadBoolean();sbyte ReadByte();byte ReadUnsignedByte();short ReadShort();ushort ReadUnsignedShort();char ReadChar();int ReadInt();long ReadLong();float ReadFloat();double ReadDouble();String ReadUTF();

Purpose Read primitive data types from the byte stream in the message body.

Remarks The JMS specification defines these eleven methods to extract data from the byte stream of a BytesMessage.

Each call reads a unit of data from the stream, and advances the read position so that the next read call gets the next datum.


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


BytesMessage.Read | 35

See Also BytesMessage.ReadBytes on page 36

ReadInt 4 int

ReadLong 8 long

ReadFloat 4 float

ReadDouble 8 double

ReadUTF varies String

Encoded as UTF-8

Table 8 BytesMessage Read Methods

Method # Bytes Interpret As



BytesMessage.ReadBytesMethod

Declaration int ReadBytes(byte[] value);

int ReadBytes(byte[] value, int length);

Purpose Read bytes to a byte array from the byte stream in the message body.

Parameters

Remarks Each call reads bytes from the stream into the byte array, and advances the read position.

When the program supplies a length argument, the call attempts to read length bytes; otherwise it attempts to read value.length bytes.

Returns This call returns the actual number of bytes read. When the call cannot read even one byte, it returns -1.


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


BytesMessage.Write | 37

BytesMessage.WriteMethod

Declaration void WriteBoolean(bool value);void WriteByte(byte value);void WriteShort(short value);void WriteChar(char value);void WriteInt(int value);void WriteLong(long value);void WriteFloat(float value);void WriteDouble(double value);void WriteUTF(string value);void WriteObject(Object value);

Purpose Write primitive data types to the byte stream in the message body.

Remarks The JMS specification defines these ten methods to insert data into the byte stream of a BytesMessage.

Each call writes a data value to the stream, and advances the write position so that the next write call appends to the new end of the stream.


value Write this value to the message.

Table 9 BytesMessage Write Methods

Method # Bytes Notes

WriteBoolean 1

WriteByte 1

WriteShort 2

WriteChar 2

WriteInt 4

WriteLong 8

WriteFloat 4

WriteDouble 8

WriteUTF varies Encoded as UTF-8



See Also BytesMessage.WriteBytes on page 39

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

Table 9 BytesMessage Write Methods

Method # Bytes Notes


BytesMessage.WriteBytes | 39

BytesMessage.WriteBytesMethod

Declaration void WriteBytes(byte[] value);

void WriteBytes(byte[] value, int offset, int length);

Purpose Write bytes from a byte array to the byte stream in the message body.

Parameters

Remarks Each call writes bytes from the byte array into the stream, and advances the write position.

When the program supplies offset and length arguments, the call attempts to write the specified bytes to the stream; otherwise it attempts to write the entire byte array.

Offset & Length When present, the offset and length arguments must conform to these restrictions:

• offset must be in the range [0, value.length-1]

• length must be in the range [0, value.length]

• offset+length must be in the range [0, value.length]

That is, these two arguments must specify a span of bytes within the value argument. Otherwise the call throws a System.IndexOutOfRangeException (and does not write any bytes).


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.



BytesMessage.ResetMethod

Declaration void Reset();

Purpose Set the read position to the beginning of the byte stream, and mark the message body as read-only.

Remarks Reset prepares a message body for reading, as if the message were newly received. Contrast Message.ClearBody on page 26, which clears a message body in preparation for writing, as if it were newly created.


MapMessage | 41

MapMessageClass

Declaration class MapMessage : Message

Purpose A message containing a set of name-value pairs.

Remarks Messages with this body type contain several values, indexed by name.



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.



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.


MapMessage | 43

MapMessageConstructor

Declaration MapMessage(Session session);

Purpose Construct an empty map message for a session.





MapMessage.GetMethod

Declaration bool GetBoolean(string name);byte GetByte(string name);short GetShort(string name);char GetChar(string name);int GetInt(string name);long GetLong(string name);float GetFloat(string name);double GetDouble(string name);string GetString(string name);byte[] GetBytes(string name);Object GetObject(string name);

Purpose Get primitive data types from a map message.

Parameters

Remarks The JMS specification defines eleven methods to extract data from the name-value pairs of a MapMessage. Ten of these methods extract primitive data values. The GetObject method gets these values as if they were objects.

Returns Each call finds the named pair (if it exists) and returns its value.

When the message does not have a field set for the name, these calls return null.


name Get the value associated with this name.


MapMessage.ItemExists | 45

MapMessage.ItemExistsMethod

Declaration bool ItemExists(string name);

Purpose Test that a named pair is set.


name Test for a pair with this name.



MapMessage.SetMethod

Declaration void SetBoolean(string name, bool value);void SetByte(string name, byte value);void SetShort(string name, short value);void SetChar(string name, char value);void SetInt(string name, int value);void SetLong(string name, long value);void SetFloat(string name, float value);void SetDouble(string name, double value);void SetString(string name, String value);void SetObject(string name, Object value);

Purpose Set a name-value pair in a map message.

Parameters

Remarks The JMS specification defines eleven methods to set name-value pairs in a MapMessage (these ten, plus MapMessage.SetBytes on page 47).

The first nine of these methods set pairs with primitive value types. The SetObject method first converts an object to a primitive type (if possible), and then places that value in the pair.

See Also MapMessage.SetBytes on page 47


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.


MapMessage.SetBytes | 47

MapMessage.SetBytesMethod

Declaration void SetBytes(string name, byte[] value);

void SetBytes(string name, byte[] value, int offset, int length);

Purpose Set a name-value pair to a byte array value.

Parameters

Remarks When the program supplies offset and length arguments, the call extracts the specified bytes and uses them as the value; otherwise it uses the entire byte array.

When present, the offset and length arguments must be between zero and value.length (inclusive), and their sum must also fall within the same range. That is, these two arguments must specify a span of bytes within the value argument. Otherwise the call throws an System.IndexOutOfRangeException (and does not set any value).

See Also MapMessage.Set on page 46


name Set the pair with this name.

value Associate bytes from this byte array as the value of the name.





ObjectMessageClass

Declaration class ObjectMessage : Message

Purpose A message containing a serializable object.

Remarks Setting the content of a MessageObject stores a snapshot of the object. subsequent changes to the original object do not affect the message.

.NETCompact

Framework

Object serialization differs among the various EMS language APIs in ways that are incompatible. An ObjectMessage contains a serialized object. Therefore EMS programs can only send an ObjectMessage to another program written in the same language; for example, Java to Java, C to C, .NET to .NET, and .NET Compact Framework to .NET Compact Framework. In particular, notice that a .NET Compact Framework client and a full .NET client cannot exchange an ObjectMessage.

Furthermore, the .NET Compact Framework supports only a limited set of objects for TheObject in an ObjectMessage—namely, bool, int, long, short, double, float, byte, bytes, char, string, short[], int[], long[], float[], double[], MapMessage, StreamMessage, and program-defined classes that implement IEMSSerialziable. Attempting to set the value to an unsupported object type results in MessageFormatException. This restriction applies only to .NET Compact Framework (the full .NET EMS API is exempt).

Superclasses Message on page 22IEMSSerialziable on page 261MessageFormatException on page 318

Member Description

Properties

TheObject Object {get; set;}

Programs can get and set the object in an ObjectMessage.


ObjectMessage Constructor. 49


ObjectMessage | 49

ObjectMessageConstructor

Declaration public ObjectMessage(Session session,object obj );

public ObjectMessage(Session session );

Purpose Create an object message.

Parameters

See Also .NET Compact Framework on page 48Session.CreateObjectMessage on page 184


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.



StreamMessageClass

Declaration class StreamMessage : Message

Purpose A message containing a stream of data items.

Remarks Each datum in the stream must be a primitive type, or an object representation of a primitive type.


Extensions TIBCO Enterprise Message Service extends the MapMessage and StreamMessage body types in two ways. These extensions allow TIBCO Enterprise Message Service to exchange messages with TIBCO Rendezvous and ActiveEnterprise formats that have certain features not available within the JMS specification.

Member Description

Properties

FieldCount int {get;}

Programs can get the number of data items in the message body. Programs cannot set this property.


StreamMessage Construct an empty stream message for a session. 52

StreamMessage.Read Read primitive data types from a stream message. 53

BytesMessage.ReadBytes Read a byte array from a stream message. 54

StreamMessage.Reset Set the read position to the beginning of the stream, and mark the message body as read-only.

55

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

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


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.



StreamMessageConstructor

Declaration StreamMessage(Session session);

Purpose Construct an empty stream message for a session.




StreamMessage.Read | 53

StreamMessage.ReadMethod

Declaration bool ReadBoolean();sbyte ReadByte();short ReadShort();char ReadChar();int ReadInt();long ReadLong();float ReadFloat();double ReadDouble();String ReadString();Object ReadObject();

Purpose Read primitive data types from a stream message.

Remarks The JMS specification defines these methods to extract data from a StreamMessage. (See also StreamMessage.ReadBytes on page 54.)

Each call reads a unit of data from the stream, and advances the read position so that the next read call gets the next datum.

See Also StreamMessage.ReadBytes on page 54



StreamMessage.ReadBytesMethod

Declaration int ReadBytes(byte[] value);

Purpose Read a byte array from a stream message.

Parameters

Remarks Each call reads bytes from the stream into the byte array, and advances the read position.

This call returns the actual number of bytes read. When the call cannot read even one byte, it returns -1.

A program that calls this method must call it repeatedly until it returns -1, indicating that the program has extracted the complete set of bytes. Only then may the program call another read method.


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


StreamMessage.Reset | 55

StreamMessage.ResetMethod


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.



StreamMessage.WriteMethod

Declaration void WriteBoolean(bool value);void WriteByte(byte value);void WriteShort(short value);void WriteChar(char value);void WriteInt(int value);void WriteLong(long value);void WriteFloat(float value);void WriteDouble(double value);void WriteString(string value);void WriteObject(Object value);

Purpose Write primitive data types to a stream message.

Remarks The JMS specification defines these methods to insert data into a StreamMessage. (See also StreamMessage.WriteBytes on page 57.)

Each call writes a data value to the stream, and advances the write position so that the next write call appends to the new end of the stream.

WriteObject converts an object to a primitive value (if possible), and writes that value to the stream message.

Parameters

See Also StreamMessage.WriteBytes on page 57


value Write this datum.


StreamMessage.WriteBytes | 57

StreamMessage.WriteBytesMethod

Declaration void WriteBytes(byte[] value);

void WriteBytes(byte[] value, int offset, int length);

Purpose Write bytes from a byte array to a stream message.

Parameters

Remarks Each call writes bytes from the byte array into the stream, and advances the write position.

When the program supplies offset and length arguments, the call attempts to write the specified bytes to the stream; otherwise it attempts to write the entire byte array.

When present, the offset and length arguments must be between zero and value.length (inclusive), and their sum must also fall within the same range. That is, these two arguments must specify a span of bytes within the value argument. Otherwise the call throws an IndexOutOfRangeException (and does not write any bytes).


value Write bytes from this byte array to the message.





TextMessageClass

Declaration class TextMessage : Message

Purpose A message containing a text string.

Remarks A TextMessage object is used to send a message containing a String. It inherits from the Message interface and adds a text message body. This message type can be used to transport text-based messages, including those with XML content.

When a client receives a TextMessage, it is in read-only mode. If a client attempts to write to the message at this point, a MessageNotWriteableException is thrown. Calling TextMessage.ClearBody allows you to both read from and write to the message.


Member Description

Properties

Text string {get; set;}

Programs can get and set the text string in a TextMessage.


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


TextMessage | 59

TextMessageConstructor

Declaration public TextMessage(Session session,string text );

public ObjectMessage(Session session );

Purpose Create a text message object.

Parameters

See Also Session.CreateTextMessage on page 190

TextMessage.ClearBody

Declaration override void ClearBody();

Purpose Clear the body of a text message.

Remarks Clearing the body of a text message leaves its header and property values unchanged.

If the text message body was read-only, this method makes it writable. The message body appears and behaves identically to an empty body in a newly created message.

See Also Message.ClearBody on page 26


session Associate the new message with this session.

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



TextMessage.Clone

Declaration override object Clone();

Implements ICloneable.Clone.

Purpose Create a copy of the text message object.


Message.EmptyEnum | 61

Message.EmptyEnumClass

Declaration class Message.EmptyEnum : IEnumerator

Purpose Specifies an empty enumerator

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

Requirements Namespace: TIBCO.EMSAssembly: TIBCO.EMS (in TIBCO.EMS.dll)

Member Description

Properties

Current object Current {get;}

Implements IEnumerator.Current.

Trying to get the current object in enumerator will throw an InvalidOperationException.


Message.EmptyEnum Construct an empty enumerator. 62

Message.EmptyEnum.MoveNext Advances the enumerator to the next element of the collection.

62

Message.EmptyEnum.Reset Reset the enumerator. 62



Message.EmptyEnumConstructor

Declaration Message.EmptyEnum();

Purpose Construct an empty enumerator.

Message.EmptyEnum.MoveNextMethod

Declaration bool MoveNext();

Purpose Advances the enumerator to the next element of the collection.

Remarks Implements IEnumerator.MoveNext. MoveNext() will always returns false.

Message.EmptyEnum.Reset


Purpose Reset the enumerator.

Remarks Implements IEnumerator.Reset. Reset() does nothing since the enumerator is empty.


| 63




| 65

Chapter 3 Destination

Topics

• Destination Overview, page 66

• Destination, page 69

• Queue, page 70

• TemporaryQueue, page 72

• TemporaryTopic, page 74

• Topic, page 76


66 | Chapter 3 Destination

Destination Overview

Destination objects represent destinations within the EMS server—the queues and topics to which programs send messages, and from which they receive messages.

Queues deliver each message to exactly one consumer. Topics deliver each message to every subscriber. Queues and topics can be static, dynamic or temporary.

Table 10 Destination Overview

Aspect Static Dynamic Temporary

Purpose Static destinations let administrators configure EMS behavior at the enterprise level. Administrators define these administered objects, and client programs use them—relieving program developers and end users of the responsibility for correct configuration.

Dynamic destinations give client programs the flexibility to define destinations as needed for short-term use.

Temporary destinations are ideal for limited-scope uses, such as reply subjects.

Scope of Delivery

Static destinations support concurrent use. That is, several client processes (and in several threads within a process) can create local objects denoting the destination, and consume messages from it.

Dynamic destinations support concurrent use. That is, several client processes (and in several threads within a process) can create local objects denoting the destination, and consume messages from it.

Temporary destinations support only local use. That is, only the client connection that created a temporary destination can consume messages from it.

However, servers connected by routes do exchange messages sent to temporary topics.


Destination Overview | 67

Creation Administrators create static destinations using EMS server administration tools or API.

If the server configuration permits dynamic destinations, client programs can create one in two steps:

1. Create a local destination object; see Session on page 170.

2. Send a message to that destination, or create a consumer for it. Either of these actions automatically creates the destination in the server.

Client programs create temporary destinations; see Session on page 170.

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

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

Not applicable.





Duration A static destination remains in the server until an administrator explicitly deletes it.

A dynamic destination remains in the server as long as at least one client actively uses it. The server automatically deletes it (at a convenient time) when all applicable conditions are true:

• Topic or Queue all client programs that access the destination have disconnected

• Topic no offline durable subscribers exist for the topic

• Queue queue, no messages are stored in the queue

A temporary destination remains in the server either until the client that created it explicitly deletes it, or until the client disconnects from the server.




Destination | 69

DestinationClass

Declaration class Destination

Purpose Root behavior of all destinations.

Subclasses Queue on page 70TemporaryQueue on page 72

Topic on page 76TemporaryTopic on page 74

Remarks Administrators define destinations in the server. Client programs access them using methods of LookupContext.

Programs do not create instances of this class; instead, they create instances of its subclasses.

See Also LookupContext on page 215



QueueClass

Declaration class Queue : Destination

Purpose Queues deliver each message to exactly one consumer.

Subclasses TemporaryQueue on page 72

Member Description

Properties

QueueName string {get;}

The lookup name of the queue object. Each queue has a name that is unique among all queues.


Queue Constructor. 71


Queue | 71

QueueConstructor

Declaration Queue(string name);

Purpose Create a queue object.

Remarks This constructor creates only local objects (within the program). It does not attempt to lookup the corresponding server object until the program creates a MessageConsumer or a MessageProducer that uses the queue. That automatic lookup can result in either of two outcomes:

• If lookup succeeds, it binds the local queue object to the server queue object.

• If lookup fails, the server creates a new dynamic queue.

See Also Session.CreateQueue on page 186LookupContext on page 215


name Find or create a queue with this name.



TemporaryQueueClass

Declaration class TemporaryQueue : Queue

Purpose Programs can use temporary queues as reply destinations.

Remarks Programs create temporary queues using Session.CreateTemporaryQueue.

A temporary queue exists only for the duration of the session’s connection, and is available only within that connection.

Only consumers associated with the same connection as the temporary queue can consume messages from it.

See Also Session.CreateTemporaryQueue on page 188


TemporaryQueue.Delete Delete a temporary queue. 73


TemporaryQueue.Delete | 73

TemporaryQueue.DeleteMethod

Declaration void Delete();

Purpose Delete a temporary queue.

Remarks When a client deletes a temporary queue, the server deletes any unconsumed messages in the queue.

Throws If the client still has listeners or receivers for the queue, or is in the middle of a Receive call, then Delete throws an EMSException.



TemporaryTopicClass

Declaration class TemporaryTopic : Topic

Purpose Programs can use temporary topics as reply destinations.

Remarks Programs create temporary topics using Session.CreateTemporaryTopic.

A temporary topic exists only for the duration of the session’s connection, and is available only within that connection.

Only consumers associated with the same connection as the temporary topic can consume messages from it.

Servers connected by routes do exchange messages sent to temporary topics.

See Also Session.CreateTemporaryTopic on page 189


TemporaryTopic.Delete Delete a temporary topic. 75


TemporaryTopic.Delete | 75

TemporaryTopic.DeleteMethod

Declaration void Delete();

Purpose Delete a temporary topic.

Remarks When a client deletes a temporary topic, the server deletes any unconsumed messages in the topic.

Throws If the client still has listeners or receivers for the topic, or is in the middle of a Receive call, then Delete throws an EMSException.



TopicClass

Declaration class Topic : Destination

Purpose Topics deliver each message to multiple consumers.

Subclasses TemporaryTopic on page 74

Member Description

Properties

TopicName string {get;}

The lookup name of the topic object. Each topic has a name that is unique among all topics.


Topic Constructor. 77


Topic | 77

TopicConstructor

Declaration Topic(string name );

Purpose Create a topic object.

Remarks This constructor creates only local objects (within the program). It does not attempt to lookup the corresponding server object until the program creates a MessageConsumer or a MessageProducer that uses the topic. That automatic lookup can result in either of two outcomes:

• If lookup succeeds, it binds the local topic object to the server topic object.

• If lookup fails, the server creates a new dynamic topic.

See Also Session.CreateTopic on page 191LookupContext on page 215


name Find or create a topic with this name.




| 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


80 | Chapter 4 Consumer

MessageConsumerClass

Declaration class MessageConsumer

Purpose Root behavior of all consumers.

Subclasses QueueReceiver

TopicSubscriber

Remarks Consumers can receive messages synchronously (using the Receive methods), or asynchronously.

Consumers can receive messages asynchronously in either of two idioms. Programmers may select either idiom—but not both (which would cause duplicate message processing, with undefined behavior).

• MessageHandler events let programs receive messages in a .NET programming idiom.

• In contrast, the MessageListener property mimics the way in which JMS provides similar functionality in a Java programming idiom.

Member Description

Events

MessageHandler EMSMessageHandler

The client library raises an event when a message arrives at the destination. The program implements a handler delegate to processes it asynchronously, and registers the delegate here. See Remarks, above.

Properties

MessageListener IMessageListener {get; set;}

When a message arrives, the client library calls this listener’s onMessage method with the message as its argument. The program implements the message listener interface, and registers a message listener object by setting this property. See Remarks, above.


MessageConsumer | 81

See Also IMessageListener on page 90EMSMessageHandler on page 87

MessageSelector string {get;}

A message selector restricts the set of messages that the consumer receives to those that match the selector; see Message Selectors on page 18.

Programs can set this property only when creating the consumer object; see Session.CreateConsumer on page 180.

Member Description


MessageConsumer.Close Stop receiving messages; reclaim resources. 82

MessageConsumer.Receive Receive a message (synchronous). 83

MessageConsumer.ReceiveNoWait Receive a message (synchronous, non-blocking). 84



MessageConsumer.CloseMethod

Declaration void Close();

Purpose Stop receiving messages; reclaim resources.

Remarks If a receive call or a message listener is in progress, then Close waits until that call returns.

Message consumers rely on resources outside the client program. To reclaim these resources in a timely manner, we recommend that client programs explicitly close message consumer objects (rather than waiting for garbage collection).

See Also MessageConsumer.Receive on page 83IMessageListener on page 90Session.CreateConsumer on page 180


MessageConsumer.Receive | 83

MessageConsumer.ReceiveMethod

Declaration Message Receive();

Message Receive(long timeout );

Purpose Receive a message (synchronous).

Remarks This method consumes the next message from the destination.

When the destination does not have any messages ready, this method blocks:

• If a message arrives at the destination, this call immediately returns that message.

• If the (non-zero) timeout elapses before a message arrives, this call returns null.

• If another thread closes the consumer, this call returns null.

When calling receive within a transaction, the consumer retains the message until transaction commits.


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.



MessageConsumer.ReceiveNoWaitMethod

Declaration Message ReceiveNoWait();

Purpose Receive a message (synchronous, non-blocking).

Remarks When the destination has at least one message ready, this method immediately returns the next message.

When the destination does not have any messages ready, this method immediately returns null.

When calling receive within a transaction, the consumer retains the message until transaction commits.


QueueReceiver | 85

QueueReceiverClass

Declaration class QueueReceiver : MessageConsumer

Purpose Consume messages from a queue.

Remarks This class inherits almost all of its behavior from MessageConsumer. It adds only a property, specializing the generic destination to a queue.

Member Description

Properties

Queue Queue {get;}

The receiver consumes messages from this queue.

Programs set this queue when creating the receiver, and cannot subsequently change it.



TopicSubscriberClass

Declaration class TopicSubscriber : MessageConsumer

Purpose Consume messages from a topic.

Remarks This class inherits almost all of its behavior from MessageConsumer; it adds only two properties.

Member Description

Properties

NoLocal bool {get;}

When true, the subscriber does not receive messages sent through the same server connection (that is, the connection associated with the subscriber).

Programs set this property when creating the subscriber, and cannot subsequently change it.

Topic Topic {get;}

The subscriber consumes messages from this topic.

Programs set this topic property when creating the subscriber, and cannot subsequently change it.


EMSMessageHandler | 87

EMSMessageHandlerDelegate

Declaration delegate void EMSMessageHandler(object sender,EMSMessageEventArgs args );

Purpose Asynchronously process an arriving message.

Remarks This delegate provides an asynchronous pathway for receiving messages. The program implements this delegate, and registers it with a MessageConsumer. When a message arrives, the client library raises an event. This delegate processes the event, which presents the message.

EMSMessageHandler receives messages in a .NET programming idiom. In contrast, IMessageListener mimics the way in which JMS provides similar functionality in a Java programming idiom. Programmers may select either idiom—but not both (which would cause duplicate message processing, with undefined behavior).

Example 1 Message Event Handler...consumer.MessageHandler += new EMSMessageHandler(handleMsg);...private void handleMsg(object sender, EMSMessageEventArgs arg){

Message m = arg.Message;Console.WriteLine("Received message: " + m);...

}...

Serialization In compliance with the JMS specification, sessions distribute messages to listeners and event handler delegates in serial (non-concurrent) fashion.

See Also MessageConsumer on page 80EMSMessageEventArgs on page 88


sender The MessageConsumer object that raised a message event.

args The event, which contains the message object.



EMSMessageEventArgsClass

Declaration class EMSMessageEventArgs : EventArgs

Purpose Present an arriving message as a .NET event.

Remarks EMSMessageHandler delegates receive this object as an argument.

Member Description

Properties

Message Message {get;}

Programs can get the message that triggered the event.


EMSMessageEventArgs Constructor. 89


EMSMessageEventArgs | 89

EMSMessageEventArgsConstructor

Declaration EMSMessageEventArgs(Message msg );

Purpose Create a message event.


msg The new event encapsulates this message, and signals its arrival.



IMessageListenerInterface

Declaration interface IMessageListener

Purpose Asynchronously process an arriving message.

Remarks This interface provides an asynchronous pathway for receiving messages. The program implements this interface, and registers a message listener with a MessageConsumer. When a message arrives, the client library calls the listener’s onMessage method with the message as its argument.

IMessageListener mimics the way in which JMS receives messages in a Java programming idiom. In contrast, EMSMessageHandler provides similar functionality in a .NET idiom. Programmers may select either idiom—but not both (which would cause duplicate message processing, with undefined behavior).

Serialization In compliance with the JMS specification, sessions distribute messages to listeners and event handler delegates in serial (non-concurrent) fashion.

Deprecated In earlier releases, clients could register listeners with sessions as well as consumers. This practice is now deprecated—we recommend migrating existing code to one of these two practices:

• Java Idiom Register listeners with consumers.

• .NET Idiom Register EMSMessageHandler delegates with consumers.

See Also MessageConsumer on page 80Session on page 170


IMessageListener.OnMessage Process inbound messages (asynchronous). 91


IMessageListener.OnMessage | 91

IMessageListener.OnMessageMethod

Declaration void OnMessage(Message message );

Purpose Process inbound messages (asynchronous).


message Process this message.




| 93

Chapter 5 Producer

Message producers send messages to destinations on the server.

Topics

• MessageProducer, page 94

• QueueSender, page 100

• TopicPublisher, page 103


94 | Chapter 5 Producer

MessageProducerClass

Declaration class MessageProducer

Purpose Root behavior of all producers.

Subclasses QueueSender

TopicPublisher

Remarks Clients use message producers to send messages. A message producer object can store several parameters that affect the messages it sends.

This class lacks a constructor. Instead, clients create message producers using methods of a Session object; subclasses (such as QueueSession and TopicSession) each define methods to create corresponding producer subclasses.

Member Description

Properties

DeliveryMode int {get; set;}

Delivery mode instructs the server concerning persistent storage.

Programs can use this property to define a default delivery mode for messages that this producer sends. Individual sending calls can override this default value.

For values, see the class DeliveryMode on page 260.

MsgDeliveryMode MessageDeliveryMode {get; set;}

This parallel property accesses the same default value using enumerated values (instead of ordinary integers). We recommend it over the ordinary integer-valued accessor, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.


MessageProducer | 95

Destination Destination {get;}

Each send call directs a message to a destination (queue or topic).

This property defines a default destination for messages that this producer sends. Individual sending calls can override this default value.

DisableMessageID bool {get; set;}

Applications that do not require message IDs can reduce overhead costs by disabling IDs (set this property to true).

DisableMessageTimestamp bool {get; set;}

Applications that do not require timestamps can reduce overhead costs by disabling timestamps (set this property to true).

Priority int {get; set;}

Priority affects the order in which the server delivers messages to consumers (higher values first).

The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.

Programs can use this property to define a default priority for messages that this producer sends. Individual sending calls can override this default value.

Member Description



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.


Programs can use this property to define a default time-to-live for messages that this producer sends. Individual sending calls can override this default value.

Whenever your application uses non-zero values for message expiration or time-to-live, you must ensure that clocks are synchronized among all the host computers that send and receive messages. Synchronize clocks to a tolerance that is a very small fraction of the smallest or time-to-live.

Member Description


MessageProducer.Close Destroy the producer object; reclaim resources. 97

MessageProducer.Send Send a message. 98


MessageProducer.Close | 97

MessageProducer.CloseMethod


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



MessageProducer.SendMethod

Declaration virtual void Send(Destination dest,Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );

virtual void Send(Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );

virtual void Send(Destination dest,Message message,int deliveryMode,int priority,long timeToLive );

virtual void Send(Message message,int deliveryMode,int priority,long timeToLive );

virtual void Send(Destination dest,Message message );

virtual void Send(Message message );

Purpose Send a message.


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.


MessageProducer.Send | 99

deliveryMode When present, the call sends the message with this delivery mode.

This argument may be either an enumerated value (see MessageDeliveryMode on page 264) or an integer (see DeliveryMode on page 260). We recommend enumerated values, because they enable .NET to do stronger type checking at compile time, which can enhance program reliability.

When absent, the call sends the message with the producer’s default delivery mode.

priority When present, the call sends the message with this priority.

Priority affects the order in which the server delivers messages to consumers (higher values first). The JMS specification defines ten levels of priority value, from zero (lowest priority) to 9 (highest priority). The specification suggests that clients consider 0–4 as gradations of normal priority, and priorities 5–9 as gradations of expedited priority.

When absent, the call sends the message with the producer’s default priority.

timeToLive When present, the call uses this value (in milliseconds) to compute the message expiration.

• If the time-to-live is non-zero, the expiration is the sum of that time-to-live and the sending client’s current time (GMT). This rule applies even within sessions with transaction semantics—the timer begins with the send call, not the commit call.


When absent, the call uses the producer’s default value to compute expiration.





QueueSenderClass

Declaration class QueueSender : MessageProducer

Purpose Send messages to a queue.

Remarks This class extends MessageProducer on page 94. It overloads more send methods, specializing the destination parameter to a queue.

Member Description

Properties

Queue Queue {get;}

Each send call directs a message to a queue.

Programs can use this property to define a default queue for messages that this producer sends. Individual sending calls can override this default value.

Programs set this queue when creating the sender, and cannot subsequently change it.


QueueSender.Send Send a message. 101


QueueSender.Send | 101

QueueSender.SendMethod

Declaration virtual void Send(Queue queue,Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );

virtual void Send(Queue queue,Message message,int deliveryMode,int priority,long timeToLive );

virtual void Send(Queue queue,Message message );

Purpose Send a message.

Remarks QueueSender inherits send methods from MessageProducer, and also defines these methods, which specialize the destination parameter to a queue; see MessageProducer.Send on page 98.


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.



When absent, the call sends the message with the sender’s default delivery mode.



See Also MessageProducer.Send on page 98



When absent, the call sends the message with the sender’s default priority.




When absent, the call uses the sender’s default value to compute expiration.




TopicPublisher | 103

TopicPublisherClass

Declaration class TopicPublisher : MessageProducer

Purpose Send a message to a topic.

Remarks This class extends MessageProducer on page 94. It overloads more send methods, specializing the destination parameter to a topic.

Member Description

Properties

Topic Topic {get;}

Each send call directs a message to a topic.

Programs can use this property to define a default topic for messages that this publisher sends. Individual sending calls can override this default value.

Programs set this topic when creating the publisher, and cannot subsequently change it.


TopicPublisher.Publish Publish a message to a topic. 104



TopicPublisher.PublishMethod

Declaration virtual void Publish(Topic topic,Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );

virtual void Publish(Message message,MessageDeliveryMode deliveryMode,int priority,long timeToLive );

virtual void Publish(Topic topic,Message message,int deliveryMode,int priority,long timeToLive );

virtual void Publish(Message message,int deliveryMode,int priority,long timeToLive );

virtual void Publish(Topic topic,Message message );

virtual void Publish(Message message );

Purpose Publish a message to a topic.

Remarks These methods are parallel to the send methods that TopicPublisher inherits from MessageProducer, and they accomplish the same goal—sending messages.


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.


TopicPublisher.Publish | 105

See Also MessageProducer.Send on page 98



When absent, the call sends the message with the publisher’s default delivery mode.



When absent, the call sends the message with the publisher’s default priority.




When absent, the call uses the publisher’s default value to compute expiration.






| 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


108 | Chapter 6 Requestor

QueueRequestorClass

Declaration class QueueRequestor

Purpose Encapsulate request-reply semantics, sending requests to a queue.

Remarks We recommend that programs follow these steps:

1. Create a QueueSession, and use it to create a Queue for requests and replies.

2. Create a QueueRequestor, using the queue session and queue as arguments.

3. Send a request and receive a reply. You may repeat this step for several request and reply pairs.

4. Close the requestor object. The Close method also closes the requestor’s session as a side effect.

See Also Queue on page 70QueueSession on page 196


QueueRequestor Create a queue requestor. 109

QueueRequestor.Close Close a queue requestor. 110

QueueRequestor.Request Send a request message; wait for a reply and return it.

111


QueueRequestor | 109

QueueRequestorConstructor

Declaration QueueRequestor (QueueSession session,Queue queue );

Purpose Create a queue requestor.


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.



QueueRequestor.CloseMethod

Declaration void Close ();

Purpose Close a queue requestor.

Remarks This method also closes the requestor’s session as a side effect.


QueueRequestor.Request | 111

QueueRequestor.RequestMethod

Declaration Message Request(Message message );

Purpose Send a request message; wait for a reply and return it.

Remarks The requestor receives only the first reply. It discards other replies that arrive subsequently.


message Send this request message.



TopicRequestorClass

Declaration class TopicRequestor

Purpose Encapsulate request-reply semantics, sending requests to a topic.

Remarks We recommend that programs follow these steps:

1. Create a TopicSession, and use it to create a Topic for requests and replies.

2. Create a TopicRequestor, using the topic session and topic as arguments.

3. Send a request and receive a reply. You may repeat this step for several request and reply pairs.

4. Close the requestor object. The Close method also closes the requestor’s session as a side effect.

See Also Topic on page 76TopicSession on page 197


TopicRequestor Create a topic requestor. 113

TopicRequestor.Close Close a topic requestor. 114

TopicRequestor.Request Send a request message; wait for a reply and return it.

115


TopicRequestor | 113

TopicRequestorConstructor

Declaration TopicRequestor (TopicSession session,Topic topic );

Purpose Create a topic requestor.


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.



TopicRequestor.CloseMethod

Declaration void Close ();

Purpose Close a topic requestor.

Remarks This method also closes the requestor’s session as a side effect.


TopicRequestor.Request | 115

TopicRequestor.RequestMethod

Declaration Message Request(Message message );

Purpose Send a request message; wait for a reply and return it.

Remarks The requestor receives only the first reply. It discards other replies that arrive subsequently.


message Send this request message.




| 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


118 | Chapter 7 Connection

ConnectionClass

Declaration class Connection

Purpose Encapsulate a server connection.

Subclasses QueueConnection on page 126TopicConnection on page 128

Remarks When a program first opens a connection, the connection is stopped—that is, it does not deliver inbound messages. To begin the flow of inbound messages, the program must explicitly call the Start method. (Outbound messages flow even before calling Start.)

The EMS .NET API does not support the optional methods createConnectionConsumer and createDurableConnectionConsumer.

AsynchronousExceptions

When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program (synchronously) by throwing exceptions.

However, when a program uses a connection only to receive messages, the client cannot catch such exceptions. Instead, programs can handle such exceptions asynchronously in one of two idioms. Programmers may select either idiom—but not both (which would cause duplicate exception processing, with undefined behavior).

• ExceptionHandler events detect this type of problem in a .NET programming idiom.

• In contrast, the ExceptionListener property mimics the way in which JMS provides similar functionality in a Java programming idiom.

Member Description

Events

ExceptionHandler EMSExceptionHandler

The client library raises an event if it detects a problem with the connection. The program implements a handler delegate to processes it asynchronously, and registers the delegate here. See Asynchronous Exceptions, above. See EMSExceptionHandler on page 130.


Connection | 119

Properties

ActiveURL string {get;}

This property holds the URL of the server at the other endpoint of the connection. When the connection interacts with several servers in a fault-tolerant arrangement, this property indicates the current active server.

ClientID string {get; set;}

This property holds the unique client ID of the connection.

Client IDs partition the namespace of durable subscribers; see Session.CreateDurableSubscriber on page 181.

Administrators can configure ConnectionFactory objects to assign client IDs to new connections. Alternatively, administrators can allow client programs to assign their own IDs. If the factory does not assign an ID, the program may set this property. However, it is illegal to overwrite an existing client ID value, and or to set this property after using the connection in any way (for example, after creating a session, or starting the connection); attempting to set this property in these situations results in IllegalStateException.

ExceptionListener IExceptionListener {get; set;}

This is an alternate pathway for alerting a client program of connection problems. The program implements the exception listener interface, and registers an exception listener object by setting this property. When the client library detects a connection problem, it calls the listener’s onException method with an exception argument that details the problem.

See Asynchronous Exceptions, above. See IExceptionListener on page 133.

IsClosed bool {get;}

This property is true if the connection has been closed; otherwise false.

IsSecure bool {get;}

This property is true if the connection communicates with a secure protocol; otherwise false.

Member Description



MetaData ConnectionMetaData {get;}

Programs can get the connection’s metadata object.

Member Description


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


Connection.Close | 121

Connection.CloseMethod

Declaration virtual void Close();

Purpose Close the connection; reclaim resources.

Remarks Closing the connection is sufficient to reclaim all of its resources; you need not separately close the sessions, producers, and consumers associated with the connection.

Closing a connection deletes all temporary destinations associated with the connection.

Blocking If any message listener or receive call associated with the connection is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes—that is, until all message listeners and receive calls have returned.

Acknowledge Closing a connection does not force acknowledgment in client-acknowledged sessions. When the program still has a message that it received from a connection that has since closed, its Message.Acknowledge method throws IllegalStateException.

Transactions Closing a connection rolls back all open transactions in all sessions associated with the connection.

See Also Message.Acknowledge on page 25MessageConsumer on page 80MessageProducer on page 94Destination on page 69Session on page 170IMessageListener on page 90IllegalStateException on page 312



Connection.CreateSessionMethod

Declaration virtual Session CreateSession(bool transacted,QueueSession acknowledgeMode );

virtual Session CreateSession(bool transacted,int acknowledgeMode );

Purpose Create a session object.

Remarks The new session uses the connection for all server communications.

See Also Message.Acknowledge on page 25Session on page 170Acknowledge Modes on page 174QueueSession on page 196


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.


Connection.Start | 123

Connection.StartMethod

Declaration virtual void Start();

Purpose Start delivering inbound messages.

Remarks When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this method to explicitly start it.

If the connection is not stopped, this call has no effect.

Outbound messages flow even before calling Start.

See Also Connection.Stop on page 124



Connection.StopMethod

Declaration virtual void Stop();

Purpose Stop delivering inbound messages.

Remarks This call temporarily stops the connection from delivering inbound messages. A program can restart delivery by calling Connection.Start.

When a connection is created, it is stopped. It does not deliver inbound messages until the program calls this method to explicitly start it.

If the connection is already stopped, this call has no effect.

Effect When this call returns, the connection has stopped delivery to all consumers associated with the connection:

• Messages do not arrive to trigger asynchronous message handler events, nor message listeners.

• Synchronous receive methods block. If their timeout intervals expire, they return null.

Blocking If any message listener or receive call associated with the connection is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes—that is, until all message listeners and receive calls have returned.

However, the stopped connection prevents the client program from processing any new messages.

Sending A stopped connection can still send outbound messages.

See Also Connection.Start on page 123


ConnectionMetaData | 125

ConnectionMetaDataClass

Declaration class ConnectionMetaData

Purpose Information about the provider.

Remarks Programs can retrieve this object from a connection; see MetaData on page 120.

Member Description

Properties

JMSXPropertyNames System.Collections.IEnumerator {get;}

Enumerates the JMS message properties; see JMS Properties on page 17.

MajorVersion int {get;}

Major version number of the JMS specification that the provider supports.

MinorVersion int {get;}

Minor version number of the JMS specification that the provider supports.

Version string {get;}

Version number of the JMS specification that the provider supports.

ProviderMajorVersion int {get;}

Major version number of the provider (EMS).

ProviderMinorVersion int {get;}

Minor version number of the provider (EMS).

ProviderVersion string {get;}

Version number of the provider (EMS).

ProviderName string {get;}

Vendor name of the provider.



QueueConnectionClass

Declaration class QueueConnection : Connection

Purpose Backward compatibility. Connection restricted to queue operations.

Remarks This class supports existing programs that use it.

For new programs, we recommend using the more general class, Connection on page 118, instead.


QueueConnection.CreateQueueSession Backward compatibility. Create a queue session object.

127


QueueConnection.CreateQueueSession | 127

QueueConnection.CreateQueueSessionMethod

Declaration virtual QueueSession CreateQueueSession(bool transacted,QueueSession acknowledgeMode );

virtual QueueSession CreateQueueSession(bool transacted,int acknowledgeMode );

Purpose Backward compatibility. Create a queue session object.

Remarks The new queue session uses the connection for all server communications.

See Also Message.Acknowledge on page 25QueueSession on page 196Acknowledge Modes on page 174QueueSession on page 196









TopicConnectionClass

Declaration class TopicConnection : Connection

Purpose Backward compatibility. Connection restricted to topic operations.


For new programs, we recommend using the more general class, Connection on page 118, instead.


TopicConnection.CreateTopicSession Backward compatibility. Create a topic session object.

129


TopicConnection.CreateTopicSession | 129

TopicConnection.CreateTopicSessionMethod

Declaration virtual TopicSession CreateTopicSession(bool transacted,QueueSession acknowledgeMode );

virtual TopicSession CreateTopicSession(bool transacted,int acknowledgeMode );

Purpose Backward compatibility. Create a topic session object.

Remarks The new topic session uses the connection for all server communications.

See Also Message.Acknowledge on page 25TopicSession on page 197Acknowledge Modes on page 174QueueSession on page 196









EMSExceptionHandlerDelegate

Declaration delegate void EMSExceptionHandler(object sender,EMSExceptionEventArgs args );

Purpose Asynchronously detect problems with connections.

Remarks When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program by throwing exceptions. However, when a program uses a connection only to receive messages, the client cannot catch such exceptions.

This delegate provides an alternate pathway for alerting a client program of connection problems. The program implements this delegate, and registers it with the connection. When the client library detects a connection problem, it raises an event. This delegate processes the event, which contains an exception that details the problem.

EMSExceptionHandler detects this type of problem in a .NET programming idiom. In contrast, IExceptionListener mimics the way in which JMS provides similar functionality in a Java programming idiom. Programmers may select either idiom—but not both (which would cause duplicate exception processing, with undefined behavior).

Example 2 Exception Event Handler...connection.ExceptionHandler += new EMSExceptionHandler(handleEx);...private void handleEx(object sender, EMSExceptionEventArgs arg){

EMSException e = arg.Exception;Console.WriteLine("Exception: " + e.Message);

}...

See Also Connection on page 118EMSExceptionHandler on page 130EMSExceptionEventArgs on page 131


sender The problematic connection object.

args The event, which contains the exception object.


EMSExceptionEventArgs | 131

EMSExceptionEventArgsClass

Declaration class EMSMessageEventArgs : EventArgs

Purpose Present a connection problem as a .NET event.

Remarks EMSExceptionHandler delegates receive this object as an argument.

See Also EMSExceptionHandler on page 130

Member Description

Properties

Exception EMSException {get;}

Programs can get the exception that details the problem.


EMSMessageEventArgs Constructor. 89



EMSExceptionEventArgsConstructor

Declaration EMSExceptionEventArgs(EMSException emse );

Purpose Create an exception event.


emse The new event encapsulates this exception, and signals its arrival.


IExceptionListener | 133

IExceptionListenerInterface

Declaration interface IExceptionListener

Purpose Asynchronously detect problems with connections.

Remarks When a program uses a connection to send messages, the send calls can detect problems with the connection, and notify the client program by throwing exceptions. However, when a program uses a connection only to receive messages, the client cannot catch such exceptions.

This interface provides an alternate pathway for alerting a client program of connection problems. The program implements this interface, and registers an exception listener with the connection object. When the client library detects a connection problem, it calls the listener’s onException method with an exception argument that details the problem.

IExceptionListener mimics the way in which JMS detects this type of problem in a Java programming idiom. In contrast, EMSExceptionHandler provides similar functionality in a .NET idiom. Programmers may select either idiom—but not both (which would cause duplicate exception processing, with undefined behavior).

See Also Connection on page 118EMSExceptionHandler on page 130


IExceptionListener.OnException Handle connection exceptions asynchronously. 134



IExceptionListener.OnExceptionMethod

Declaration void OnException(EMSException exception );

Purpose Handle connection exceptions asynchronously.


exception Handle this exception.


| 135




| 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


138 | Chapter 8 Connection Factory

ConnectionFactoryClass

Declaration class ConnectionFactory

Purpose Administered object for creating server connections.

Subclasses QueueConnectionFactory on page 161TopicConnectionFactory on page 164

Remarks Connection factories are administered objects. They support concurrent use.

Administrators define connection factories in a repository. Each connection factory has administrative parameters that guide the creation of server connections. Usage follows either of two models:

EMS Server You can use the EMS server as a name service provider—one tibemsd process provides both the name repository and the message service. Administrators define factories in the name repository. Client programs create connection factory objects with the URL of the repository, and call the ConnectionFactory.CreateConnection method. This method automatically accesses the corresponding factory in the repository, and uses it to create a connection to the message service.

Separate JNDIRepository

Administrators define factories in a JNDI repository. Client programs call LookupContext.Lookup to retrieve factories, and use them to create connections to the server.

Member Description

Properties

Metric QueueConnectionFactory Metric {get; set;}

When the connection factory balances the client load among several servers, it uses this metric to determine the least loaded server, so the connection factory can create a connection to it. For values, see QueueConnectionFactory on page 161.


ConnectionFactory | 139


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.



AdministeredObjects

Administered objects let administrators configure EMS behavior at the enterprise level. Administrators define these objects, and client programs use them. This arrangement relieves program developers and end users of the responsibility for correct configuration.


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.



ConnectionFactory | 141

ConnectionFactoryConstructor

Declaration ConnectionFactory(string serverUrl,string clientId,Hashtable properties );

ConnectionFactory(string serverUrl,string clientId );

ConnectionFactory(string serverUrl );

ConnectionFactory();

Purpose Create a connection factory.

Remarks When administrators define factories in the EMS server, these constructors automatically access the corresponding objects in the repository.

Reconnect andFault Tolerance

To enable reconnection behavior and fault tolerance, the serverURL parameter must be a comma-separated list of two or more URLs. In a situation with only one server, you may supply two copies of that server’s URL to enable client reconnection (for example, tcp://localhost:7222,tcp://localhost:7222).



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.



ConnectionFactory.CloneMethod


Purpose Overrides the cloning process

ConnectionFactory.CreateConnectionMethod

Declaration Connection CreateConnection(string userName,string password );

Connection CreateConnection();

Purpose Create a connection object.

When the identity parameters are absent, the connection object presents a default user identity. If the server configuration permits that user, then the call succeeds.

See Also Connection on page 118


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.


ConnectionFactory.GetSSLProxyHost | 143

ConnectionFactory.GetSSLProxyHostMethod

Declaration string GetSSLProxyHost();

Purpose Get the SSL proxy host from this connection factory.

ConnectionFactory.GetSSLProxyPasswordMethod

Declaration string GetSSLProxyPassword();

Purpose Get the SSL proxy password from a connection factory.

ConnectionFactory.GetSSLProxyPortMethod

Declaration int GetSSLProxyPort();

Purpose Get the SSL proxy port from this connection factory.

ConnectionFactory.GetSSLProxyUserMethod

Declaration string GetSSLProxyUser();

Purpose Get the SSL proxy username from a connection factory.



ConnectionFactory.SetCertificateStoreTypeMethod

Declaration void SetCertificateStoreType(EMSSSLStoreType type,object storeInfo

);

Purpose Set the certificate store type and info.


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.


ConnectionFactory.SetClientID | 145

ConnectionFactory.SetClientIDMethod

Declaration void SetClientID(string clientID);

Purpose Set the client id.

Throws EMSException if the specified client id already exists.


clientID Client ID.



ConnectionFactory.SetClientTracerMethod

Declaration void SetClientTracer(StreamWriter tracer);

Purpose Set the client tracer to given output stream.

Remarks Client tracing prints loaded certificates and information about the SSL handshake errors and results.


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


ConnectionFactory.SetConnAttemptCount | 147

ConnectionFactory.SetConnAttemptCountMethod

Declaration void SetConnAttemptCount(int attempts);

Purpose Set the number of connection attempts.

Remarks See Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide for details.


attempts Number of connection attempts.



ConnectionFactory.SetConnAttemptDelayMethod

Declaration void SetConnAttemptDelay(int delay);

Purpose Set the delay between connection attempts.

Remarks See Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide for details.


delay Time (in milliseconds) of the delay between connection attempts.


ConnectionFactory.SetConnAttemptTimeout | 149

ConnectionFactory.SetConnAttemptTimeoutMethod

Declaration void SetConnAttemptTimeout(int timeout);

Purpose Set the Connect Attempt timeout for a given connection.

Remarks This timeout is per url and per connect_attempt. For example, to specify two connect attempts for a given url, then for each attempt the client will wait for the period specified by the connect attempt timeout for the connection to be established. If no connection is established within that the specified timeframe, the client connection attempt is terminated.

See Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide for details.


timeout Timeout (in milliseconds) for the connection.



ConnectionFactory.SetHostNameVerifierMethod

Declaration void SetHostNameVerifier(EMSSSLHostNameVerifier verifier

);

Purpose Set the custom host name verifier.


verifier Host name verifier. Set to null to remove custom host name verifier.

See EMSSSLHostNameVerifier on page 255 for details.


ConnectionFactory.SetMetric | 151

ConnectionFactory.SetMetricMethod

Declaration void SetMetric(int metric);

Purpose Set the load balance metric.

Throws EMSException if invalid metric is passed.


metric Load balance metric.



ConnectionFactory.SetReconnAttemptCountMethod

Declaration void SetReconnAttemptCount(int attempts);

Purpose Set the number of reconnect attempts.

Remarks See Reconnect Timeout in the TIBCO Enterprise Message Service User’s Guide for details.


attempts Number of reconnection attempts.


ConnectionFactory.SetReconnAttemptDelay | 153

ConnectionFactory.SetReconnAttemptDelayMethod

Declaration void SetConnAttemptDelay( int delay);

Purpose Set the delay between reconnection attempts.


attempts Time (in milliseconds) of the delay between reconnection attempts.



ConnectionFactory.SetReconnAttemptTimeoutMethod

Declaration void SetReconnAttemptTimeout(int timeout);

Purpose Set the Reconnect Attempt timeout for a given connection.

Remarks This timeout is per url and per reconnect_attempt. For example, to specify two reconnect attempts for a given url, then for each attempt the client will wait for the period specified by the reconnect attempt timeout for the connection to be established. If no reconnection is established within that the specified timeframe, the reconnection attempt is terminated.


timeout Timeout (in milliseconds) for the reconnection attempt.


ConnectionFactory.SetServerUrl | 155

ConnectionFactory.SetServerUrlMethod

Declaration void SetServerUrl(string serverUrl);

Purpose Set the server URL.

Remarks The server URL is of the form:

protocol://hostName:portNumber

For example:

tcp://localhost:7222

The server URL for a fault-tolerant configuration is a string with multiple URL's that are comma separated.

For example:

tcp://localhost:7222,tcp://localhost:7224.

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


serverUrl The server URL.



ConnectionFactory.SetSSLAuthOnlyMethod

Declaration SetSSLAuthOnly (bool authOnly);

Purpose Enable or disable auth only for the SSL connection.

Remarks For the client and server to require an SSL connection only to perform authentication, the ssl_auth_only parameter needs to be set on the server and AUTH_ONLY needs to be set by the client. Setting these flags on both the server and client side indicates that the SSL connection is only used to only perform authentication. Once authentication is complete, the client switches to a regular TCP connection to communicate with the server.

See the SSL Authentication Only section in the TIBCO Enterprise Message Service User’s Guide for details.

See Also EMSSSL.SetAuthOnly on page 242EMSSSL.GetAuthOnly on page 241


authOnly • When true, AUTH_ONLY is enabled.

• When false, (the default) AUTH_ONLY is disabled.


ConnectionFactory.SetSSLProxy | 157

ConnectionFactory.SetSSLProxyMethod

Declaration void SetSSLProxy(string host,int port

);

Purpose Set the connection factory's parameters for connecting through an SSL proxy.

Remarks An SSL proxy lets an EMS application create an SSL connection to an EMS server, even though a firewall separates the application from the server. The proxy usually runs within the firewall's DMZ. A connection factory contacts the SSL proxy, requesting an SSL connection to the server. The proxy authenticates the application program, and mediates the initial SSL negotiation between application and server. After the SSL connection is established, the application and server use it to communicate directly with one another.

Throws EMSException if the proxy host is null or empty, the port is zero or the protocol of the connection factory's URL is not SSL.


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.



ConnectionFactory.SetSSLProxyAuthMethod

Declaration public void SetSSLProxyAuth(string username,string password

);

Purpose Set a connection factory's username and password for connecting through an SSL proxy.

Remarks When a connection factory establishes an EMS server connection through an SSL proxy host, the proxy might first require authentication before facilitating a connection. When required, use this call to set that authentication data on the connection factory.

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

This proxy authentication data is distinct from the server authentication data, and from the SSL private key encryption password.


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.


ConnectionFactory.SetSSLTrace | 159

ConnectionFactory.SetSSLTraceMethod

Declaration SetSSLTrace (bool tracing);

Purpose Enable or disable tracing on the client side.

Remarks Tracing will show information during the SSL handshake and on messages received and sent by the SSL link.

ConnectionFactory.SetTargetHostNameMethod

Declaration void SetTargetHostName(string targetHostName);

Purpose Set the name of the target EMS server.

Remarks This is a required parameter for all .NET SSL connections. Because System.Net.Security.SslStream requires a target host, this value is required.


tracing • When true, tracing is enabled.

• When false, (the default) tracing is disabled.


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.



ConnectionFactory.SetUserNameMethod

Declaration void SetUserName(string username);

Purpose Set user name.

ConnectionFactory.SetUserPasswordMethod

Declaration void SetUserPassword(string password);

Purpose Set user password.


username User name.


password Password.


QueueConnectionFactory | 161

QueueConnectionFactoryClass

Declaration class QueueConnectionFactory : ConnectionFactory

Purpose Backward compatibility. Administered object for creating queue connections.


For new programs, we recommend using the more general class, ConnectionFactory on page 138, instead.


QueueConnectionFactory Constructor.

Same method signatures as the constructors for ConnectionFactory on page 141.

—

QueueConnectionFactory.CreateQueue

Connection

Create a queue connection object. 162

QueueConnectionFactory.Clone Implementation of ICloneable.Clone. 163



QueueConnectionFactory.CreateQueueConnectionMethod

Declaration QueueConnection CreateQueueConnection(string userName,string password );

QueueConnection CreateQueueConnection();

Purpose Create a queue connection object.

Remarks When the identity parameters are absent, the connection object presents a default user identity. If the server configuration permits that user, then the call succeeds.

See Also QueueConnection on page 126


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.


QueueConnectionFactory.Clone | 163

QueueConnectionFactory.CloneMethod


Purpose Implementation of ICloneable.Clone.

Remarks Overrides the Clone process. Returns an object that is a clone of this QueueConnectionFactory instance.



TopicConnectionFactoryClass

Declaration class TopicConnectionFactory : ConnectionFactory

Purpose Backward compatibility. Administered object for creating topic connections.


For new programs, we recommend using the more general class, ConnectionFactory on page 138, instead.


TopicConnectionFactory Constructor.

Same method signatures as the constructors for ConnectionFactory on page 141.

—

TopicConnectionFactory.CreateTopic

Connection

Create a topic connection object. 165

TopicConnectionFactory.Clone Implementation of ICloneable.Clone. 166


TopicConnectionFactory.CreateTopicConnection | 165

TopicConnectionFactory.CreateTopicConnectionMethod

Declaration TopicConnection CreateTopicConnection(string userName,string password );

TopicConnection CreateTopicConnection();

Purpose Create a topic connection object.

Remarks When the identity parameters are absent, the connection object presents a default user identity. If the server configuration permits that user, then the call succeeds.

See Also TopicConnection on page 128


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.



TopicConnectionFactory.CloneMethod


Purpose Implementation of ICloneable.Clone.

Remarks Overrides the Clone process. Returns an object that is a clone of this TopicConnectionFactory instance.


FactoryLoadBalanceMetric | 167

FactoryLoadBalanceMetricClass

Declaration enum FactoryLoadBalanceMetric

Purpose Define enumerated load balancing constants.

Remarks When a connection factory balances the client load among several servers, it uses this metric to determine the least loaded server, so the connection factory can create a connection to it.

See Also ConnectionFactory on page 138

Member Description

Fields

None Indicates absence of any load balancing metric.

Connections The connection factory balances the connection load among several servers by creating a connection to the server with the fewest number of connections.

ByteRate The connection factory balances the connection load among several servers by creating a connection to the server with the lowest total byte rate (input and output).




| 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


170 | Chapter 9 Session

SessionClass

Declaration class Session

Purpose Main organizing context for message activity.

Subclasses QueueSession on page 196TopicSession on page 197

Remarks Sessions combine several roles:

• Factory for message producers and consumers

• Factory for message objects

• Factory for temporary destinations

• Factory for dynamic destinations

• Factory for queue browsers

• Serializer for inbound and outbound messages

• Serializer for asynchronous message events (or message listeners) of its consumer objects

• Cache for inbound messages (until the program acknowledges them).

• Transaction support (when enabled).

Single Thread The JMS specification restricts programs to use each session within a single thread.

AssociatedObjects

The same single-thread restriction applies to objects associated with a session—namely, messages, message consumers, durable subscribers, message producers, queue browsers, and temporary destinations (however, static and dynamic destinations are exempt from this restriction).

Corollary One consequence of this rule is that all the consumers of a session must deliver messages in the same mode—either synchronously or asynchronously.

Asynchronous In asynchronous delivery, the program registers message handler events or message listeners with the session’s consumer objects. An internal dispatcher thread delivers messages to those event handlers or listeners (in all the session’s consumer objects). No other thread may use the session (nor objects created by the session).


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.



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.


Member Description


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


Session | 173

Destinations

Session.CreateBrowser Create a queue browser. 178

Session.CreateTemporaryQueue Create a temporary queue. 188

Session.CreateTemporaryTopic Create a temporary topic. 189

Session.CreateQueue Create a queue. 186

Session.CreateTopic Create a topic. 191

Consumers & Producers

Session.CreateConsumer Create a message consumer. 180

Session.CreateDurableSubscriber Create a durable topic subscriber. 181

Session.CreateProducer Create a message producer. 185

Session.Unsubscribe Unsubscribe a durable topic subscription. 195

Transactions

Session.Commit Commit the open transaction. 177

Session.Rollback Roll back messages in the current transaction. 193

Other

Session.Close Close a session; reclaim resources. 176

Session.Recover Recover from undetermined state during message processing.

192

Session.Run Obsolete. Do not call. 194




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.


Session | 175

EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE int

In EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE mode, the client program lazily acknowledges only the individual message, by calling Message.Acknowledge on page 25. The client may acknowledge messages in any order.

Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message.


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.


Field Description



Session.CloseMethod


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.


Session.Commit | 177

Session.CommitMethod

Declaration virtual void Commit();

Purpose Commit the open transaction.

Remarks A session (with transaction semantics) always has exactly one open transaction. Message operations associated with the session become part of that transaction. This call commits all the messages within the transaction, and releases any locks. Then it opens a new transaction.

Throws EMSException on page 306TransactionRolledBackException on page 327IllegalStateException on page 312



Session.CreateBrowserMethod

Declaration QueueBrowser CreateBrowser(Queue queue,string messageSelector );

QueueBrowser CreateBrowser(Queue queue );

Purpose Create a queue browser.

Throws EMSException on page 306InvalidDestinationException on page 314InvalidSelectorException on page 316

See Also Queue on page 70QueueBrowser on page 202


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.


Session.CreateBytesMessage | 179

Session.CreateBytesMessageMethod

Declaration BytesMessage CreateBytesMessage();

Purpose Create a byte array message.

See Also BytesMessage on page 32



Session.CreateConsumerMethod

Declaration MessageConsumer CreateConsumer(Destination dest,string messageSelector,bool noLocal );

MessageConsumer CreateConsumer(Destination dest,string messageSelector );

MessageConsumer CreateConsumer(Destination dest );

Purpose Create a message consumer.

Throws EMSException on page 306IllegalStateException on page 312InvalidDestinationException on page 314InvalidSelectorException on page 316

See Also Destination on page 69


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.


Session.CreateDurableSubscriber | 181

Session.CreateDurableSubscriberMethod

Declaration TopicSubscriber CreateDurableSubscriber(Topic topic,string name,string messageSelector,bool noLocal );

TopicSubscriber CreateDurableSubscriber(Topic topic,string name );

Purpose Create a durable topic subscriber.

Remarks The server associates a durable subscription with at most one subscriber object at a time. When a subscriber object exists, the subscription is active, and the server delivers messages to it; when no subscriber object exists, the subscription is inactive.

Durable subscriptions guarantee message delivery across periods during which the subscriber is inactive. The server retains unacknowledged messages until the subscriber acknowledges them, or until the messages expire.

SubscriptionContinuity

Continuity across inactive periods uses two data items from the client:

• Subscription Name a parameter of this method

• Client ID an optional property of the Connection (used only when supplied)


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.



The server uses one or both of these two items to match a subscriber object with its subscription. If a matching subscription exists, and it is inactive, then the server associates it with the subscriber (and the subscription becomes active). The server delivers unacknowledged messages to the subscriber.

If a matching subscription exists, but it is already active, this method throws EMSException.

If a matching subscription to the topic does not yet exist, the server creates one.

MatchingClient ID

• If the Connection’s client ID is non-null when a session creates a durable subscription, then only sessions of a connection with the same client ID can attach to that subscription.

• If the Connection’s client ID is null when a session creates a durable subscription, then any session can attach to that subscription (to receive its messages).

Changing Topicor Selector

Notice that the server does not use the topic and message selector arguments to match a subscriber to an existing subscription. As a result, client programs can change a subscription by altering either or both of these arguments. The effect is equivalent to deleting the existing subscription (from the server) and creating a new one (albeit with the same client ID and subscription name).

Throws EMSException on page 306IllegalStateException on page 312InvalidDestinationException on page 314InvalidSelectorException on page 316

See Also Topic on page 76Connection on page 118


Session.CreateMapMessage | 183

Session.CreateMapMessageMethod

Declaration MapMessage CreateMapMessage();

Purpose Create a map message.

See Also MapMessage on page 41



Session.CreateObjectMessageMethod

Declaration ObjectMessage CreateObjectMessage(object obj );

ObjectMessage CreateObjectMessage();

Purpose Create an object message.

See Also ObjectMessage on page 48


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


Session.CreateProducer | 185

Session.CreateProducerMethod

Declaration MessageProducer CreateProducer(Destination dest );

Purpose Create a message producer.

Throws EMSException on page 306InvalidDestinationException on page 314

See Also MessageProducer on page 94


dest When non-null, the producer sends messages to this destination.

When null, the client program must specify the destination for each message individually.



Session.CreateQueueMethod

Declaration Queue CreateQueue(string queueName );

Purpose Create a queue.

Remarks If the named queue already exists at the server, then this method returns that queue. (That queue can be either static or dynamic.)

If the named queue does not yet exist at the server, and the server allows dynamic queues, then this method creates a dynamic queue.

Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.

See Also Queue on page 70


queueName Get or create the queue with this name.


Session.CreateStreamMessage | 187

Session.CreateStreamMessageMethod

Declaration StreamMessage CreateStreamMessage();

Purpose Create a stream message.

See Also StreamMessage on page 50



Session.CreateTemporaryQueueMethod

Declaration TemporaryQueue CreateTemporaryQueue();

Purpose Create a temporary queue.

Remarks A temporary queue lasts no longer than the connection. That is, when the connection is closed or broken, the server deletes temporary queues associated with the connection.

See Also TemporaryQueue on page 72


Session.CreateTemporaryTopic | 189

Session.CreateTemporaryTopicMethod

Declaration TemporaryTopic CreateTemporaryTopic();

Purpose Create a temporary topic.

Remarks A temporary topic lasts no longer than the connection. That is, when the connection is closed or broken, the server deletes temporary topic associated with the connection.

See Also TemporaryTopic on page 74



Session.CreateTextMessageMethod

Declaration TextMessage CreateTextMessage(string text);

TextMessage CreateTextMessage();

Purpose Create a text message.

See Also TextMessage on page 58


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


Session.CreateTopic | 191

Session.CreateTopicMethod

Declaration Topic CreateTopic(string topicName );

Purpose Create a topic.

Remarks If the named topic already exists at the server, then this method returns that topic. (That topic can be either static or dynamic.)

If the named topic does not yet exist at the server, and the server allows dynamic topics, then this method creates a dynamic topic.

Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.

See Also Topic on page 76


topicName Get or create the topic with this name.



Session.RecoverMethod

Declaration void Recover();

Purpose Recover from undetermined state during message processing.

Remarks Exceptions during message processing can sometimes leave a program in an ambiguous state. For example, some messages might be partially processed. This method lets a program return to an unambiguous state—the point within the message stream when the program last acknowledged the receipt of inbound messages. Programs can then review the messages delivered since that point (they are marked as redelivered), and resolve ambiguities about message processing.

Programs can also use this method to resolve similar ambiguities after a Connection stops delivering messages, and then starts again.

Operation This method requests that the server do this sequence of actions:

1. Stop message delivery within the session.

2. Mark as redelivered, any messages that the server has attempted to deliver to the session, but for which it has not received acknowledgement (that is, messages for which processing state is ambiguous).

According to the JMS specification, the server need not redeliver messages in the same order as it first delivered them.

3. Restart message delivery (including messages marked as redelivered in step 2).

When a session has transactional semantics, this method throws IllegalStateException (commit and rollback are more appropriate for transactions).

Throws EMSException on page 306IllegalStateException on page 312


Session.Rollback | 193

Session.RollbackMethod

Declaration virtual void Rollback();

Purpose Roll back messages in the current transaction.

Remarks When a session does not have transactional semantics, this method throws IllegalStateException.

Messages sent to a queue with prefetch=none and maxRedelivery=number properties are not received number times by an EMS application that receives in a loop and does an XA rollback after the XA prepare phase.

Throws EMSException on page 306IllegalStateException on page 312



Session.RunMethod

Declaration void Run();

Purpose Obsolete. Do not call.


Session.Unsubscribe | 195

Session.UnsubscribeMethod

Declaration void Unsubscribe(string name );

Purpose Unsubscribe a durable topic subscription.

Remarks This method deletes the subscription from the server.

It is illegal to delete an active subscription—that is, while a MessageConsumer or TopicSubscriber exists. Attempting to do so results in EMSException.

It is illegal to delete a subscription while one of its messages is either unacknowledged, or uncommitted (in the current transaction). Attempting to do so results in EMSException.

If the session is closed, this method throws IllegalStateException.

Throws EMSException on page 306IllegalStateException on page 312InvalidDestinationException on page 314

See Also MessageConsumer on page 80TopicSubscriber on page 86Topic on page 76Session.CreateDurableSubscriber on page 181


name This name lets the server locate the subscription.



QueueSessionClass

Declaration class QueueSession : Session

Purpose Session restricted to queues.

Remarks Use this class with QueueRequestor objects.

Otherwise, when coding new programs, use the more general class, Session on page 170. Nonetheless, for backward compatibility, this class also supports existing programs that use it (rather than generic sessions).

See Also QueueRequestor on page 108


TopicSession | 197

TopicSessionClass

Declaration class TopicSession : Session

Purpose Session restricted to topics.

Remarks Use this class with TopicRequestor objects.

Otherwise, when coding new programs, use the more general class, Session on page 170. Nonetheless, for backward compatibility, this class also supports existing programs that use it (rather than generic sessions).

See Also TopicRequestor on page 112



SessionModeEnumeration

Declaration enum SessionMode

Purpose Enumerate constants associated with sessions.

Members Description

SessionTransacted The IsTransacted property has this value if the session uses transaction semantics.

Acknowledge Modes

AutoAcknowledge In this mode, the session automatically acknowledges a message when message processing is finished—that is, in either of these methods returns successfully:

• synchronous Receive call

• asynchronous listener handler

ClientAcknowledge In this mode, the client program acknowledges receipt by calling Message.Acknowledge on page 25. Each call acknowledges all messages received so far.

DupsOkAcknowledge As with AutoAcknowledge, the session automatically acknowledges messages. However, it may do so lazily. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. Lazy acknowledgement can reduce session overhead.

ExplicitClientAcknowledge As with ClientAcknowledge, the client program acknowledges receipt by calling Message.Acknowledge on page 25. However, each call acknowledges only the individual message. The client may acknowledge messages in any order.



SessionMode | 199

ExplicitClientDupsOkAcknowledge In this mode, the client program lazily acknowledges only the individual message, by calling Message.Acknowledge on page 25. The client may acknowledge messages in any order.

Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message.


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.


Members Description




| 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


202 | Chapter 10 Queue Browser

QueueBrowserClass

Declaration class QueueBrowser : IEnumerator

Purpose Enumerate the messages in a queue without consuming them.

Remarks A browser is a dynamic enumerator of the queue (not a static snapshot). The queue is at the server, and its contents change as message arrive and consumers remove them. Meanwhile, while the browser is at the client. The method QueueBrowser.MoveNext asks the server for the next message after Current—that is, the next message that is still in the queue.

The browser can enumerate messages in a queue, or a subset filtered by a message selector.

Sessions serve as factories for queue browsers; see Session.CreateBrowser on page 178.

Member Description

Properties

Current object {get;}

This property presents the current message in the browser’s enumeration, but accessing the property does not consume that message.

The method QueueBrowser.MoveNext advances the current message.

MessageSelector string {get;}

The browser’s message selector expression filters the messages that the browser presents.

Queue Queue {get;}

The queue that this browser scans.


QueueBrowser.Close Close the browser; reclaim resources. 204


QueueBrowser | 203

See Also Session.CreateBrowser on page 178

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

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

206

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

207




QueueBrowser.CloseMethod


Purpose Close the browser; reclaim resources.


QueueBrowser.GetEnumerator | 205

QueueBrowser.GetEnumeratorMethod

Declaration IEnumerator GetEnumerator();

Purpose Get an enumerator of messages in the queue.

Remarks This method returns the browser object—which is itself the enumerator.



QueueBrowser.MoveNextMethod

Declaration bool MoveNext();

Purpose Advance the browser’s enumeration to the next message.

Remarks A browser is a dynamic enumerator of the queue (not a static snapshot). The queue is at the server, and its contents change as message arrive and consumers remove them. Meanwhile, while the browser is at the client. This method asks the server for the next message after Current—that is, the next message that is still in the queue.

Returns true if another message exists; the Current property subsequently presents the next message.

Returns false otherwise.

After creating a browser, programs must first call this method to examine the first message.


QueueBrowser.Reset | 207

QueueBrowser.ResetMethod


Purpose Reset the browser to the location before the first message.




| 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


210 | Chapter 11 Name Server Lookup

ILookupContextInterface

Declaration interface ILookupContext

Purpose The initial context used to look up administered objects in either an EMS server or a third-party LDAP server.

Remarks ILookupContext is implemented by the LookupContext and LdapLookupContext classes. LookupContext is mainly used to lookup up JMS administered objects in the TIBCO EMS server, whereas LdapLookupContext is used for looking up JMS administered objects in an LDAP server.

Users obtain an object of type ILookupContext (implemented by LookupContext and LdapLookupContext) by calling the LookupContextFactory.CreateContext method.


Member Description

Settings System.Collections.Hashtable Settings {get;}

Return the current settings of this lookup context.


ILookupContext.AddSettings Add settings to the lookup context. 211

ILookupContext.Lookup Lookup up an object by name in an LDAP or TIBCO EMS Naming server.

212

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


ILookupContext.AddSettings | 211

ILookupContext.AddSettingsMethod

Declaration object AddSettings(string propName, object propValue);

void AddSettings(Hashtable table);

Purpose Add settings to the lookup context.

Remarks You can add settings to the lookup context by either passing a hash table or a property/value pair.

Setting added to the lookup context are mainly LDAP or TIBCO EMS Naming Server related parameters used for looking up objects stored in an LDAP server or TIBCO EMS Server. Examples of setting names include LDAP_SERVER_URL or LDAP_BASE_DN.

Examples To add settings contained in a hash table:

Hashtable table = new Hashtable();LookupContextFactory contextFactory =

new LookupContextFactory();ILookupContext searcher = contextFactory.Create("ldap", table); searcher.AddSettings(table);

To add settings directly:

Hashtable table = new Hashtable();LookupContextFactory contextFactory =

new LookupContextFactory();ILookupContext searcher = contextFactory.Create("ldap", table); searcher.AddSettings(LdapLookupConsts.LDAP_SERVER_URL,

"adc1.na.tibco.com:10389");


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.



ILookupContext.LookupMethod

Declaration object Lookup(string name);

Purpose Lookup up an object by name in an LDAP or TIBCO EMS Naming server.

Remarks This method looks up an object in either an LDAP or TIBCO EMS Naming server, depending on which interface is asked for in the LookupContextFactory.

Ldap related information

If the context initialized is LDAP context, the Lookup method initializes the LDAP connection environment; searches for the object in the LDAP server; constructs the object, and the returns the object.

At a very high level, the lookup function performs a set of tasks for an LDAP context:

• Initializes the ldap connection environment, performs various checks to make sure the right parameters are passed in.

• Establishes a LDAP connection to the specified server

• Searches for the specified object in the LDAP server

• Once it receives the XML data for the specified administered object, it performs XML validation (i.e.) through the specified DTD.

• Retrieves the object properties stored as XML.

• Constructs the object and then returns the object.

Example This example demonstrates how to lookup a connection factory object in an LDAP server:

LookupContextFactory contextFactory = new LookupContextFactory();ILookupContext searcher = contextFactory.Create("ldap", table); ConnectionFactory cf =

(ConnectionFactory)searcher.Lookup("cn='testConnFact");


name Name of the object to lookup.


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.



ILookupContext.RemoveSettingsMethod

Declaration object RemoveSettings(string propName);

Purpose Remove a lookup context setting by name.

Example Add and then remove the LDAP_SERVER_URL property from the lookup context:

Hashtable table = new Hashtable();table.Add(LdapLookupConsts.LDAP_SERVER_URL,

"adc1.na.tibco.com:10389");LookupContextFactory contextFactory = new LookupContextFactory();ILookupContext searcher = contextFactory.CreateContext(

"ldap", table); searcher.RemoveSettings(LdapLookupConsts.LDAP_SERVER_URL);


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


LookupContext | 215

LookupContextClass

Declaration class LookupContext

Purpose Search for and perform queries on administered objects in the EMS server.

Remarks The context object establishes communication with the EMS server, authenticates the user, and submits name queries.

The following is a list of properties used to connect to an EMS server and specifying the search scope for looking up EMS administered objects. See LdapLookupConsts on page 224 for the properties related to establishing a lookup context for a third-party LDAP server.

Member Description

Properties

Settings System.Collections.Hashtable {get;}

Programs can get a copy of the context’s current settings.

Fields

Programs use these constants as names of context settings (in argument hashtables or individually).

PROVIDER_URL string

URL of the naming server (EMS server).

SECURITY_CREDENTIALS string

User password of the client program.

SECURITY_PRINCIPAL string

User name of the client program.

URL_LIST string

ArrayList of URLs of naming servers (EMS servers).

This property lets programs specify URLs as an ArrayList, rather than as a string (as with PROVIDER_URL).



URL_SEPARATOR string

Syntactic separator between URLs in the PROVIDER_URL.

Member Description


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


LookupContext | 217

LookupContextConstructor

Declaration LookupContext(Hashtable prop );

LookupContext();

Purpose Create a new lookup context object.

Remarks The first constructor sets properties of the new context object.

The second constructor creates a context without property settings.


prop Set all the name-value pairs contained in this hash table.



LookupContext.AddSettingsMethod

Declaration virtual object AddSettings(string propName,object propValue );

virtual void AddSettings(Hashtable prop );

Purpose Add or change the lookup context settings.

Remarks The first method sets one property. If the property was previously set, the method modifies it and returns the old value.

The second method sets multiple properties defined in a hash table.







LookupContext.Lookup | 219

LookupContext.LookupMethod

Declaration virtual object Lookup(string name );

Purpose Lookup an object in the naming server.

Remarks Returns the named object, if the server finds it.

If the server does not find the object, this method throws NamingException.

Example Hashtable env = new Hashtable();env.Add(LookupContext.PROVIDER_URL,

"tibjmsnaming://localhost:7222");env.Add(LookupContext.SECURITY_PRINCIPAL", "myUserName");env.Add(LookupContext.SECURITY_CREDENTIALS", "myPassword");try {

LookupContext searcher = new LookupContext(env);TIBCO.EMS.Queue queue =

(TIBCO.EMS.Queue)searcher.Lookup("theQueueName");...

} catch (NamingException) {...

}

Throws AuthenticationException on page 308NamingException on page 322ServiceUnavailableException on page 325


name Lookup this name.



LookupContext.RemoveSettingsMethod

Declaration virtual object RemoveSettings(string propName );

Purpose Remove a context setting.


propName Remove this property.



LookupContextFactory | 221

LookupContextFactoryClass

Declaration class LookupContextFactory

Purpose Create ILookupContext objects.

Remarks To lookup administered objects in either a third-party LDAP naming server or the TIBCO EMS Naming server, clients create an instance of the LookupContextFactory and invoke the LookupContextFactory.CreateContext method to get an ILookupContext object.

Member Description

Fields

Programs use these constants as names of context settings (in argument hashtables or individually).

LDAP_CONTEXT string

Ldap context to lookup administered object in an ldap server.

TIBJMS_NAMING_CONTEXT string

tibjmsnaming context to lookup administered object inside the tibjmsnaming server.


LookupContextFactory Create a lookup context factory. 222

LookupContextFactory.CreateContext Returns the initial context used to search for administered objects

222



LookupContextFactoryConstructor

Declaration LookupContextFactory();

Purpose Create a lookup context factory.

LookupContextFactory.CreateContextMethod

Declaration ILookupContext CreateContext(String name, Hashtable props);

Purpose Returns the initial context used to search for administered objects

Remarks This method returns an ILookupContext object that is the initial context used to look up administered object in the EMS server or an LDAP server. The currently supported contexts are tibjmsnaming and ldap.

Before calling CreateContext, first create a hash table of properties and their values.

Examples This example demonstrates how to create an initial context for looking up a queue object in the EMS naming server:

Hashtable env = new Hashtable();env.Add(LookupContext.PROVIDER_URL,

"tibjmsnaming://localhost:7222");env.Add(LookupContext.SECURITY_PRINCIPAL", "myUserName");env.Add(LookupContext.SECURITY_CREDENTIALS", "myPassword");

LookupContextFactory factory = new LookupContextFactory();ILookupContext searcher = factory.CreateContext(


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.


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



LdapLookupConstsClass

Declaration abstract class LdapLookupConsts

Purpose Specifies the parameters used to connect to a third-party LDAP server and lookup EMS administered objects.

Remarks The LDAP Lookup Constants are mainly to specify parameters to connect to an LDAP server and specify search scope with the LDAP server for looking up EMS administered objects.

See LookupContext on page 215 for the parameters used looking up administered objects in the EMS server.

Member Description

LDAP_BASE_DN Specifies the base DN, which is where to start looking for the administered objects.

LDAP_CERT_NAME Specifies the certificate name. This is required property when the LDAP_CONN_TYPE of ldaps is used and LDAP_SSL_PARAMS is not specified with a LdapLookupSSLParams.SetSSLQueryClientCertificateCal

lback method.

LDAP_CERT_STORE_LOCATION Specifies the store location, acceptable values are "currentuser" (the default) and "localmachine."

LDAP_CERT_STORE_NAME Specifies the store name. The default is "My" (i.e personal) store at the "currentuser" location.

LDAP_CONN_TYPE Specifies the connection type. The acceptable values are "ldap" (the default) and "ldaps".

LDAP_CREDENTIAL Specifies the credential (i.e the password) to use while connecting to the LDAP server.

LDAP_PRINCIPAL Specifies the principal (for example, the user name) to use while connecting to the ldap server.

LDAP_SEARCH_SCOPE Specifies the search scope. The acceptable values are "subtree" (the default) and "onelevel."

LDAP_SERVER_URL Specifies the url for the connection to the LDAP server.


LdapLookupConsts | 225

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

Member Description



LdapLookupContextClass

Declaration class LdapLookupContext

Purpose Interface used to search for and perform queries on EMS administered objects in a third-party LDAP server.

Member Description

Settings System.Collections.Hashtable Settings {get;}

Return a copy of the current settings.


LdapLookupContext.AddSettings Add or change the lookup context settings. 227

LdapLookupContext.Lookup Lookup up an EMS administered object by name in an LDAP server.

228

LdapLookupContext.RemoveSettings Remove a setting by name. 228


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.



For property names, see LdapLookupConsts on page 224.





LdapLookupContext.Lookup

Declaration object Lookup(string name)

Purpose Lookup up an EMS administered object by name in an LDAP server.

Remarks This is an implementation of ILookupContext.Lookup. The administered objects can be either EMS connection factories, topics, queues stored in a third-party LDAP server.

When looking up administered SSL connection factory objects, because of differences in the .NET ssl implementation and java/c ssl implementation, certain parameters are ignored.

The following values are supported.

• Expected hostname is converted to targethostName

• SSL client identity (only pkcs12 file)

• SSL password for the private key in the pkcs12 file

• SSL trace

• SSL trusted

The following (not complete) is the list of values ignored when constructing the ssl connection factory object:

• ssl verify host

• ssl vendor

• ssl verify host name

Lookup of XA connection factories is not supported.


name Lookup this name.


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.



LdapLookupContext.RemoveSettings

Declaration object RemoveSettings string propName);

Purpose Remove a setting by name.

Remarks Implements ILookupContext.RemoveSettings

Throws ArgumentException if the property name is null.


propName Remove this property.

For property names, see LdapLookupConsts on page 224.


LdapLookupSSLParams | 231

LdapLookupSSLParamsClass

Declaration class LdapLookupSSLParams

Purpose Provides the query client certificate callback and the server verify callback used to establish an SSL connection to the LDAP server (ldaps).

Remarks The parameters set by this object are optional. The client may choose to either specify the store location along with the store name and certificate name, or optionally the query client certificate callback.

LdapLookupSSLParamsConstructor

Declaration LdapLookupSSLParams();

Purpose Create a LDAP lookup SSL Parameters object.


LdapLookupSSLParams Create a LDAP lookup SSL Parameters object. 231

LdapLookupSSLParams.SetSSLQueryCl

ientCertificateCallback

Set the query client certificate callback to be invoked during the SSL handshake with the LDAP server.

232

LdapLookupSSLParams.SetSSLVerifyS

erverCertificateCallback

Set the server certificate verify callback to be invoked during the SSL handshake with the ldap server.

232



LdapLookupSSLParams.SetSSLQueryClientCertificateCallback

Declaration public void SetSSLQueryClientCertificateCallback(QueryClientCertificateCallback callback);

Purpose Set the query client certificate callback to be invoked during the SSL handshake with the LDAP server.

Remarks A query client certificate callback that gets invoked during the ssl handshake with the ldap server, allowing the user to specify a client certificate to be used for ssl handshake.

LdapLookupSSLParams.SetSSLVerifyServerCertificateCallback

Declaration public void SetSSLVerifyServerCertificateCallback(VerifyServerCertificateCallback callback);

Purpose Set the server certificate verify callback to be invoked during the SSL handshake with the ldap server.

Remarks A server certificate verify callback if set gets invoked during the ssl handshake with the ldap server. If this is not specified then the client will trust any server


callback The query client certificate callback.


callback The server certificate verify callback.


| 233




| 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


236 | Chapter 12 SSL Support

EMSSSLClass

Declaration class EMSSSL

Purpose Sets and gets the SSL parameters that apply across all connections.

Remarks Normally a client application obtains SSL setup as a part of the ConnectionFactory definition. A ConnectionFactory is usually obtained by the client applications via JNDI lookup calls. Alternatively, the client can use the EMSSSL class to define SSL parameters locally rather than from the ConnectionFactory. This may be necessary, for example, due to security considerations when JNDI lookup operation cannot be performed securely over SSL protocol. The EMSSSL class allows you to set SSL parameters globally so they apply to all the connections.

A EMS client communicates with the server via SSL protocol when the server URL provided to the ConnectionFactory is specified in the form ssl://host:port.

When the connection between the client and the server is an SSL connection, the server and the client application must set parameters in order for the SSL handshake to be successful. The server parameters are set by the administrator. Each client application is responsible for setting SSL parameters correctly in order to be able to establish an SSL connection to the server.

Setting up SSL parameters by the client can be done in one of three ways:

• All SSL parameters are specified in the ConnectionFactory, which either can be created dynamically by the client or obtained via a JNDI lookup call. Notice this does not address an issue of making JNDI lookup calls over SSL connection.

• SSL parameters are set globally via calls to this class. When a ConnectionFactory is using a URL specifying 'ssl' protocol but does not specify any other SSL parameters, the SSL parameters set via calls to the methods of this class will be used.

• A client application can create a Map of SSL parameters and pass it directly into constructor of TopicConnectionFactory or QueueConnectionFactory.


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.



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.


Integer defining PKCS7 format.


Integer defining PKCS8 format of the private key data.


EMSSSL | 239

HOST_NAME_VERIFIER string HOST_NAME_VERIFIER = "TIBCO.EMS.ssl.hostname_verifier";

Name of SSL property specifying the custom host name verifier. Notice when this property is specified, the Map of parameters can not be stored in JNDI. The value is a EMSSSLHostNameVerifier object. This name is defined as "TIBCO.EMS.ssl.hostname_verifier".

IDENTITY string IDENTITY = "TIBCO.EMS.ssl.identity";

Name of SSL property specifying the client-side identity. An identity usually consists of the certificate, corresponding private key and optionally a set of issuer certificates. The value specified by this property can be a certificate, a PKCS12 file, a KeyStore object or an Entrust Store. Last three object types normally include all elements of the identity into a single storage. In this case only PASSWORD property should be specified as the password required to decrypt the content of the specified identity data. If this property specifies the certificate file then PRIVATE_KEY must be also set and optionally ISSUER_CERTIFICATES. This name is defined as "TIBCO.EMS.ssl.identity".

PASSWORD string PASSWORD = "TIBCO.EMS.ssl.password";

Name of SSL property specifying the password for the private key or the identity store. The value is a java.lang.String object or char[]. This name is defined as "TIBCO.EMS.ssl.password".

STORE_INFO string STORE_INFO = "TIBCO.EMS.ssl.store_info";

SSL Store Info

STORE_TYPE string STORE_TYPE = "TIBCO.EMS.ssl.store_type";

SSL Store type

TARGET_HOST_NAME string TARGET_HOST_NAME = "TIBCO.EMS.ssl.target_host_name";

TRACE

Member Description



TRUSTED_CERTIFICATES string TRUSTED_CERTIFICATES = "TIBCO.EMS.ssl.trusted_certs";

Name of SSL property specifying the set of trusted certificates. The value is a Vector object, elements of the Vector can be: - certificate object, - an Integer object specifying the certificate type followed by the certificate object. An Integer object before the object presenting the certificate data may be required when certificate data does not allow automatic detection of the encoding format. This name is defined as "TIBCO.EMS.ssl.trusted_certs".

Member Description


EMSSSL.GetAuthOnly Get the value of the AUTH_ONLY flag. 241

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

241

EMSSSL.GetHostNameVerifier Returns currently set custom host name verifier. 241

EMSSSL.GetTargetHostName Returns the name set target host name. 241

EMSSSL.Initialize Initializes SSL environment. 242

EMSSSL.SetAuthOnly Enable or disable AUTH_ONLY on the client side.

242

EMSSSL.SetCertificateStoreType Set the store type for all the connection factories. 243

EMSSSL.SetClientTracer Set client tracer to given output stream. 244

EMSSSL.SetHostNameVerifier Set the custom host name verifier. 244

EMSSSL.SetTargetHostName Set the target host name. 245


EMSSSL.GetAuthOnly | 241

EMSSSL.GetAuthOnlyMethod

Declaration static bool GetAuthOnly();

Purpose Get the value of the AUTH_ONLY flag.

Remarks Returns true for enabled and false for disabled.

See Also EMSSSL.SetAuthOnly on page 242

EMSSSL.GetClientTracerMethod

Declaration static StreamWriter GetClientTracer();

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

EMSSSL.GetHostNameVerifierMethod

Declaration static EMSSSLHostNameVerifier GetHostNameVerifier();

Purpose Returns currently set custom host name verifier.

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

EMSSSL.GetTargetHostNameMethod

Declaration static string GetTargetHostName();

Purpose Returns the name set target host name.



EMSSSL.InitializeMethod

Declaration static void Initialize();

Purpose Initializes SSL environment.

Remarks Normally SSL environment is initialized automatically when creating the first SSL connection. If SSL environment has been already initialized this method does nothing.

EMSSSL.SetAuthOnlyMethod

Declaration static void SetAuthOnly(bool flag);

Purpose Enable or disable AUTH_ONLY on the client side.

Remarks For the client and server to require an SSL connection only to perform authentication, the ssl_auth_only parameter needs to be set on the server and AUTH_ONLY needs to be set by the client. Setting these flags on both the server and client side indicates that the SSL connection is only used to only perform authentication. Once authentication is complete, the client switches to a regular TCP connection to communicate with the server.

See the SSL Authentication Only section in the TIBCO Enterprise Message Service User’s Guide for details.

See Also EMSSSL.GetAuthOnly on page 241ConnectionFactory.SetSSLAuthOnly on page 156


flag True = enabled.

False = disabled.


EMSSSL.SetCertificateStoreType | 243

EMSSSL.SetCertificateStoreTypeMethod

Declaration static void SetCertificateStoreType(EMSSSLStoreType type,object storeInfo

);

Purpose Set the store type for all the connection factories.


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.



EMSSSL.SetClientTracerMethod

Declaration static void SetClientTracer(StreamWriter tracer);

Purpose Set client tracer to given output stream.

.Remarks Client tracing prints loaded certificates and information about the SSL handshake errors and results.

EMSSSL.SetHostNameVerifierMethod

Declaration static void SetHostNameVerifier(EMSSSLHostNameVerifier verifier);

Purpose Set the custom host name verifier.


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


verifier Host name verifier. Set to null to remove custom host name verifier.

See EMSSSLHostNameVerifier on page 255 for details.


EMSSSL.SetTargetHostName | 245

EMSSSL.SetTargetHostNameMethod

Declaration static void SetTargetHostName(string hostname);

Purpose Set the target host name.

Remarks This is a required parameter for all .NET SSL connections. Because System.Net.Security.SslStream requires a target host, this value is required.


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.



EMSSSLFileStoreInfoClass

Declaration class EMSSSLFileStoreInfo;

Purpose Specifies the file store information

Remarks The File Store Info object sets the store for a connection factory via the ConnectionFactory.SetCertificateStoreType method or while using the global EMSSSL API to set the certificate store. The store info consists of the client's identity (the only type supported is the pkcs12 file aka .pfx file format), the SSL password for the private key stored in the pkcs12 file and any optional trusted certificates.



EMSSSLFileStoreInfo Create a new File Store Info object.

247

EMSSSLFileStoreInfo.ClearTrustedCerts Remove all previously set trusted certificates.

247

EMSSSLFileStoreInfo.SetSSLClientIdentity Set the client identity. 248

EMSSSLFileStoreInfo.SetSSLPassword Set private key password. 249

EMSSSLFileStoreInfo.SetSSLTrustedCertificate Add a certificate to the list of trusted certificates.

250


EMSSSLFileStoreInfo | 247

EMSSSLFileStoreInfoConstructor

Declaration EMSSSLFileStoreInfo();

Purpose Create a new File Store Info object

EMSSSLFileStoreInfo.ClearTrustedCertsMethod

Declaration void ClearTrustedCerts();

Purpose Remove all previously set trusted certificates.



EMSSSLFileStoreInfo.SetSSLClientIdentityMethod

Declaration void SetSSLClientIdentity(X509Certificate certificate);

void SetSSLClientIdentity(string clientIdentity);

Purpose Set the client identity.

Remarks Overloaded. The only file type that is supported here is a pkcs12 or .pfx file. NOTE: If other file format are specified then a configuration exception will be thrown during the SSL handshake.

To set the Client Identity as a string:

public void SetSSLClientIdentity(clientId);

To set Client Identity as a X509 Certificate, use:

void SetSSLClientIdentity(X509Certificate);


certificate A pkcs12 or .pfx file used to identify the client.

clientIdentity The X509 Certificate used to identify the client.


EMSSSLFileStoreInfo.SetSSLPassword | 249

EMSSSLFileStoreInfo.SetSSLPasswordMethod

Declaration void SetSSLPassword(char[] password);

Purpose Set private key password.


password The SSL Password.



EMSSSLFileStoreInfo.SetSSLTrustedCertificateMethod

Declaration void SetSSLTrustedCertificate(X509Certificate certificate);

void SetSSLTrustedCertificate(string certificate);

Purpose Add a certificate to the list of trusted certificates.

Remarks Only ASN1.DER encoded files are supported.


certificate The name of the certificate to add to the list of trusted certificates.


EMSSSLSystemStoreInfo | 251

EMSSSLSystemStoreInfoClass

Declaration class EMSSSLSystemStoreInfo

Purpose Specifies the system store information.

Remarks The System Store Info object sets the store for a connection factory via the ConnectionFactory.SetCertificateStoreType method or while using the global EMSSSL API to set the certificate store. The store info consists of the store location, store name, the certificate name (to look for in the specified store name at the specified store location).

The default store location is StoreLocation.CurrentUser and the default store name is 'my' store as defined by the .NET framework. The search criteria to find the certificate in the store name at the store location is X509FindType.FindBySubjectDistinguishedName.


EMSSSLSystemStoreInfo Creates an object of type system store info.

252

EMSSSLSystemStoreInfo.SetCertificateName Set the name of the certificate.

253

EMSSSLSystemStoreInfo.SetCertificateStoreLocation Set location of the certificate store.

254

EMSSSLSystemStoreInfo.SetCertificateStoreName Set the certificate store name. 254



EMSSSLSystemStoreInfoConstructor

Declaration EMSSSLSystemStoreInfo();

Purpose Creates an object of type system store info.

Remarks This object is used mainly to specify system store information when the store type of SYSTEM is used by the ConnectionFactory.SetCertificateStoreType method.

See Also ConnectionFactory.SetCertificateStoreType on page 144


EMSSSLSystemStoreInfo.SetCertificateName | 253

EMSSSLSystemStoreInfo.SetCertificateNameMethod

Declaration void SetCertificateName(string certName);

Purpose Set the name of the certificate.

Remarks This method sets the name of the certificate. The certificate name is the subject distinguished name of the certificate. During the SSL handshake, the server searches for the named certificate in the store specified by EMSSSLSystemStoreInfo.SetCertificateStoreName at the location specified by EMSSSLSystemStoreInfo.SetCertificateStoreLocation.

Throws ArgumentException if the certificate name is null.

See Also EMSSSLSystemStoreInfo.SetCertificateStoreName on page 254 EMSSSLSystemStoreInfo.SetCertificateStoreLocation on page 254

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


certName Certificate name.



EMSSSLSystemStoreInfo.SetCertificateStoreLocationMethod

Declaration void SetCertificateStoreLocation(StoreLocation storeLocation);

Purpose Set location of the certificate store.

Remarks The certificate store location indicates where to lookup the certificate by name. If no store name is specified, then the default store name is "My" store name within this store location.

EMSSSLSystemStoreInfo.SetCertificateStoreNameMethod

Declaration void SetCertificateStoreName(string storeName);

Purpose Set the certificate store name.

Remarks This is the name of the store in which certificates are stored. During the SSL handshake, this is where the client library looks for the certificates.

Throws ArgumentException if the store name is null.


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


storeName Name of the certificate store.


EMSSSLHostNameVerifier | 255

EMSSSLHostNameVerifierDelegate

Declaration delegate bool EMSSSLHostNameVerifier(object sender,EMSSSLHostNameVerifierArgs args

);

Purpose Delegate declaration for host name verifier.

Remarks The user can perform any necessary specific validations in the host name verifier delegate, returning false will cause the SSL handshake to terminate, returning true will cause the SSL handshake to continue.



sender The source of the event.

args The event argument, EMSSSLHostNameVerifierArgs.



EMSSSLHostNameVerifierArgsClass

Declaration class EMSSSLHostNameVerifierArgs : EventArgs

Purpose Specifies the host name verifier arguments.

Remarks The user is handed off an EMSSSLHostNameVerifierArgs object as part of the host name verifier event callback, LdapLookupSSLParams.SetSSLVerifyServerCertificateCallback.

Member Description

m_certificateCommonName string m_certificateCommonName;

The certificate CN name should be same as the target host name.

m_connectedHostName string m_connectedHostName;

The host name to which the client is connected.

m_targetHostName string m_targetHostName;

The target host name, which is the server certificate CN name.

m_serverCertificate X509Certificate m_serverCertificate;

The server's certificate.

m_x509Chain X509Chain m_x509Chain;

The server certificate's chain.


EMSSSLStoreType | 257

EMSSSLStoreTypeEnumeration

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.




| 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


260 | Chapter 13 Utilities

DeliveryModeClass

Declaration class DeliveryMode

Purpose Backward compatibility. Define delivery mode constants as integers.

Remarks The class MessageDeliveryMode defines a parallel set of constants as .NET enumerated values (instead of ordinary integers). We recommend the enumeration over these ordinary integer values, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.

Member Description

Fields

NON_PERSISTENT int

Non-persistent delivery.

PERSISTENT int

Persistent delivery.

RELIABLE_DELIVERY int

Reliable delivery mode is a TIBCO proprietary extension that offers increased performance of the message producers. See also RELIABLE_DELIVERY in TIBCO Enterprise Message Service User’s Guide.


IEMSSerialziable | 261

IEMSSerialziableInterface

Declaration interface IEMSSerialzable

Purpose Customize serialization and deserialization of objects.

.NET CompactFramework

This interface is available only in .NET Compact Framework. Programmers can use it to allow otherwise excluded objects within an ObjectMessage.

Remarks When an object class implements this interface, it can be serialized within an ObjectMessage.

To implement this interface for a class, define the methods listed below and a constructor that does not require any arguments.

See Also ObjectMessage on page 48


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

IEMSSerialziable.Serialize Serialize an object. 263



IEMSSerialziable.DeserializeMethod

Declaration void Deserialize(System.IO.Stream stream );

Purpose Deserialize a data stream to reconstruct an object.

Remarks When this method is called, the stream already contains context information. That context information resides before the write position of the stream when this method is called (call it initWritePos). Your implementation of this method must not modify that context information, nor reset the stream’s write pointer to a position before initWritePos.

Similarly, your implementation must not close the stream.


stream Deserialize the data from this stream to reconstruct an object.


IEMSSerialziable.Serialize | 263

IEMSSerialziable.SerializeMethod

Declaration void Serialize(System.IO.Stream stream );

Purpose Serialize an object.

Remarks When this method is called, the stream already contains context information. That context information resides before the write position of the stream when this method is called (call it initWritePos). Your implementation of this method must not modify that context information, nor reset the stream’s write pointer to a position before initWritePos.

Similarly, your implementation must not close the stream.


stream Serialize the object’s data to this stream.



MessageDeliveryModeEnumeration

Declaration enum MessageDeliveryMode

Purpose Define enumerated delivery mode constants.

Remarks The class DeliveryMode defines a parallel set of constants as ordinary integers. However, we recommend this enumeration, because it enables .NET to do stronger type checking at compile time, which can enhance program reliability.

Member Description

NonPersistent Non-persistent delivery.

Persistent Persistent delivery.

ReliableDelivery Reliable delivery mode is a TIBCO proprietary extension that offers increased performance of the message producers. See also RELIABLE_DELIVERY on page 26 in TIBCO Enterprise Message Service User’s Guide.


Tibems | 265

TibemsClass

Declaration class Tibems

Purpose Define constants and utility methods specific to EMS.

Constant Description

Connection-Related Fields (Constants)

Programs can use these constants as names of settings in the hash table argument to ConnectionFactory.CreateConnection. They govern the behavior of the resulting connections that the factory creates.

DEFAULT_FACTORY_PASSWORD string

Defines the name of a ConnectionFactory property. That property specifies a default user password for the connections that the factory creates.

If the client does not supply a password, the connection factory object uses this password as a default when creating a connection. See also ConnectionFactory.CreateConnection on page 142.

DEFAULT_FACTORY_USERNAME string

Defines the name of a ConnectionFactory property. That property specifies a default username for the connections that the factory creates.

If the client does not supply a username, the connection factory object uses this username as a default when creating a connection. See also ConnectionFactory.CreateConnection on page 142.

FACTORY_LOAD_BALANCE_METRIC string

This field defines the name of a provider-specific ConnectionFactory property. That property governs the assignment of client connections among a set of load-balanced servers.

For property values, see QueueConnectionFactory on page 161.



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.



Tibems | 267

JMS_TIBCO_MSG_TRACE string

Defines the name of a provider-specific message property. Programs may set that property before sending a message to request trace data at significant events during the lifetime of the message. See also JMS_TIBCO_MSG_TRACE on page 16.

JMS_TIBCO_PRESERVE_UNDELIVERED string

Defines the name of a provider-specific message property. Programs may set that property before sending a message to request that the server hold it in a special queue if the server cannot deliver it. See also JMS_TIBCO_PRESERVE_UNDELIVERED on page 16.

JMS_TIBCO_SENDER string

Defines the name of a provider-specific message property. When a destination requests it, the server stores the username of the message producer in that property. See also JMS_TIBCO_SENDER on page 16.

JMS_TIBCO_SS_SENDER string

Defines the name of a provider-specific message property. The server sets that property when importing a message from TIBCO SmartSockets; its value is the SmartSockets sender name. See also JMS_TIBCO_SS_SENDER on page 16.



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

270

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

Tibems.GetAllowCloseInCallback Determine whether client callbacks may call close methods.

272

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



Tibems.GetConnectAttempts Return the connection attempts setting. 274

Tibems.GetConnectAttemptTimeout Returns the connect attempt timeout value. 275

Tibems.GetConnectionActiveURL Return the URL of the EMS server for the specified connection.

276

Tibems.GetEncoding Return the global character encoding for messages.

277

Tibems.GetExceptionOnFTSwitch Return the fault tolerance exception setting. 278

Tibems.GetMessageEncoding Return the character encoding for an individual message.

279

Tibems.GetMessageSize

(and related methods)Return the size of a wire format message—or its body, header or properties portions.

280

Tibems.GetPingInterval Return the interval at which the client tests network connectivity.

281

Tibems.GetProperty Return a property value. 282

Tibems.GetReconnectAttempts Return the reconnection attempts setting. 284

Tibems.GetReconnectAttemptTimeout Returns the reconnect attempt timeout value. 285

Tibems.GetSessionDispatcherDaemon Return the dispatcher thread setting. 286

Tibems.GetSocketReceiveBufferSize Return the size of socket receive buffers. 287

Tibems.GetSocketSendBufferSize Return the size of socket send buffers. 288

Tibems.MakeWriteable Make a message writable. 289

Tibems.SetAllowCloseInCallback Override a JMS requirement so client callbacks may call close methods.

290

Tibems.SetConnectAttempts Modify the connection attempts setting. 291

Tibems.SetConnectAttemptTimeout Set the maximum amount of time a client will wait for the connection to be established.

292

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



Tibems | 269

Tibems.SetExceptionOnFTSwitch Modify the fault tolerance exception setting. 294

Tibems.SetMessageEncoding Set the character encoding for an individual message.

295

Tibems.SetPingInterval Set the interval at which the client tests network connectivity.

296

Tibems.SetProperty Modify a property value. 297

Tibems.SetReconnectAttempts Modify the reconnection attempts setting. 299

Tibems.SetReconnectAttemptTimeout Sets the maximum amount of time a client will wait for the reconnect to complete.

300

Tibems.SetSessionDispatcherDaemon Set the dispatcher thread setting. 301

Tibems.SetSocketReceiveBufferSize Set the size of socket receive buffers. 302

Tibems.SetSocketSendBufferSize Set the size of socket send buffers. 303




Tibems.CalculateMessageSizeMethod

Declaration static int CalculateMessageSize(Message msg );

Purpose Returns the total size (in bytes) of a message in wire format.

Remarks The total size includes headers, properties and body.

This method re-measures the message, and caches the results; contrast Tibems.GetMessageSize.

This method might consume process storage, and might involve disk I/O—with associated performance penalties.

See Also Tibems.GetMessageSize on page 280


msg Compute the size of this message.


Tibems.CreateFromBytes | 271

Tibems.CreateFromBytesMethod

Declaration static Message CreateFromBytes(byte[] bytes );

Purpose Create a message from a byte array.

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

See Also Tibems.GetAsBytes on page 273Tibems.MakeWriteable on page 289


bytes Fill the new message with this byte array.

This byte array must be the result of previously calling Tibems.GetAsBytes.



Tibems.GetAllowCloseInCallbackMethod

Declaration static bool GetAllowCloseInCallback();

Purpose Determine whether client callbacks may call close methods.

Remarks According to the JMS specification, close methods (that is, MessageConsumer.Close, Session.Close, Connection.Close) cannot return while any message callbacks (that is, EMSMessageHandler, IMessageListener.OnMessage) are running. As a result, a message callback must not call a close method, lest it cause a deadlock.

Tibems.SetAllowCloseInCallback explicitly overrides this JMS requirement, permitting callbacks to call close without deadlock (that is, embedded close calls do not wait for callbacks to return).

See Also Tibems.SetAllowCloseInCallback on page 290

This method replaces the deprecated method GetAllowCallbackInClose.


Tibems.GetAsBytes | 273

Tibems.GetAsBytesMethod

Declaration static byte[] GetAsBytes(Message message );

Purpose Copy a message into a byte array.

Remarks The byte array includes the message headers, properties and body.

See Also Tibems.CreateFromBytes on page 271


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



Tibems.GetConnectAttemptsMethod

Declaration static string GetConnectAttempts();

Purpose Return the connection attempts setting.

Remarks This setting governs all client Connection objects as they attempt to connect to the server. Its value is a string of the form attempts or attempts,delay:

• attempts limits the number of times that the connection object attempts to establish a connection to the server. When this property is absent, the default value is 2. The minimum value is 1.

• delay is the time (in milliseconds) between connection attempts. When absent, the default value is 500. The minimum value is 250.

This method returns the string argument to Tibems.SetConnectAttempts—not the numeric value of the setting. If the client has not set a value, this method returns the null string.

See Also Tibems.SetConnectAttempts on page 291


Tibems.GetConnectAttemptTimeout | 275

Tibems.GetConnectAttemptTimeoutMethod

Declaration static int GetConnectAttemptTimeout();

Purpose Returns the connect attempt timeout value.

See Also Tibems.SetConnectAttemptTimeout on page 292

Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide



Tibems.GetConnectionActiveURLMethod

Declaration static String GetConnectionActiveURL(Connection connection);

Purpose Return the URL of the EMS server for the specified connection.

Remarks The server URL is returned as a String.


connection The connection to the EMS server.


Tibems.GetEncoding | 277

Tibems.GetEncodingMethod

Declaration static string GetEncoding();

Purpose Return the global character encoding for messages.

Remarks If the global encoding has not been set, this method returns null.

Programs can override the global encoding for individual messages. When neither a global nor an individual message encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.

This encoding applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The methods BytesMessage.ReadUTF and BytesMessage.WriteUTF are exempt from global and individual encoding settings.

See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.SetEncoding on page 293Tibems.GetMessageEncoding on page 279Tibems.SetMessageEncoding on page 295



Tibems.GetExceptionOnFTSwitchMethod

Declaration static bool GetExceptionOnFTSwitch();

Purpose Return the fault tolerance exception setting.

Remarks This setting determines exception behavior when the client successfully switches to a different server (fault-tolerant failover).

• When true, the connection’s ExceptionListener catches an EMSException, which contains the name of the new server.

• When false, fault-tolerant failover does not trigger an exception in the client.

See Also IExceptionListener on page 133Tibems.SetExceptionOnFTSwitch on page 294


Tibems.GetMessageEncoding | 279

Tibems.GetMessageEncodingMethod

Declaration static string GetMessageEncoding(Message message );

Purpose Return the character encoding for an individual message.

Remarks If the encoding has not been set for the individual message, this method returns null.

This encoding for an individual message overrides the global encoding. When neither a global nor an individual encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.


See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.GetEncoding on page 277Tibems.SetEncoding on page 293Tibems.SetMessageEncoding on page 295


message Get the encoding for this message.



Tibems.GetMessageSizeMethod

Declaration static int GetMessageSize(Message msg );

static int GetMessageBodySize(Message msg );

static int GetMessageHeadersSize(Message msg );

static int GetMessagePropertiesSize(Message msg );

Purpose Return the size of a wire format message—or its body, header or properties portions.

Remarks These four methods return cached values for the size of a message or its parts.

The sizes are implicitly measured and cached when an inbound message arrives at the client, and when the client sends an outbound message. If the client modifies a message, or creates a message but never sends it, then these methods could yield incorrect cached values. To explicitly force a new measurement and cache its results, call Tibems.CalculateMessageSize; then these methods yield correct values.

GetMessageSize returns the total size of a message—that is, the number of bytes that traverse the network when the client sends the message. This total is slightly larger than the sum of its three constituent parts, because it includes additional control information. Furthermore, the server adds its own control information as well, so the size of message as measured by receivers is slightly larger than its size as measured by the sender.

See Also Tibems.CalculateMessageSize on page 270


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


Tibems.GetPingInterval | 281

Tibems.GetPingIntervalMethod

Declaration static int GetPingInterval();

Purpose Return the interval at which the client tests network connectivity.

Remarks Clients test network connectivity by sending ping requests to the server at regular intervals. This method returns that interval (in seconds). Zero is a special value that disables ping testing.

See Also Tibems.SetPingInterval on page 296



Tibems.GetPropertyMethod

Declaration static object GetProperty(string key );

Purpose Return a property value.

Remarks If the property is not set, this method returns null.

In .NET, methods exist to get and set the properties. GetProperty provides an alternate way to get property values, which is consistent with the EMS Java API (for easy porting to .NET).


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


Tibems.GetProperty | 283

See Also Tibems.SetProperty on page 297

PROP_PING_INTERVAL Tibems.GetPingInterval on page 281

Tibems.SetPingInterval on page 296

PROP_FT_SWITCH Tibems.GetExceptionOnFTSwitch on page 278

Tibems.SetExceptionOnFTSwitch on page 294

PROP_MESSAGE_ENCODING Tibems.GetMessageEncoding on page 279

Tibems.SetMessageEncoding on page 295

PROP_DAEMON_DISPATCHER Tibems.GetSessionDispatcherDaemon on page 286

Tibems.SetSessionDispatcherDaemon on page 301




Tibems.GetReconnectAttemptsMethod

Declaration static string GetReconnectAttempts();

Purpose Return the reconnection attempts setting.

Remarks This setting governs all client Connection objects as they attempt to reconnect to the server after a network disconnect. Its value is a string of the form attempts or attempts,delay:

• attempts limits the number of times that the connection object attempts to reestablish a connection to the server. When this property is absent, the default value is 4. The minimum value is 1.

• delay is the time (in milliseconds) between reconnection attempts. When absent, the default value is 500. The minimum value is 250.

This method returns the string argument to Tibems.SetReconnectAttempts—not the numeric value of the setting. If the client has not set a value, this method returns the null string.

See Also Tibems.SetReconnectAttempts on page 299


Tibems.GetReconnectAttemptTimeout | 285

Tibems.GetReconnectAttemptTimeoutMethod

Declaration static int GetReconnectAttemptTimeout();

Purpose Returns the reconnect attempt timeout value.

See Also Tibems.SetReconnectAttemptTimeout on page 300

Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.



Tibems.GetSessionDispatcherDaemonMethod

Declaration static bool GetSessionDispatcherDaemon();

Purpose Return the dispatcher thread setting.

Remarks When a program uses asynchronous message consumers (either message listeners or .NET message event handler delegates), EMS creates internal dispatcher threads for each Session that has at least one asynchronous message consumer. When this setting is true, those dispatcher threads are daemon threads; when false (the default) they are not daemon threads.


The .NET Compact Framework does not support daemon threads. This call always returns false.

See Also Tibems.SetSessionDispatcherDaemon on page 301


Tibems.GetSocketReceiveBufferSize | 287

Tibems.GetSocketReceiveBufferSizeMethod

Declaration static int GetSocketReceiveBufferSize();

Purpose Return the size of socket receive buffers.

Remarks When set, this value overrides the operating system’s default for the size of receive buffers associated with sockets that the client uses for connections to the server. (Some operating systems do not allow you to override the default size.)

See Also Tibems.SetSocketReceiveBufferSize on page 302



Tibems.GetSocketSendBufferSizeMethod

Declaration static int GetSocketSendBufferSize();

Purpose Return the size of socket send buffers.

Remarks When set, this value overrides the operating system’s default for the size of send buffers associated with sockets that the client uses for connections to the server. (Some operating systems do not allow you to override the default size.)

See Also Tibems.SetSocketSendBufferSize on page 303


Tibems.MakeWriteable | 289

Tibems.MakeWriteableMethod

Declaration static void MakeWriteable(Message message);

Purpose Make a message writable.

See Also MessageNotWriteableException on page 320


message Make this message writable.



Tibems.SetAllowCloseInCallbackMethod

Declaration static void SetAllowCloseInCallback(bool allow );

Purpose Override a JMS requirement so client callbacks may call close methods.

Remarks According to the JMS specification, close methods (that is, MessageConsumer.Close, Session.Close, Connection.Close) cannot return while any message callbacks (that is, EMSMessageHandler, IMessageListener.OnMessage) are running. As a result, a message callback must not call a close method, lest it cause a deadlock.

This method explicitly overrides this JMS requirement, permitting callbacks to call close without deadlock (that is, embedded close calls do not wait for callbacks to return).

See Also Tibems.GetAllowCloseInCallback on page 272


allow When true, EMS overrides the JMS specification.

When false (the default), EMS obeys the JMS specification.

This method replaces the deprecated method SetAllowCallbackInClose.


Tibems.SetConnectAttempts | 291

Tibems.SetConnectAttemptsMethod

Declaration static void SetConnectAttempts(string specs );

Purpose Modify the connection attempts setting.

Remarks This setting governs all client Connection objects as they attempt to connect to the server.

See Also Tibems.GetConnectAttempts on page 274


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.



Tibems.SetConnectAttemptTimeoutMethod

Declaration static void SetConnectAttemptTimeout(int timeout

);

Purpose Set the maximum amount of time a client will wait for the connection to be established.

Remarks When too many clients connect to the same server, the server may not be able to accept all connections at the same time or may run out of system resources. This method specifies the amount of time a client is willing to wait for a connection to be established. Internally the client library will tear down any hung connections (either because of non-availability of system resources or some other EMS server problem) after the timeout period has elapsed.

See Also Tibems.SetReconnectAttemptTimeout on page 300Tibems.GetConnectAttemptTimeout on page 275

Setting Connection Attempts, Timeout and Delay Parameters in the TIBCO Enterprise Message Service User’s Guide


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


Tibems.SetEncoding | 293

Tibems.SetEncodingMethod

Declaration static void SetEncoding(string encodingName );

Purpose Set the global string encoding for messages.

Remarks Programs can override the global encoding for individual messages. When neither a global nor an individual message encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.

This encoding applies to all strings in message body fields (names and values), and properties (names and values). It does not apply to message header fields. The methods BytesMessage.ReadUTF and BytesMessage.WriteUTF are exempt from global and individual encoding settings.

See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.GetEncoding on page 277Tibems.GetMessageEncoding on page 279Tibems.SetMessageEncoding on page 295

The only encoding names supported by the .NET client are the ones defined by the .NET framework. Please refer to the .NET framework documentation for a complete list of the supported encoding names.


encodingName The name of the encoding (for example, "utf-8").

An EMSException is generated if the encoding is not supported.




Tibems.SetExceptionOnFTSwitchMethod

Declaration static void SetExceptionOnFTSwitch(bool callExceptionListener );

Purpose Modify the fault tolerance exception setting.

Remarks This setting determines exception behavior when the client successfully switches to a different server (fault-tolerant failover).

See Also IExceptionListener on page 133Tibems.GetExceptionOnFTSwitch on page 278


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.


Tibems.SetMessageEncoding | 295

Tibems.SetMessageEncodingMethod

Declaration static void SetMessageEncoding(Message messagestring encodingName );

Purpose Set the character encoding for an individual message.

Remarks This encoding for an individual message overrides the global encoding. When neither a global nor an individual message encoding has been set, then EMS encodes the strings of an outbound message using the default UTF-8 encoding.


See Also BytesMessage.Read on page 34BytesMessage.Write on page 37Tibems.GetEncoding on page 277Tibems.SetEncoding on page 293Tibems.GetMessageEncoding on page 279


message Set the encoding for this message.

encodingName Set this encoding.




Tibems.SetPingIntervalMethod

Declaration static void SetPingInterval(int seconds );

Purpose Set the interval at which the client tests network connectivity.

Remarks Clients test network connectivity by sending ping requests to the server at regular intervals. This method sets that interval (in seconds). If your program calls this method, it must do so before creating its first Connection object; after creating that object, this call has no effect.

See Also Tibems.GetPingInterval on page 281


seconds Ping at this interval (in seconds).

Zero is a special value that disables ping testing.


Tibems.SetProperty | 297

Tibems.SetPropertyMethod

Declaration static void SetProperty(string key,object val );

Purpose Modify a property value.

Remarks In .NET, methods exist to get and set the properties. SetProperty provides an alternate way to set property values, which is consistent with the EMS Java API (for easy porting to .NET).


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.


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



See Also Tibems.GetProperty on page 282

PROP_PING_INTERVAL Tibems.GetPingInterval on page 281

Tibems.SetPingInterval on page 296

PROP_FT_SWITCH Tibems.GetExceptionOnFTSwitch on page 278

Tibems.SetExceptionOnFTSwitch on page 294

PROP_MESSAGE_ENCODING Tibems.GetMessageEncoding on page 279

Tibems.SetMessageEncoding on page 295

PROP_DAEMON_DISPATCHER Tibems.GetSessionDispatcherDaemon on page 286

Tibems.SetSessionDispatcherDaemon on page 301



Tibems.SetReconnectAttempts | 299

Tibems.SetReconnectAttemptsMethod

Declaration static void SetReconnectAttempts(string specs );

Purpose Modify the reconnection attempts setting.

Remarks This setting governs all client Connection objects as they attempt to reconnect to the server after a network disconnect.

See Also Tibems.GetReconnectAttempts on page 284


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.



Tibems.SetReconnectAttemptTimeoutMethod

Declaration static void SetReconnectAttemptTimeout(int timeout

);

Purpose Sets the maximum amount of time a client will wait for the reconnect to complete.

Remarks This method is similar to Tibems.SetConnectAttemptTimeout. However, during the initial connect of the clients to the server, the time for each connect attempt is normally distributed and there are less chances of the server exceeding its maximum accept queue. During a fault-tolerant switch, all of the clients automatically try to reconnect to the backup server at approximately the same time. When the number of connections is large, it may require more reconnect time to reconnect than the initial connect.

See Also Tibems.SetConnectAttemptTimeout on page 292Tibems.GetReconnectAttemptTimeout on page 285

Setting Reconnection Failure Parameters in the TIBCO Enterprise Message Service User’s Guide.


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


Tibems.SetSessionDispatcherDaemon | 301

Tibems.SetSessionDispatcherDaemonMethod

Declaration static void SetSessionDispatcherDaemon(bool makeDaemon );

Purpose Set the dispatcher thread setting.

Remarks When a program uses asynchronous message consumers (either message listeners or .NET message event handler delegates), EMS creates internal dispatcher threads for each Session that has at least one asynchronous message consumer. When this setting is true, those dispatcher threads are daemon threads; when false (the default) they are not daemon threads.


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

See Also Tibems.GetSessionDispatcherDaemon on page 286


makeDaemon • When true, dispatcher threads are daemon threads.

• When false, (the default) they are not daemon threads



Tibems.SetSocketReceiveBufferSizeMethod

Declaration static void SetSocketReceiveBufferSize(int size );

Purpose Set the size of socket receive buffers.

Remarks This value overrides the operating system’s default for the size of receive buffers associated with sockets that the client uses for connections to the server.

Use this call before creating server connections. This call sets an override buffer size for new socket buffers; it does not change the size of existing socket buffers.


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

See Also Tibems.GetSocketReceiveBufferSize on page 287


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


Tibems.SetSocketSendBufferSize | 303

Tibems.SetSocketSendBufferSizeMethod

Declaration static void SetSocketSendBufferSize(int size );

Purpose Set the size of socket send buffers.

Remarks This value overrides the operating system’s default for the size of send buffers associated with sockets that the client uses for connections to the server.

Use this call before creating server connections. This call sets an override buffer size for new socket buffers; it does not change the size of existing socket buffers.


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

See Also Tibems.GetSocketSendBufferSize on page 288


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




| 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


306 | Chapter 14 Exception

EMSExceptionClass

Declaration class EMSException : System.Exception

Purpose Root of exceptions specific to EMS.

Origin Corresponds to JMSException in JMS.

Remarks EMS methods throw instances of this class and its subclasses.

Subclasses EMSExceptionIllegalStateExceptionInvalidClientIDExceptionInvalidDestinationExceptionInvalidSelectorExceptionMessageEOFExceptionMessageFormatExceptionMessageNotReadableExceptionMessageNotWriteableExceptionNamingException

AuthenticationExceptionCannotProceedExceptionCommunicationExceptionConfigurationExceptionInvalidNameExceptionNameNotFoundExceptionServiceUnavailableException

ResourceAllocationExceptionSecurityExceptionTransactionInProgressExceptionTransactionRolledBackException

Member Description

Properties

ErrorCode string {get;}

When an exception results from a server error, this property holds the server’s error code.

LinkedException System.Exception {get; set;}

When an EMS exception results from a deeper problem, this linked exception details that problem.


EMSException | 307

Constructors EMSException (string reason );

EMSException (string reason,string errorCode );



AuthenticationExceptionClass

Declaration class AuthenticationException : NamingException

Purpose Invalid authentication or insufficient privileges for a lookup request.



CannotProceedException | 309

CannotProceedExceptionClass

Declaration class CannotProceedException : NamingException

Purpose Insufficient information to resolve a lookup request.

Remarks A destination lookup request found both a queue and a topic with the specified name. To resolve this situation, specify the destination name in one of these forms:

• $topic:<topic-name>

• $queue:<queue-name>




CommunicationExceptionClass

Declaration class CommunicationException : NamingException

Purpose A lookup request returned bad data.

Remarks This exception could indicate a version mismatch between the client and tibemsd.



ConfigurationException | 311

ConfigurationExceptionClass

Declaration class ConfigurationException : NamingException

Purpose Configuration error associated with a lookup context object.

Remarks When the client initialized the lookup context, some parameter values were missing or invalid.




IllegalStateExceptionClass

Declaration class IllegalStateException : EMSException

Purpose A method call or server request occurred in an inappropriate context.

Origin JMS.

Remarks For example, Session.Commit throws this exception when the session is non-transactional.


InvalidClientIDException | 313

InvalidClientIDExceptionClass

Declaration class InvalidClientIDException : EMSException

Purpose The provider rejects the connection’s client ID.

Origin JMS.

Remarks Setting a connection’s client ID to an invalid or duplicate value results in this exception. (A duplicate value is one that is already in use by another connection.)



InvalidDestinationExceptionClass

Declaration class InvalidDestinationException : EMSException

Purpose tibemsd cannot locate the destination.

Origin JMS.


InvalidNameException | 315

InvalidNameExceptionClass

Declaration class InvalidNameException : NamingException

Purpose In a lookup request, the name has incorrect syntax.

Remarks The most common syntax error is a prefix other than tibjmsnaming:// (or a misspelling).




InvalidSelectorExceptionClass

Declaration class InvalidSelectorException : EMSException

Purpose The client passed a message selector with invalid syntax.

Origin JMS.

See Also Message Selectors on page 18


MessageEOFException | 317

MessageEOFExceptionClass

Declaration class MessageEOFException : EMSException

Purpose The data stream within a message ended unexpectedly.

Origin JMS.

Remarks BytesMessage contains a stream of bytes. StreamMessage contains a stream of characters. If any of their read methods detects the end of the stream unexpectedly, it throws this exception.



MessageFormatExceptionClass

Declaration class MessageFormatException : EMSException

Purpose Datatype mismatch.

Origin JMS.

Remarks For example:

• A read method cannot read the data with the specified type.

• A write method cannot store the data in the message or property because the data has the wrong type.


MessageNotReadableException | 319

MessageNotReadableExceptionClass

Declaration class MessageNotReadableException : EMSException

Purpose Attempt to read from a message in write-only mode.

Origin JMS.



MessageNotWriteableExceptionClass

Declaration class MessageNotWriteableException : EMSException

Purpose Attempt to write to a message in read-only mode.

Origin JMS.

See Also Tibems.MakeWriteable on page 289


NameNotFoundException | 321

NameNotFoundExceptionClass

Declaration class NameNotFoundException : NamingException

Purpose The name lookup repository cannot find a name; the name is not bound.




NamingExceptionClass

Declaration class NamingException : EMSException

Purpose Root of exceptions related to name lookup requests.

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

Subclasses NamingExceptionAuthenticationExceptionCannotProceedExceptionCommunicationExceptionConfigurationExceptionInvalidNameExceptionNameNotFoundExceptionServiceUnavailableException


Member Description

Properties

RootCause System.Exception {get; set;}

When a naming exception results from a more general problem, this exception details that problem.


ResourceAllocationException | 323

ResourceAllocationExceptionClass

Declaration class ResourceAllocationException : EMSException

Purpose Required resources are not available.

Origin JMS.



SecurityExceptionClass

Declaration class SecurityException : EMSException

Purpose The method cannot complete because of a security restriction.

Origin JMS.

Remarks For example, the provider rejects a user or the user’s authentication.


ServiceUnavailableException | 325

ServiceUnavailableExceptionClass

Declaration class ServiceUnavailableException : NamingException

Purpose A lookup request failed because the client could not connect to the server.




TransactionInProgressExceptionClass

Declaration class TransactionInProgressException : EMSException

Purpose Reserved for future use.

Origin JMS.

Remarks When a session uses an XA transaction manager, the XA resource is the correct locus for all commit and rollback requests. Local commit or rollback calls are not permitted, and throw this exception.


TransactionRolledBackException | 327

TransactionRolledBackExceptionClass

Declaration class TransactionRolledBackException : EMSException

Purpose An attempt to commit a transaction resulted in rollback.

Origin JMS.




| 329

Index

A

Acknowledge 25AuthenticationException 308

B

body types, message 9BodyLength 32BytesMessage 32

Read methods 34ReadBytes 36Reset 40Write methods 37WriteBytes 39

C

CalculateMessageSize 270CannotProceedException 309character encoding 4, 277, 279, 293, 295ClearBody 26ClearProperties 26Clone 26Close

Connection 121MessageConsumer 82MessageProducer 97QueueBrowser 204QueueRequestor 110Session 176TopicRequestor 114

Commit 177CommunicationException 310Compact Framework 5

compression 3ConfigurationException 311Connection 118

Close 121CreateSession 122Start 123Stop 124

ConnectionConsumer (not supported) 3ConnectionFactory 138

constructor 141CreateConnection 142

ConnectionMetaData 125conversion, data type 21CreateBrowser 178CreateBytesMessage 179CreateConnection 142CreateConsumer 180CreateDurableSubscriber 181CreateFromBytes 271CreateMapMessage 183CreateObjectMessage 184CreateProducer 185CreateQueue 186CreateQueueConnection 162CreateQueueSession 127CreateSession 122CreateStreamMessage 187CreateTemporaryQueue 188CreateTemporaryTopic 189CreateTextMessage 190CreateTopic 191CreateTopicConnection 165CreateTopicSession 129customer support xvii


330 | Index

D

daemon threads 3data type conversion 21Delete

TemporaryQueue 73TemporaryTopic 75

DeliveryMode 260Deserialize 262Destination 69

overview 66durable subscription

unsubscribe 195dynamic destination 66

E

EMSException 306EMSExceptionEventArgs 131

constructor 132EMSExceptionHandler 130EMSMessageEventArgs 88

constructor 89Message 88

EMSMessageHandler 87encoding, character 4, 277, 279, 293, 295exceptions 305

F

FactoryLoadBalanceMetric 167fault tolerance

ActiveURL 119failover exceptions 278, 294

FieldCountMapMessage 41StreamMessage 50

G

GetMapMessage 44message properties 28

GetAllowCloseInCallback 272GetAsBytes 273GetConnectAttempts 274GetConnectAttemptTimeout 275GetDeliveryModeName 27GetEncoding 277GetEnumerator 205GetExceptionOnFTSwitch 278GetMessageBodySize 280GetMessageEncoding 279GetMessageHeadersSize 280GetMessageSize 280GetPingInterval 281GetProperty, Tibems 282GetReconnectAttempts 284GetReconnectAttemptTimeout 285GetSessionDispatcherDaemon 286GetSocketReceiveBufferSize 287GetSocketSendBufferSize 288

H

headers, message 10

I

IEMSSerialziable 261Deserialize 262Serialize 263

IExceptionListener 133OnException 134

IllegalStateException 312IMessageListener 90

OnMessage 91InvalidClientIDException 313InvalidDestinationException 314


Index | 331

InvalidNameException 315InvalidSelectorException 316ItemExists 45

L

Lookup 219LookupContext 210, 215

AddSettingsAddSettings 218

constructor 217Lookup 219RemoveSettings 220

M

MakeWriteable 289MapMessage 41

FieldCount 41Get methods 44ItemExists 45MapNames 41set methods 46SetBytes 47

MapNames 41Message 22

Acknowledge 25body types 9BodyLength 32ClearBody 26ClearProperties 26Clone 26EMSMessageEventArgs 88get property methods 28GetDeliveryModeName 27headers 10parts of 8properties 15PropertyExists 29set property methods 30ToString 31

messageselectors 18

MessageConsumer 80Close 82MessageHandler 80MessageListener 80MessageSelector 81Receive 83ReceiveNoWait 84

MessageDeliveryMode 264MessageEOFException 317MessageFormatException 318MessageHandler 80MessageListener 80MessageNotReadableException 319MessageNotWriteableException 320MessageProducer 94

Close 97Send 98

MessageProducer.Close 97MessageProducer.Send 98MessageSelector 81MoveNext 206

N

NameNotFoundException 321NamingException 322.NET Compact Framework 5NoLocal 86

O

object serialization 3ObjectMessage 48

constructor 49TheObject 48

OnException 134OnMessage 91


332 | Index

P

property, message 15get 28set 30

PropertyExists 29Publish 104

Q

Queue 70constructor 71QueueName 70QueueReceiver 85

QueueBrowser 202Close 204GetEnumerator 205MoveNext 206Reset 207

QueueConnection 126CreateQueueSession 127

QueueConnectionFactory 161CreateQueueConnection 162

QueueName 70QueueReceiver 85

Queue 85QueueRequestor 108

Close 110constructor 109Request 111

QueueSender 100Send 101

QueueSender.Send 101QueueSession 196

R

ReadBytesMessage 34StreamMethod 53

ReadBytesBytesMessage 36StreamMessage 54

read-only 26, 40, 55, 271, 320Receive 83ReceiveNoWait 84Recover 192RemoveSettings 220Request

QueueRequestor 111TopicRequestor 115

request 10Reset

BytesMessage 40QueueBrowser 207StreamMessage 55

ResourceAllocationException 323Rollback 193Run (obsolete) 194

S

SecurityException 324selectors, message 18Send

MessageProducer 98QueueSender 101

serializable object interface 261serialization 3Serialize 263ServerSession (not supported) 3ServerSessionPool (not supported) 3ServiceUnavailableException 325


Index | 333

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

SessionMode 198Set

MapMessage 46message property 30

SetAllowCloseInCallback 290SetBytes 47SetConnectAttempts 291SetConnectAttemptTimeout 292SetEncoding 293SetExceptionOnFTSwitch 294SetMessageEncoding 295SetPingInterval 296SetProperty, Tibems 297SetReconnectAttempts 299SetReconnectAttemptTimeout 300SetSessionDispatcherDaemon 301SetSocketReceiveBufferSize 302SetSocketSendBufferSize 303SSL 3Start 123static destination 66Stop 124

StreamMessage 50FieldCount 50Read methods 53ReadBytes 54Reset 55Write methods 56WriteBytes 57

string and character encoding 4support, contacting xvii

T

technical support xviitemporary destination 66TemporaryQueue 72

Delete 73TemporaryTopic 74

Delete 75Text 58TextMessage 58

constructor 59Text 58

TheObject 48


334 | Index

Tibems 265CalculateMessageSize 270CreateFromBytes 271GetAllowCloseInCallback 272GetAsBytes 273GetConnectAttempts 274GetConnectAttemptTimeout 275GetEncoding 277GetExceptionOnFTSwitch 278GetMessageBodySize 280GetMessageEncoding 279GetMessageHeadersSize 280GetMessageSize 280GetPingInterval 281GetProperty 282GetReconnectAttempts 284GetReconnectAttemptTimeout 285GetSessionDispatcherDaemon 286GetSocketReceiveBufferSize 287GetSocketSendBufferSize 288MakeWriteable 289SetAllowCloseInCallback 290SetConnectAttempts 291SetConnectAttemptTimeout 292SetEncoding 293SetExceptionOnFTSwitch 294SetMessageEncoding 295SetPingInterval 296SetProperty 297SetReconnectAttempts 299SetReconnectAttemptTimeout 300SetSessionDispatcherDaemon 301SetSocketReceiveBufferSize 302SetSocketSendBufferSize 303

tibemsd 138, 209Topic 76

constructor 77TopicName 76TopicSubscriber 86

TopicConnection 128CreateTopicSession 129

TopicConnectionFactory 164CreateTopicConnection 165

TopicName 76

TopicPublisher 103Publish 104

TopicPublisher.Publish 104TopicRequestor 112

Close 114constructor 113Request 115

TopicSession 197TopicSubscriber 86

NoLocal 86Topic 86

ToString 31TransactionInProgressException 326TransactionRolledBackException 327translation, character encoding 4type conversion 21

U

Unicode 4Unsubscribe 195

W

WriteBytesMessage 37StreamMessage 56

WriteBytesBytesMessage 39StreamMessage 57

X

XA (not supported) 3


Documents

Tib Ems Dotnet Ref